MCP Proxy Endpoint
Reference for POST /api/proxy/mcp — proxy key auth forms, webhook credential injection, and the tv_session upstream auth type.
POST /api/proxy/mcp
The MCP proxy endpoint. An agent's MCP client points at a proxy URL; Token Vault authenticates the proxy key, evaluates ABAC policies, and forwards the request to your webhook's /v1/proxy with a signed ticket. Your webhook injects the real credential (substituting ${TOKEN} in your header templates) and calls the upstream service; Token Vault streams the response back but never sees the credential.
{
"mcpServers": {
"github": {
"url": "https://api.tokenvault.uk/api/proxy/mcp?key=mcp_…",
"headers": {}
}
}
}Authentication
The proxy's mcp_… key, one of three ways (checked in this order):
| Method | Example | Notes |
|---|---|---|
Authorization header | Authorization: Bearer mcp_… | Preferred |
x-mcp-key header | x-mcp-key: mcp_… | For clients that reserve Authorization |
?key= query param | ?key=mcp_… | Common in MCP client configs that can't set headers |
Keys are issued when you create a proxy in the dashboard, shown once, and revocable in one click.
Upstream auth types
| Type | Credential source | Path |
|---|---|---|
| Token (default) | A credential stored on your webhook | TV → webhook /v1/proxy → webhook injects and calls upstream |
tv_session | Token Vault's own session token (tvsess_…), auto-refreshed and bound to an agent | TV injects Authorization: Bearer tvsess_… and dials the upstream directly — no webhook hop, because the injected token is TV's own, not a stored credential |
tv_session is for gating your own MCP servers with Token Vault identities: your server validates the session via the introspection endpoint.
Behaviour notes
- Upstream
3xxresponses are not followed (the bearer must never leak to a redirect target). - Expired stored credentials are refreshed by your webhook before the upstream call — the agent never sees a 401.
- Policy denials return
403with the standardPOLICY_DENIEDbody. - Webhook offline →
503: the kill switch.
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.
MCP Endpoint
Reference for POST /api/agents/mcp — the MCP server exposing list_credentials and get_credential tools, with tvagent_ key or OAuth 2.1 session auth.
Token Refresh
The canonical reference for OAuth token refresh — webhook-autonomous by default, notify hints, and the narrow opt-in TV-mediated path for built-in providers.