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
- Runs
claude mcp add --transport http your-app https://mcp.example.com/mcp, then chooses Authenticate. - Their browser opens your app. They sign in as usual, including their second factor.
- Your consent page shows which agent is asking and what it wants. They pick what to allow and press Allow.
- 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.
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.
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:
- Verify the token against your app's JWKS with issuer and audience (your resource URL, exactly) and check
typeisagent_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. - Ask
POST /{slug}/v1/agent-access/introspectwhether the connection is still live, and cache a positive answer for a few seconds at most, so Disconnect takes effect quickly. - Allow the call only if the scopes allow it and the user's current role does.
{
"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.
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
| Route | Credential | Purpose |
|---|---|---|
| GET /.well-known/oauth-authorization-server/{slug} | public | Discovery (RFC 8414). 404 while agent access is off. |
| POST /{slug}/oauth/register | public | Dynamic client registration (RFC 7591). Public clients only; https or localhost redirects. |
| GET /{slug}/oauth/authorize | browser | Validates the request (PKCE S256 required) and sends the browser to your consent page. |
| POST /{slug}/oauth/token | public | Authorization code and refresh token grants. Refresh tokens rotate on every use. |
| POST /{slug}/oauth/revoke | public | Token revocation (RFC 7009). |
| GET /{slug}/v1/agent-access/authorizations/{handle} | user's token | Your consent page reads the request. |
| POST …/authorizations/{handle}/approve | deny | user's token | The user decided. Answers the URL to send the browser to. |
| GET | DELETE /{slug}/v1/me/agent-grants | user's token | The user's connected agents, and Disconnect. |
| PUT | GET /{slug}/v1/agent-access/config | Platform API key | Turn it on: your MCP server URL, consent page and scopes. |
| POST /{slug}/v1/agent-access/introspect | Platform API key | Your MCP server checks a token is still live. |
| GET /{slug}/v1/agent-access/grants | Platform API key | Every user's connected agents, filtered by the context you stored (e.g. one workspace). |
| DELETE /{slug}/v1/agent-access/grants/{grant_id} | Platform API key | Disconnect anyone's agent, e.g. from a workspace owner's admin page. |
Security model
- PKCE with S256 is required;
plainand missing challenges are refused. - Redirect URIs match exactly, with one relaxation: any port on
localhost,127.0.0.1or[::1](RFC 8252), which native agents need. Plainhttpis 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 itsclient_idis 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.