Core concepts
Core concepts

Agent access: let AI agents act for your users.

Your users connect Claude Code, or any MCP client, to your app with one command and approve it in their browser. The agent then calls your MCP server as that user, within what they allowed. Auth runs the OAuth 2.1 authorization server; you keep the consent page and the permission check.


What your user does

  1. Runs claude mcp add --transport http your-app https://mcp.example.com/mcp, then chooses Authenticate.
  2. Their browser opens your app. They sign in as usual, including their second factor.
  3. Your consent page shows which agent is asking and what it wants. They pick what to allow and press Allow.
  4. The browser hands back to the agent, which now has a token for your MCP server only.

No API key ends up in a config file, and the user can disconnect the agent at any time from a page in your app.


Who does what

  • Auth is the authorization server: discovery, client registration, PKCE, the authorization code, access tokens bound to your resource, rotating refresh tokens, revocation and the user's list of connected agents. Every grant, revocation and registration lands in your app's audit log.
  • Your app hosts the consent page (it already signs your users in) and the MCP server. The server checks each token, then applies the user's current role on every call, so an agent never does more than its user can do today.

1. Turn it on

Push the settings from your backend on boot with a Platform API key that holds auth.agent_access.configure on the app. The scopes are yours: name them after what your API does.

config
PUT https://api.auth.productcraft.co/{slug}/v1/agent-access/config
Authorization: Bearer pcft_live_…        # auth.agent_access.configure

{
  "enabled": true,
  "resources": ["https://mcp.example.com/mcp"],
  "consent_url": "https://app.example.com/oauth/consent",
  "scopes": [
    { "name": "projects:read",  "description": "Read your projects" },
    { "name": "projects:write", "description": "Change your projects" }
  ]
}

2. Your consent page

Auth sends the browser to consent_url?request=pcar_…. Sign the user in if needed, read the request with their own access token, and show it. When client.verified is true, show the client as verified: Auth has fetched its publisher's metadata document and vouches for it (Claude Code today). Otherwise the name is self-declared: say it is unverified. For every client show where the browser will return (redirect.host; loopback: true means “on this computer”). Isolate every value you place inside a sentence (the client name, the user's address, hosts) with <bdi>, so right-to-left text cannot reorder it. The first signed-in user to open a request is bound to it; anyone else gets 404. Requests live 10 minutes.

On Allow, approve with the scopes they kept and any context your server will need later (up to 2 KB, returned on introspection exactly as you sent it). Then send the browser to redirect_to.

approve
POST https://api.auth.productcraft.co/{slug}/v1/agent-access/authorizations/{handle}/approve
Authorization: Bearer <the signed-in user's access token>

{ "scopes": ["projects:read"], "context": { "workspace_ids": ["ws_123"] } }

→ 200 { "redirect_to": "http://localhost:53682/callback?code=…&state=…&iss=…", "grant_id": "agr_…" }

3. Your MCP server

Answer an unauthenticated request with 401 and WWW-Authenticate: Bearer resource_metadata="…", and serve the protected-resource metadata (RFC 9728) naming https://api.auth.productcraft.co/{slug} as the authorization server. For each request:

  1. Verify the token against your app's JWKS with issuer and audience (your resource URL, exactly) and check type is agent_access. An end-user session token has a different audience and type, so neither can stand in for the other. If any of your own APIs verify Auth tokens without checking the audience, fix that before turning agent access on.
  2. Ask POST /{slug}/v1/agent-access/introspect whether the connection is still live, and cache a positive answer for a few seconds at most, so Disconnect takes effect quickly.
  3. Allow the call only if the scopes allow it and the user's current role does.
access token claims
{
  "iss": "https://api.auth.productcraft.co/{slug}",
  "aud": "https://mcp.example.com/mcp",     // exactly your resource
  "sub": "<end user id>",
  "type": "agent_access", "token_use": "agent_access",
  "client_id": "pcac_…", "grant_id": "agr_…",
  "scope": "projects:read",
  "auth_time": 1794830400,                  // when the user approved
  "exp": …                                  // 15 minutes
}

