Connect your MCP client

Every tool call your client makes through KnoxCall reaches the upstream with your identity on it: the tool allowlist, the prompt-injection firewall and PII redaction all run first, and the call is recorded against you rather than against a shared key. This page is the whole flow for the three clients KnoxCall documents. One page rather than three, because the token flow is identical and only the file location differs — a page per client is three places for the same instructions to drift.

You copy the config block into place yourself. KnoxCall does not install anything into your editor and there is no extension or protocol handler.

1. Get a token, as yourself

An MCP token has to name a person. The workload-federation exchange (/v1/oauth/token) mints tokens for CI jobs from a signed id_token, which is the wrong shape for a human at a laptop — so there is a device flow. If your client speaks RFC 8628 (device authorization), point it at KnoxCall and it will show you a code. If it does not, run the flow yourself:

# 1. Ask for a code. `mcp_server` is the slug of the server you want —
#    your admin console shows it next to each MCP server.
curl -s https://api.knoxcall.com/v1/oauth/device_code \
  -d mcp_server=jira \
  -d client_name="my laptop"

{
  "device_code": "…",
  "user_code": "H4T9-KP2M",
  "verification_uri": "https://app.knoxcall.com/ai-gateway/device",
  "verification_uri_complete": "https://app.knoxcall.com/ai-gateway/device?user_code=H4T9-KP2M",
  "expires_in": 900,
  "interval": 5
}

Open verification_uri_complete, check that the screen names the MCP server and the workspace you expected, and approve. Codes last 15 minutes and can be used once.

# 2. Poll for the token. Wait `interval` seconds between polls — polling faster
#    is answered with `slow_down`, not with a token.
curl -s https://api.knoxcall.com/v1/oauth/token \
  -d grant_type=urn:ietf:params:oauth:grant-type:device_code \
  -d device_code=…

While you have not approved yet, that returns authorization_pending. Once you have, it returns the token — once. A second poll with the same device_code is refused as a replay.

{ "access_token": "kp_live_t_…", "token_type": "Bearer", "expires_in": 900 }

Approve only a code you just generated yourself. The approval screen shows the name the client gave itself, and that name is not verified — anyone can start a flow and ask you to approve it. Approving one hands that device a token that acts as you.

2. Point your client at the server

All three clients read the same mcpServers map. Replace the token with the one you just obtained, and the URL with the Connect URL shown on the MCP server’s page in your admin console.

Claude Code
Claude Desktop
Cursor

.mcp.json in your project root (shared with your team), or ~/.claude.json for just you:

{
  "mcpServers": {
    "jira": {
      "type": "http",
      "url": "https://api.knoxcall.com/v1/mcp/jira",
      "headers": {
        "Authorization": "Bearer kp_live_t_<paste-the-token-your-device-flow-returned>"
      }
    }
  }
}

~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows:

{
  "mcpServers": {
    "jira": {
      "type": "http",
      "url": "https://api.knoxcall.com/v1/mcp/jira",
      "headers": {
        "Authorization": "Bearer kp_live_t_<paste-the-token-your-device-flow-returned>"
      }
    }
  }
}

Restart Claude Desktop after editing the file.

.cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "jira": {
      "type": "http",
      "url": "https://api.knoxcall.com/v1/mcp/jira",
      "headers": {
        "Authorization": "Bearer kp_live_t_<paste-the-token-your-device-flow-returned>"
      }
    }
  }
}

3. What your token can and cannot do


One server	The token is audience-bound (RFC 8707) to the MCP server you approved. Pointed at another, it is refused — not degraded, refused.
One mode	A token approved in Test mode reaches Test servers only, and resolves Test credentials.
One person — you	The subject is fixed at mint and is covered by the token’s signature. `X-KC-User` is not an identity and is ignored.
No AI agent	It reaches no `/v1/ai` agent and no provider credential. It is a tool token, not a gateway key.
15 minutes	Re-run the device flow when it expires.

Troubleshooting

What you see	What it means
`authorization_pending`	Nobody has approved the code yet. Keep polling on `interval`.
`slow_down`	You polled faster than `interval`. Wait and try again.
`expired_token`	The code is older than 15 minutes, or was never valid. Start again.
`access_denied`	Someone declined it on the approval screen.
`invalid_grant`	That `device_code` was already used. A token is issued once.
`401 insufficient_scope` on a tool call	The token is not a `tool` token — it did not come from this flow.
`401` naming a different resource	The token is bound to another MCP server. Get one for this server.
`401 passthrough_identity_unbound`	The token names nobody. Tokens from the device flow always do; this one did not come from it.

If your server uses delegated OAuth

A server in auth.mode: "delegated" also needs your upstream account connected once, from the MCP server’s page in the console — see the MCP gateway page. The MCP token above says who you are to KnoxCall; the connection is what lets KnoxCall act as you at the upstream. Nobody can connect on your behalf.

Getting Started

SDKs

Essentials: Routes

Essentials: Ephemeral Proxy

Essentials: Clients

Essentials: Secrets

Essentials: Environments

Essentials: Collections

Essentials: Databases

Essentials: Vaults

Essentials: Inbound Webhooks

Essentials: Rate Limiting

Essentials: Crypto Keys

Essentials: Portable Encryption

Essentials: Certificate Authority

Essentials: Key Management

Essentials: Tenant KMS (BYOK)

Webhooks

Workflows

AI Gateway

Integrations

Integration Setup Guides

Security

Single Sign-On (SAML)

Monitoring

Advanced Features

Infrastructure

Secret Store Migrations

Account

Troubleshooting

Support

About

Connect Claude Code, Claude Desktop and Cursor

Connect your MCP client

1. Get a token, as yourself

2. Point your client at the server

3. What your token can and cannot do

Troubleshooting

If your server uses delegated OAuth

​Connect your MCP client

​1. Get a token, as yourself

​2. Point your client at the server

​3. What your token can and cannot do

​Troubleshooting

​If your server uses delegated OAuth

Connect your MCP client

1. Get a token, as yourself

2. Point your client at the server

3. What your token can and cannot do

Troubleshooting

If your server uses delegated OAuth