MCP Proxy: Secure AI Agent Connections

What is the MCP Proxy?

The MCP proxy acts as a secure intermediary for your AI agents (Cursor, Windsurf, Claude, etc.). Your agent gets a proxy key (a random string). When the agent makes a request, the proxy validates the key, fetches the real token from your vault, injects it into the request headers, and forwards everything to the upstream service. The agent never sees your real credentials.

How It Works

Proxy Flow

Creating a Proxy

1. Go to the MCP Proxy tab and click "Create MCP Proxy".
2. Choose a method: Manual Config, Templates, or Import JSON.
3. For manual: enter a name, the upstream MCP URL, select which stored token to inject, and configure headers.
4. Use ${TOKEN} as a placeholder in headers where the real token should be injected (e.g., Authorization: Bearer ${TOKEN}).
5. Click "Generate Config" to get the proxy configuration JSON.

Manual Configuration

Fill in the proxy name, upstream URL, and select a token to inject:

Import from JSON

If you have an MCP config snippet from a tool's documentation (e.g., { "mcpServers": { ... } }), switch to the Import JSON tab in the create dialog, paste it, and Token Vault will automatically extract the URL and headers for you:

Proxy Ready

After generating the config, the dialog shows the proxy configuration JSON that you copy into your agent's config file:

Connecting Your Agent

Copy the generated JSON and paste it into your agent's configuration file:

"mcpServers": {
  "github-proxy": {
    "url": "https://api.tokenvault.uk/api/proxy/mcp?key=YOUR_PROXY_KEY",
    "headers": {}
  }
}

Notice: headers is empty because Token Vault handles authentication server-side.

Claude.ai Connectors

Claude.ai web UI connectors expect a plain URL — no JSON config file, no custom headers. Use the Copy URL button on the proxy card (or the "Token in URL" tab in the config dialog) to get a URL with the key embedded:

https://api.tokenvault.uk/api/proxy/mcp?key=mcp_YOUR_PROXY_KEY

Paste this directly into the Add connector dialog in Claude.ai. The key is in the URL, so no additional authentication setup is needed.

Auth Types

A proxy injects upstream credentials one of two ways:

tv_session: front an OAuth-gated MCP server

If your upstream is itself gated by Token Vault's OAuth 2.1 tokens (for example your own MCP gateway using introspection), a tv_session proxy keeps a fresh session injected for you:

{
  "name": "Home MCP Hub",
  "upstreamUrl": "https://mcp.example.com/mcp",
  "authType": "tv_session",
  "boundAgentId": "agent-doc-id"
}

On create, Token Vault mints a refresh token bound to that agent and stores it server-side (never echoed back). At call time it mints or reuses a one-hour tvsess_ and calls the upstream directly — these are Token Vault's own session tokens, not your credentials, so your webhook is not involved. The bound agent's ABAC policies gate every call; suspending the agent or deleting the proxy breaks the path immediately.

Managing Proxies

The MCP Proxy page shows all your configured proxies with their status, upstream URL, and action buttons:

Webhook Mode + MCP Proxy