> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Claude Code, Claude Desktop and Cursor

> Get an MCP token as a person — not as a CI job — and point your client at a KnoxCall-governed MCP server.

# 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.

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

## 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:

```bash theme={"dark"}
# 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"
```

```json theme={"dark"}
{
  "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**.

```bash theme={"dark"}
# 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.

```json theme={"dark"}
{ "access_token": "kp_live_t_…", "token_type": "Bearer", "expires_in": 900 }
```

<Warning>
  **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.
</Warning>

## 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.

<Tabs>
  <Tab title="Claude Code">
    `.mcp.json` in your project root (shared with your team), or `~/.claude.json` for
    just you:

    ```json theme={"dark"}
    {
      "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>"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Claude Desktop">
    `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
    `%APPDATA%\Claude\claude_desktop_config.json` on Windows:

    ```json theme={"dark"}
    {
      "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.
  </Tab>

  <Tab title="Cursor">
    `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for every project:

    ```json theme={"dark"}
    {
      "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>"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 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](/ai-gateway/mcp-gateway). 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.