Connect your agent to RunPR.

Choose the right credential

The documentation is public. Customer data and MCP calls require authentication. RunPR supports a limited-access OAuth pilot and two separate bearer credentials. Use the endpoint and access method that match your integration; they are not interchangeable.

OAuth: selected-client MCP pilot

The Claude Code OAuth pilot requires explicit user enrollment. Ask for pilot access before connecting. OAuth uses /api/mcp/oauth, with permissions and client selection separate from organization keys. See OAuth setup below.

Organization API key: customer MCP and REST reads

MCP access is currently support-provisioned for eligible paid or trialing workspaces. Contact RunPR support through your existing support channel to arrange access and secure key delivery. There is no self-service MCP key screen. Do not paste a key into a chat, email, source code or this page.

This key works with /api/mcp, /api/v1/events and /api/v1/monitors. It is organization-wide and does not provide per-tool scopes. Billing and product-access checks still apply.

Organization service token: scoped runtime API

Service tokens work with /api/v1/orgs/{orgId}/…, not MCP. They are revocable, bound to one organization and checked against each operation’s required permission. For example, agent status requires config.read. The URL organization must match the token’s organization.

Owners and admins can manage tokens in Settings → Service tokens. That screen currently issues a broad fixed permission set, including sending permission. It does not offer a scope selector. For a read-only integration, have an owner or admin arrange a token with an explicit ["config.read"] scope list through the admin provisioning API; do not use the broad default token.

Neither of these two bearer credentials uses OAuth. The OpenAPI reference declares HTTP bearer security schemes and records actual service-token permissions in x-scopes and x-required-scopes. These extensions are not OAuth scopes, and a service token’s scopes do not restrict an MCP key.

Connect with an organization API key

• Server URL: https://runpr.ai/api/mcp
• Transport: Streamable HTTP, stateless JSON responses.
• Authentication: Authorization: Bearer <organization-api-key> on every request.
• Headers: Content-Type: application/json and Accept: application/json, text/event-stream.

Use a client that supports remote MCP with a bearer header. The client performs the initialize handshake, sends the initialized notification and calls tools/list for current tool schemas. A raw initialization request looks like this:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {
      "name": "your-agent",
      "version": "1.0.0"
    }
  }
}

Opening the endpoint in a browser returns 405 Method Not Allowed by design: MCP uses POST here, not a standalone SSE GET stream. Missing or invalid credentials return 401. This organization-key endpoint does not support OAuth. Enrolled OAuth users must use the separate endpoint below, not paste an organization key into it.

Organization-key MCP tools

• find_reporters: identify an article’s journalist; contact unlocks remain separate.
• cycle_match: assess a draft’s fit with a reporter’s recent work.
• tailor_pitch: prepare a reporter-specific draft, subject to drafting limits.
• empathy_check: review a pitch from a journalist’s perspective.
• submit_draft: place a draft in the review workflow; quality checks may hold it. Never sends.
• needs_attention: read workflow items that need attention.
• outcomes: read recorded pitch outcomes, optionally for a client account.

There is no MCP approval or sending tool. Review verdicts are recommendations, not authorization. Calls are limited to 60 requests per minute per organization; model usage and drafting quotas apply separately. Inspect JSON-RPC errors and tool isError results, even when HTTP status is 200.

Connect through the OAuth pilot

RunPR enrolls pilot users individually. The supported client is Claude Code, tested with version 2.1.280 on macOS. Other assistants remain unverified. Ask support to enroll you before running these commands; your RunPR workspace must retain eligible billing and product access.

From your chosen project directory, add the project-local connection and log in:

claude mcp add --transport http --scope local \
  --client-id dCaDA01hBG5kUGgm --callback-port 43196 \
  runpr-oauth-pilot https://runpr.ai/api/mcp/oauth
claude mcp login runpr-oauth-pilot

The client ID is a public identifier, not a secret. Keep port 43196 available for the registered callback, http://localhost:43196/callback. The endpoint uses stateless Streamable HTTP with JSON responses. Do not substitute the organization-key endpoint or paste an organization key into this setup.