4. Optional: an admin overview

Your admins may need to see every agent connected to their organisation and cut one off. List the app's connections with a Platform API key holding auth.agent_access.grants.manage, narrowed by the context you stored at approval (JSON containment), and disconnect any of them. Record in your own trail who asked; Auth records the revocation with reason app.

grants
GET https://api.auth.productcraft.co/{slug}/v1/agent-access/grants?context={"workspace_ids":["ws_123"]}
Authorization: Bearer pcft_live_…        # auth.agent_access.grants.manage

→ 200 { "data": [ { "id": "agr_…",
                    "account": { "id": "…", "username": "dana", "email": "dana@acme.com" },
                    "client": { "client_id": "https://claude.ai/oauth/claude-code-client-metadata",
                                "name": "Claude Code", "verified": true, "kind": "metadata_document" },
                    "scopes": ["projects:read"], "last_used_at": "…", … } ],
        "pagination": { "next_cursor": null, "has_more": false } }

Endpoints

RouteCredentialPurpose
GET /.well-known/oauth-authorization-server/{slug}publicDiscovery (RFC 8414). 404 while agent access is off.
POST /{slug}/oauth/registerpublicDynamic client registration (RFC 7591). Public clients only; https or localhost redirects.
GET /{slug}/oauth/authorizebrowserValidates the request (PKCE S256 required) and sends the browser to your consent page.
POST /{slug}/oauth/tokenpublicAuthorization code and refresh token grants. Refresh tokens rotate on every use.
POST /{slug}/oauth/revokepublicToken revocation (RFC 7009).
GET /{slug}/v1/agent-access/authorizations/{handle}user's tokenYour consent page reads the request.
POST …/authorizations/{handle}/approve | denyuser's tokenThe user decided. Answers the URL to send the browser to.
GET | DELETE /{slug}/v1/me/agent-grantsuser's tokenThe user's connected agents, and Disconnect.
PUT | GET /{slug}/v1/agent-access/configPlatform API keyTurn it on: your MCP server URL, consent page and scopes.
POST /{slug}/v1/agent-access/introspectPlatform API keyYour MCP server checks a token is still live.
GET /{slug}/v1/agent-access/grantsPlatform API keyEvery user's connected agents, filtered by the context you stored (e.g. one workspace).
DELETE /{slug}/v1/agent-access/grants/{grant_id}Platform API keyDisconnect anyone's agent, e.g. from a workspace owner's admin page.

Security model

  • PKCE with S256 is required; plain and missing challenges are refused.
  • Redirect URIs match exactly, with one relaxation: any port on localhost, 127.0.0.1 or [::1] (RFC 8252), which native agents need. Plain http is accepted only there.
  • Codes live 60 seconds and work once; a replayed code revokes what it issued. Access tokens live 15 minutes. Refresh tokens live 30 days and rotate on every use; presenting an old one revokes the whole connection. A connection ends after 90 days at the latest.
  • Clients identify themselves with a Client ID Metadata Document (the MCP spec's preferred way; Claude Code uses https://claude.ai/oauth/claude-code-client-metadata) or, as a fallback, by dynamic registration. Auth fetches a metadata document over https from public addresses only (no redirects, 5 KB, 5 seconds), checks that its client_id is its own URL and that the redirect is one it lists, and caches it for an hour. Only documents whose publisher Auth vouches for are verified; every self-registered client and every other document stays unverified.
  • Client names are stored without bidi control or invisible characters, so a name cannot reorder the sentence it is shown in.
  • Registration is limited to 10 clients an hour per address, and an app keeps at most 5,000 registered clients.
  • Deleting or suspending a user ends their agents' access at once.

In production

dispute.markets uses agent access for its MCP server. Its customers connect Claude Code with one command; see dispute.markets/docs/mcp.