MCP Server

Connect an agent to RepScale

The RepScale MCP server exposes 5 sales-research tools via the Model Context Protocol over HTTP. It runs at https://app.repscale.ai/api/mcp and authenticates via either OAuth 2.0 (recommended for end users) or an API key (recommended for backend agents and one-off scripts).

Quick start — Claude Desktop & other MCP clients

Most MCP clients can self-configure via OAuth. Add the server to your client's config using its URL — the client will discover authentication endpoints automatically and walk you through a sign-in + consent flow in your browser.

{
  "mcpServers": {
    "repscale": {
      "url": "https://app.repscale.ai/api/mcp"
    }
  }
}

On first call, the client will:

Hit /api/mcp and receive a 401 with a discovery pointer
Fetch /.well-known/oauth-protected-resource and the linked authorization-server metadata
Register itself dynamically (RFC 7591) and open a browser tab for you to approve
Exchange the auth code for an access token (PKCE / S256) and start calling tools

You can revoke the connection any time from Settings → Connected Agents.

Quick start — API key (programmatic agents)

For backend agents that don't have a browser, generate a long-lived API key. Same rate limits and quota as OAuth tokens; same tool surface.

Go to Settings → API Keys and click Generate Key
Copy the key (shown once)
Send it as Authorization: Bearer rsk_live_… on every request to /api/mcp

Available tools

Tool	What it does	Cost
`research_prospect`	Generates a structured brief for a B2B prospect — company snapshot, recent business signals, leadership context, contact-level insights. Cached 7 days per prospect.	1 of your daily research quota
`get_recommended_angle`	Returns the recommended sales angle for a brief — hook, pain, proof.	Free / cached
`explain_confidence`	Explains why a brief has its current confidence level and what would raise it.	Free / cached
`suggest_adjacent_research`	Suggests follow-up research the agent might want to do next based on what's in the brief.	Free / cached
`cite_source`	Returns the source citation for a specific claim made in a brief — the URL, retrieval date, and quote.	Free / cached

Call tools/listagainst the server for the full input schemas — they're always served fresh and machine-readable.

Rate limits & quota

Free plan: 1 research_prospect call per day. Follow-up tools are free.
Pro plan: 200 research_prospect calls per day (safety cap to catch runaway agent loops, not a plan restriction — contact support to raise).
Follow-up tools (everything except research): 120 calls per minute per credential, regardless of plan. Idempotent — cache results client-side rather than re-calling.

MCP usage shares the same daily counter as the web app. A research call from Claude Desktop counts the same as one from the RepScale web UI.

OAuth 2.0 endpoints

Implements MCP 2025-06-18 authorization. PKCE is required (S256 only). Resource Indicators (RFC 8707) are required on both /authorize and /token.

Resource metadata:
  https://app.repscale.ai/.well-known/oauth-protected-resource

Authorization server metadata:
  https://app.repscale.ai/.well-known/oauth-authorization-server

Endpoints:
  POST /api/oauth/register   (RFC 7591 Dynamic Client Registration)
  GET  /api/oauth/authorize  (Clerk-gated consent + PKCE challenge)
  POST /api/oauth/token      (auth_code + refresh_token grants)

Scopes:        mcp:tools
Access TTL:    1 hour
Refresh TTL:   30 days (rotated on every use)

Errors

Tool errors return as JSON-RPC result envelopes (not JSON-RPC errors), so agents can program against them. Every error has the same shape:

{
  "error": "daily_limit_reached",
  "message": "Daily research cap reached (1 per day on the Free tier).",
  "suggested_fix": "Wait for the daily reset at midnight UTC, or upgrade to Pro.",
  "retryable": false
}

Auth failures return HTTP 401 with a WWW-Authenticate header pointing at the resource metadata. OAuth-specific subcodes (error="invalid_token") signal whether the client should refresh and retry vs re-run discovery from scratch.

Support

Stuck? Email software@tbfatl.com with the timestamp of the failing call and the structured error body — that's enough to find the request in the server logs.