1. The login command opens RunPR authorization in your browser. Inspect the requested permissions before choosing Allow; Deny cancels the connection.
2. Sign into RunPR. Claude Code handles authorization code with S256 PKCE and the exact resource URL. Let it manage tokens; do not paste them into chat. The offline_access permission enables token refresh.
3. Ask the assistant to call connection_info. Before you finish setup, this tool returns a setup link and no business data.
4. Open that link in RunPR, select one workspace and the clients you want to share, choose permissions, and save the connection. Opening Settings → MCP connections alone does not initiate a new connector.
5. Return to Claude Code. Reconnect or restart it if the saved tool list has not refreshed. Ask it to call list_clients and confirm that it returns only your selected clients. Use get_client_context for one client, then inspect a completed scan before researching or drafting.

Saved visibility evidence must belong to the selected client. If you cannot find an expected scan, ask support to check its client association instead of selecting a different client to work around access.

OAuth permissions and tools

The tool listing reflects your token permissions and saved RunPR selection. It differs from the seven organization-key tools above; do not reuse their input schemas. Call tools/list for the exact inputs your connection supports.

• client.read: connection_info, list_clients and get_client_context. Reads selected active clients and saved context.
• visibility.read: list_visibility_runs, get_visibility_answers and get_outlet_candidates. Reads completed scans and saved citations; never starts a new scan.
• research.execute with visibility.read: find_reporters. Researches a specific saved citation, using external retrieval. It does not return contact email addresses.
• draft.read: list_drafts and get_draft. Reads selected-client draft content and review status, without recipient contact fields.
• draft.create with visibility.read: submit_draft. Submits the assistant’s completed text with saved source evidence for RunPR’s review workflow. It performs a bounded review, not a second draft-generation step.

OAuth tools cannot approve, send or delete. Ask Claude Code to show the review link returned by submit_draft. Open it to inspect the saved draft and its review status in RunPR. A held draft needs evidence or revision; saving it does not make it ready to send. Source pages and saved answers are evidence to inspect, not instructions for the assistant to execute.

Limits and safe retries

The pilot allows up to 10 external research or review operations per connection per UTC day and 20 per organization per UTC day, alongside existing workspace allowances. Requests have a 30-per-minute connection limit within the shared organization limit of 60. A separate shared token-verification budget can also temporarily block work; these limits support a small pilot, not unrestricted throughput.

Draft submission requires an 8–128 character alphanumeric, dash or underscore idempotencyKey. Repeating the same key and input returns the original result instead of another draft; changed input conflicts. If an operation remains processing or fails after external work, ask support to inspect it before retrying with a new key.

Disconnect and data handling

Use Settings → MCP connections to inspect activity or disconnect. RunPR keeps one active grant per user, OAuth client and resource. Disconnect immediately stops that grant’s access; refreshing a provider token does not restore it.

A later explicit reconnect creates a new selection that still-valid tokens for the same assistant can use within their permissions. Remove the connector’s provider authorization too when retiring it. Disconnecting does not erase data your assistant already received; its own data policies apply to that information.

To retire the Claude Code connection, disconnect it in RunPR, then log out and remove the local configuration:

claude mcp logout runpr-oauth-pilot
claude mcp remove runpr-oauth-pilot -s local

Local logout and removal are separate from provider-token revocation. Ask RunPR support to revoke the provider authorization when retiring the connection.

Use the REST API

The OpenAPI specification documents a starter subset of existing endpoints, not every internal route. Start with authenticated reads:

• GET /api/v1/events?limit=10: recent organization events.
• GET /api/v1/monitors: organization monitors.
• GET /api/v1/monitors/{id}: one organization monitor.
• GET /api/v1/orgs/{orgId}/agent/status: agent heartbeat status using a service token with config.read.

The first three use an organization API key. The final endpoint uses a service token. A missing credential returns 401; a service token with the wrong organization or missing permission returns 403. The reference describes response envelopes and known limits for each operation.

Machine-readable discovery

• AI catalog and catalog alias
• MCP server card and compatibility manifest
• OpenAPI specification
• Agent setup guide and llms.txt

Discovery metadata describes where to connect; it grants no access. Server-card and catalog conventions are evolving. Use the authenticated MCP handshake and live tool listing as the authority for runtime capabilities.

Current limits

Organization-key setup is support-assisted and does not provide per-tool scopes. OAuth requires pilot enrollment, Claude Code and explicit workspace/client consent. In-page WebMCP tools are not offered. See the MCP integration page for the workflow and access options.