Authentication

The RocketReach MCP server uses OAuth 2.1 with PKCE and Dynamic Client Registration (DCR). MCP-compatible clients handle this flow automatically — you do not need to implement it yourself. This page documents the flow for developers building their own MCP clients or integrations.

How it works

The server exposes a standard OAuth discovery chain that compliant clients follow automatically:

1. Discovery — the client fetches /.well-known/oauth-protected-resource from the MCP server to learn the authorization server URL.
2. Authorization server metadata — the client fetches /.well-known/oauth-authorization-server from the authorization server (RocketReach) to discover all OAuth endpoints.
3. Dynamic Client Registration — the client registers itself by POSTing to /mcp-oauth/register and receives a client_id.
4. Authorization — the client redirects the user's browser to /mcp-oauth/authorize with a PKCE code_challenge.
5. User consent — the user logs into RocketReach and approves the access request.
6. Token exchange — the client exchanges the authorization code for an access token via POST /mcp-oauth/token.
7. API calls — the client sends Authorization: Bearer <token> on every request to POST /mcp.

Endpoints

Token format

Access tokens are JWE-wrapped JWTs (sign-then-encrypt). The outer envelope is AES-256-GCM (JWE); inside is an HS256-signed JWT (JWS) that carries standard claims (sub, aud, exp) plus RocketReach-specific claims including the API key. The inner JWS is signed, not encrypted, so the API key sits in plaintext inside it — the outer JWE envelope is what keeps these credentials confidential from intermediate parties.

Pass tokens as Bearer tokens:

Authorization: Bearer <access_token>

Tokens are bound to the MCP server URL — a token issued for mcp.rocketreach.co will be rejected by any other audience. The server validates the audience claim on every request.

Token lifetimes

Access tokens are short-lived by design. When one expires, compliant MCP clients automatically exchange the refresh token for a new access + refresh token pair via POST /mcp-oauth/token with grant_type=refresh_token. This happens transparently — users are not prompted to re-authorize unless the refresh token itself expires or is revoked.

Refresh tokens are single-use and rotate on each exchange. If a refresh token is presented after already being used, all tokens for that user+client are immediately revoked.

Token revocation

To disconnect an AI client or revoke a specific token:

POST https://rocketreach.co/mcp-oauth/revoke
Content-Type: application/x-www-form-urlencoded

token=<access_or_refresh_token>

Revoking a refresh token invalidates the access tokens issued from it.

Scopes

A single scope is used: rocketreach:read. Authorizing this grants access to all tools (search, lookup, account). Pass it in the scope parameter of the authorization request, or omit it — an empty scope defaults to rocketreach:read.

Custom client implementation notes

If you are building your own MCP client against the RocketReach OAuth endpoints:

• Generate a random state parameter before redirecting the user to /mcp-oauth/authorize. Verify the returned state matches on the callback. This is your CSRF defense for the OAuth flow — it is the client's responsibility, not the server's.
• Dynamic Client Registration is open per RFC 7591 — no pre-approval required. Register at POST /mcp-oauth/register.
• Redirect URIs are bound at registration. The redirect_uri on the authorize request must exactly match a URI registered for your client_id. Non-localhost redirects must use https://. http://localhost and http://127.0.0.1 on any port are allowed for native/desktop clients (RFC 8252).

Errors