​

MCP Gateway

​

What it governs

• initialize / ping — pass through to the upstream. They carry protocol negotiation, not tenant data.
• tools/list — returns only the tools your allowlist permits (intersected with the token’s tool scope). Tools you haven’t allowed are never advertised.
• tools/call —
  1. Authorizes the tool against the allowlist — a call to a tool that isn’t allowed is rejected with a JSON-RPC error and never forwarded.
  2. Screens the arguments through the prompt firewall — an injection attempt in a text argument is blocked.
  3. Redacts PII in the arguments before forwarding, so sensitive data never reaches the upstream MCP server.
  4. Forwards the (redacted) call to the upstream.
  5. Redacts PII in the result on the way back to the client.

​

resources/* and prompts/* are refused

​

The credential

​

How the server authenticates upstream

​

secret (default)

​

passthrough — each user acts as themselves

{ "mode": "passthrough" }

POST /v1/mcp/my-jira
Authorization: Bearer kp_live_t_...           # your KnoxCall tool token, minted FOR YOU
X-KC-Upstream-Authorization: Bearer <your Jira token>

• The token has to name a person — and only the token does. The credential belongs to a human and the upstream will act as that human; the only record connecting the two is the one we write. So the identity comes from the subject bound into your tool token, which is covered by the token’s capability signature and fixed at mint. A token that names nobody is refused on a passthrough server, whatever headers it sends. X-KC-User is not an identity here and is ignored for binding. It used to be one, checked only against your directory — which meant anyone holding a credential could record the action against any provisioned employee. If you send it and it disagrees with the token, the call is still attributed to the token’s subject and the disagreement is logged. Two ways to get a subject-bound token, both of which prove the person before minting:

  Path	Who it is for	How the person is proven
  OIDC exchange with a binding that sets subject_claim	a workload acting for a named user	the claim is read out of an id_token your IdP signed
  Device-code grant	a human on Claude Code / Claude Desktop / Cursor	they sign in to KnoxCall and approve the device

  Set subject_claim on the binding to the claim that names the person (for example email). Its value is resolved against your directory (ai_gateway_user_attribution) at exchange time; a claim naming someone you have not provisioned is refused rather than minted unbound. Leave it null for ordinary CI — a build job is not a person, and a token with no subject keeps working everywhere except a passthrough server.
• No stored headers. A passthrough server cannot also carry auth.headers — sending both would put the shared credential and the user’s on the same request and let the upstream pick.
• Missing credential = refused, never anonymous. There is nothing to fall back to, and dialling unauthenticated would look like the feature working.
• A KnoxCall token is refused. If the header value looks like a KnoxCall credential — tk_ (tenant API key), kc_ (OAuth 2.1 access token), kr_ (OAuth 2.1 refresh token), kp_ (AI data-plane phantom token) or AKE (enterprise access key) — the call is rejected: that header goes to a third-party server, which has no use for it. The list is KNOXCALL_CREDENTIAL_PREFIXES in src/proxy/passthrough.ts, and every authenticator’s prefix has to be on it.
• Connections are never shared between users. Upstream connections are pooled for reuse; the pool key includes the token’s bound subject and a non-reversible tag derived from the credential, so two people can never end up on one connection — including when they hold the same token and send the same Mcp-Session-Id.

​

delegated — each user acts as themselves, without carrying a credential

{
  "mode": "delegated",
  "delegated": {
    "authorize_url": "https://provider.example.com/oauth/authorize",
    "token_url": "https://provider.example.com/oauth/token",
    "client_id": "your-oauth-app-client-id",
    "client_secret_ref": "{{secret_id:<uuid>}}",
    "scopes": ["read:issues", "write:issues"]
  }
}

• The token has to name a person, exactly as in passthrough. A call whose token names nobody is refused; a person with no connection is refused with a message telling them to connect, not with an upstream error.
• client_secret_ref is a secret reference, never a literal. auth is not encrypted and is returned by every read path, so a literal client secret would sit in cleartext in the control plane. A literal is refused with 422.
• Both endpoints must be public https://. Refused at write time, and the connection is dialled through the gateway’s resolve-and-pin egress, which validates every DNS answer and refuses redirects — the request carries a live credential.
• PKCE (S256) is always sent, whatever the client type. The authorization code comes back through a redirect the user’s browser follows, and an intercepted code with no verifier is that person’s upstream account.
• Refresh is single-flight across the fleet. Four API workers refreshing one connection at once is how a provider that rotates refresh tokens invalidates three of them and locks the user out of their own account.
• Only the person who started a connection can finish it. The callback requires a KnoxCall session and refuses if it is not the same user. Without that, someone could start a connection as themselves, send you the link, and have your upstream credential stored under their name — the refusal is audited, and nothing is stored.
• Changing auth revokes every connection on the server, and so does archiving it. The stored tokens were issued for one app, one set of scopes and one upstream; keeping them across a change would mean dialling with tokens minted under settings nobody can see any more.
• Revoking destroys the stored tokens, it does not set a flag. It does not revoke KnoxCall’s authorization at the provider — do that in the provider’s own account settings if you need it gone there too.
• Connections are never shared between users, on the same key as passthrough: the pool key carries the token’s bound subject and a non-reversible tag of the minted access token, so a refresh opens a new connection rather than leaving an expired token in service.

​

Getting a token as a person

• the OIDC exchange, for a workload (a CI job presenting an id_token from a bound issuer). Set subject_claim on the binding when that workload acts for a named user;
• the device flow, for a human at a laptop. See Connect Claude Code, Claude Desktop and Cursor.

​

Discovery & audience-bound tokens (OAuth 2.1)

1. Protected-resource metadata — RFC 9728. On a 401, the client fetches:
   GET https://<your-slug>.knoxcall.com/.well-known/oauth-protected-resource/v1/mcp/<server-slug>
   
   which returns the authorization server to use and the DPoP algorithms this resource accepts:
   {
     "resource": "https://<your-slug>.knoxcall.com/v1/mcp/<server-slug>",
     "authorization_servers": ["https://<your-slug>.knoxcall.com"],
     "bearer_methods_supported": ["header"],
     "dpop_bound_access_tokens_required": false,
     "dpop_signing_alg_values_supported": ["ES256"]
   }
   
   dpop_bound_access_tokens_required is false because DPoP binding is set per token, not per resource: a token minted with dpop_required must always be presented with a proof, and one minted without it may not use the DPoP scheme at all. Sender-constraining a token is strongly recommended and is what the flow below does — but a resource that returned true here would be promising that every token it accepts is bound, which is not something this server enforces.
2. Authorization-server metadata — RFC 8414. The client reads https://<your-slug>.knoxcall.com/.well-known/oauth-authorization-server to find the token endpoint.
3. Resource-indicated token — RFC 8707. When exchanging a workload identity for a token at /v1/oauth/token, the client passes a resource naming the exact MCP server:
   resource=https://<your-slug>.knoxcall.com/v1/mcp/<server-slug>
   
   The minted token is audience-confined to that resource — bound into its capability HMAC, so a token issued for /v1/mcp/weather cannot be replayed against /v1/mcp/payments. The resource must name an MCP server on your own domain; a foreign or malformed resource is rejected. Multiple resource indicators are not supported — pass exactly one.

​

Registering a server

curl -X POST https://api.knoxcall.com/v1/ai-gateway/gateways/$GATEWAY_ID/mcp-servers   -H "Authorization: Bearer $KNOXCALL_KEY"   -H "Content-Type: application/json"   -d '{
    "name": "Vendor tools",
    "slug": "vendor-tools",
    "upstream_url": "https://mcp.vendor.example/mcp",
    "allowed_tools": ["get_weather"],
    "auth": { "headers": { "Authorization": "Bearer {{secret_id:<uuid>}}" } }
  }'

• connect_url — where an MCP client points.
• resource — the RFC 8707 value a token for this server must be bound to (see above).

• upstream_url must be a public https:// address. Private, loopback, link-local and cloud-metadata destinations are refused when you save the server and again when we connect — the request carries your decrypted upstream credential, so it is never sent in cleartext or to an address inside anyone’s network.
• Upstream auth must reference a KnoxCall secret, e.g. "Bearer {{secret_id:<uuid>}}". A literal credential is rejected: it would sit unencrypted in the control plane, which is the opposite of what you use KnoxCall for.
• An empty allowed_tools advertises nothing. That is the default, and it is deliberate — a newly registered server exposes no tools until you name them.

​

Sessions

• A session belongs to one token. The pool is keyed on the verified capability token, so two tokens never share an upstream connection — nor the decrypted upstream credential behind it — whatever mcp-session-id they send. Before 2026-08-25 the client-supplied header was the only separator; see the changelog.
• A token holds at most 4 concurrent sessions per server per environment. Opening a fifth closes that token’s least recently used one. Idle sessions are closed after 5 minutes.

​

Two kinds of MCP server

• Upstream — proxies an external MCP server (its transport + URL), governed as above. This is what you can create today.
• Collection — synthesizing MCP tools from a KnoxCall route collection, so each governed route becomes a tool executed through the existing proxy. Not available yet: the data plane does not serve this type, so creating one is refused with 422 unsupported_server_type rather than leaving you with a server that fails on every call.