OAuth 2.1 for MCP Clients
Connect Claude, IDEs, and agent runtimes to Token Vault with a standard in-client OAuth 2.1 flow — no pasted keys.
Token Vault is an OAuth 2.1 authorization server and protected resource for MCP — the MCP authorization spec's two server roles, co-located. Any client that speaks the spec (Claude Code, Claude.ai, ChatGPT, IDEs, agent runtimes) can connect to Token Vault's MCP endpoint and obtain an agent-scoped session token in-client — the human approves once in a browser, no static key is ever pasted.
claude mcp add --transport http token-vault https://api.tokenvault.uk/api/agents/mcp
# then inside Claude Code: /mcp → Authenticate → browser opens → pick agent → doneNew in July 2026
This gateway just shipped — read the announcement for the design rationale and what "beyond the MCP baseline" means in practice.
The client discovers everything else itself: it hits the MCP endpoint, gets a 401
pointing at the discovery documents, registers itself, and runs a PKCE authorization
code flow. You approve in the browser and pick which agent identity the client
binds to.
Standards
| Standard | Role | In the MCP auth spec |
|---|---|---|
| RFC 9728 | Protected resource metadata (/.well-known/oauth-protected-resource) | Required |
| RFC 8414 | Authorization server metadata (/.well-known/oauth-authorization-server) | Required |
| OAuth 2.1 + RFC 7636 | PKCE, S256 only — no client secrets, public clients only | Required (S256-only matches the 2025-11-25 hardening) |
| RFC 7591 | Dynamic client registration — no pre-shared client_id | Recommended — and ChatGPT's MCP connectors require it |
| RFC 7009 | Token revocation | Beyond the MCP baseline |
| RFC 7662 | Token introspection (bearer-as-subject) | Beyond the MCP baseline |
The flow
One identity, two token types
Access is always bound to a (user, agent) pair. There are two interchangeable ways
for a client to present that identity:
| Token | Issued by | Lifetime | Use when |
|---|---|---|---|
tvagent_… | Console (static API key) | Until revoked | Server-side agents you configure by hand |
tvsess_… | OAuth 2.1 flow | 1 hour, auto-refreshed via tvrefresh_… | MCP clients with a human in the loop |
Both resolve through the same code path to the same agent, with the same grants and ABAC policies. The auth method is orthogonal to what the agent can do.
Consent and the agent picker
The authorization endpoint is a page on the dashboard (tokenvault.uk/oauth/authorize).
You sign in with your normal account, then:
- Pick the agent the client should act as. Its grants and policies apply.
- If the agent doesn't have MCP access enabled yet, the page offers to enable it — a deliberate opt-in, recorded in your activity feed.
- Approve. The client gets its code on a loopback redirect and exchanges it for tokens.
Suspended agents can't be authorized, and every refresh re-checks the agent's status — suspending an agent kills its sessions at the next refresh, within the hour.
Kill switches
| Action | Effect |
|---|---|
| Suspend the agent | New sessions + refreshes refused immediately; live tvsess_ expires ≤ 1 h |
| Delete the agent | Same, permanently |
POST /api/mcp-oauth/revoke | Kills a specific tvsess_ or tvrefresh_ now |
ABAC time_window policy | Gate sessions by schedule — enforced on every call and surfaced via introspection |
Next steps
Endpoint Reference
Every endpoint with curl examples: discovery, register, authorize, token, revoke, introspect.
Introspection & Gateway Gating
Validate tvsess_ tokens from your own MCP gateway and honor Token Vault schedules.
Agents & Grants
What an agent is, how grants scope credential access, and the MCP tool surface.
Ready to try it?
Sign up free with Google — your credentials stay on your own webhook, and the quickstart gets an agent fetching its first credential in about ten minutes.