# MCP tokens API

> List, create, rename, rescope and revoke the MCP tokens that AI assistants use to query your ApiTraffic data through the MCP server.

Source: https://www.apitraffic.io/docs/api-reference/mcp-tokens

An MCP token lets an AI assistant such as Claude or Cursor query your traffic through the [ApiTraffic MCP server](https://www.apitraffic.io/docs/integrations/mcp-server) at `https://api.apitraffic.io/mcp`. Each token is limited to one environment and, optionally, to some of its buckets. MCP tokens work only with the MCP server; they are not accepted by the REST API.

**Plan:** creating and changing MCP tokens needs a plan that includes the **MCP server**. Listing, reading and revoking existing tokens keep working if the plan changes. The number of active tokens an account can hold depends on the plan.

**Permissions:** any member can list and read tokens. Creating, changing and revoking a token needs an owner or admin session, or an `administrator` API token.

> **Note:** The token value is returned once, in the response to [Create MCP token](#create-mcp-token). Every other response shows a masked hint, so copy the value into your MCP client when you create it.

## The MCP token object

- **sid (string, required)**:
  The token's identifier (`mcp_` followed by 27 letters and digits). Use it in paths. It is not the credential.

- **accountSid (string, required)**:
  The account the token belongs to.

- **environmentSid (string, required)**:
  The environment the token can read.

- **bucketSids (string[], required)**:
  The buckets the token can read. An empty array means every bucket in the environment.

- **name (string, required)**:
  The token's name.

- **token (string | null)**:
  The credential (`mcp_…`, longer than the sid) in the create response; a masked hint everywhere else.

- **isRevoked (boolean, required)**:
  Whether the token has been revoked.

- **createdAt (string, required)**:
  When the token was created (ISO 8601).

- **updatedAt (string, required)**:
  When the token was last changed.

- **lastUsedAt (string | null)**:
  When an assistant last used the token. `null` if never.

- **revokedAt (string | null)**:
  When the token was revoked. `null` while it is active.

## List MCP tokens

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/mcpTokens`

Returns the account's active MCP tokens. Revoked tokens are left out.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier (`acc_` followed by 27 letters and digits).

### Response

- **hasMore (boolean, required)**:
  Always `false`: every active token is returned in one response.

- **records (object[], required)**:
  The tokens, as [MCP token objects](#the-mcp-token-object).

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/mcpTokens \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/mcpTokens`, {
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
const { records } = await response.json();
```

```json 200
{
  "hasMore": false,
  "records": [
    {
      "sid": "mcp_2pR7vK1xN9mQ4tB6wZ3cL8hY5fD",
      "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
      "environmentSid": "prd7k2",
      "bucketSids": [],
      "name": "Jordan's Claude",
      "token": "mcp_Lw3Pz*******6Kp1N",
      "isRevoked": false,
      "createdAt": "2026-09-14T10:00:00.000Z",
      "updatedAt": "2026-09-14T10:00:00.000Z",
      "lastUsedAt": "2026-10-19T13:48:22.000Z",
      "revokedAt": null
    }
  ]
}
```

## Get MCP token

`GET https://api.apitraffic.io/v1/accounts/{accountSid}/mcpTokens/{mcpTokenSid}`

Returns one MCP token, including a revoked one. The token value is masked.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **mcpTokenSid (path, string, required)**:
  The token's identifier (`mcp_` followed by 27 letters and digits).

### Response

An [MCP token object](#the-mcp-token-object).

```bash cURL
curl https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/mcpTokens/mcp_2pR7vK1xN9mQ4tB6wZ3cL8hY5fD \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const mcpTokenSid = 'mcp_2pR7vK1xN9mQ4tB6wZ3cL8hY5fD';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/mcpTokens/${mcpTokenSid}`,
  { headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` } },
);
const token = await response.json();
```

```json 200
{
  "sid": "mcp_2pR7vK1xN9mQ4tB6wZ3cL8hY5fD",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "environmentSid": "prd7k2",
  "bucketSids": [],
  "name": "Jordan's Claude",
  "token": "mcp_Lw3Pz*******6Kp1N",
  "isRevoked": false,
  "createdAt": "2026-09-14T10:00:00.000Z",
  "updatedAt": "2026-09-14T10:00:00.000Z",
  "lastUsedAt": "2026-10-19T13:48:22.000Z",
  "revokedAt": null
}
```

## Create MCP token

`POST https://api.apitraffic.io/v1/accounts/{accountSid}/mcpTokens`

Creates an MCP token for one environment. The response is the only time the full token value is returned.

**Plan:** needs the **MCP server**; past the plan's active token limit, the API answers `409` with code `2213`. **Permissions:** owner or admin, or an `administrator` API token.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

### Body parameters

- **name (body, string, required)**:
  A name that says who or what uses the token, for example `Jordan's Claude`.

- **environmentSid (body, string, required)**:
  The environment the token can read.

- **bucketSids (body, string[], default [])**:
  The buckets the token can read. Leave it out, or send an empty array, for every bucket in the environment.

### Response

An [MCP token object](#the-mcp-token-object), with the full value in `token`.

```bash cURL
curl -X POST https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/mcpTokens \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jordan'\''s Claude",
    "environmentSid": "prd7k2",
    "bucketSids": ["k3m9p2x"]
  }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const response = await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/mcpTokens`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ name: "Jordan's Claude", environmentSid: 'prd7k2', bucketSids: ['k3m9p2x'] }),
});
const created = await response.json();
// Paste created.token into your MCP client now: it is never returned again.
```

```json 200
{
  "sid": "mcp_2pR7vK1xN9mQ4tB6wZ3cL8hY5fD",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "environmentSid": "prd7k2",
  "bucketSids": ["k3m9p2x"],
  "name": "Jordan's Claude",
  "token": "mcp_Lw3Pz8Qk1Vn6Rt9Xb2Mc5Hd7Jf4Gs0Ye8Ua3Io6Kp1N",
  "isRevoked": false,
  "createdAt": "2026-10-19T14:20:00.000Z",
  "updatedAt": "2026-10-19T14:20:00.000Z",
  "lastUsedAt": null,
  "revokedAt": null
}
```

## Update MCP token

`PUT https://api.apitraffic.io/v1/accounts/{accountSid}/mcpTokens/{mcpTokenSid}`

Renames a token or changes the buckets it can read. Send only the fields you want to change. A change of buckets takes effect on the token's next call. The environment cannot change; create a new token for another environment.

**Plan:** needs the **MCP server**. **Permissions:** owner or admin, or an `administrator` API token.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **mcpTokenSid (path, string, required)**:
  The token's identifier.

### Body parameters

- **name (body, string)**:
  The new name.

- **bucketSids (body, string[])**:
  The buckets the token can read. An empty array means every bucket in the environment.

### Response

The updated [MCP token object](#the-mcp-token-object), with the value masked.

```bash cURL
curl -X PUT https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/mcpTokens/mcp_2pR7vK1xN9mQ4tB6wZ3cL8hY5fD \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "bucketSids": [] }'
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const mcpTokenSid = 'mcp_2pR7vK1xN9mQ4tB6wZ3cL8hY5fD';
const response = await fetch(
  `https://api.apitraffic.io/v1/accounts/${accountSid}/mcpTokens/${mcpTokenSid}`,
  {
    method: 'PUT',
    headers: {
      Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ bucketSids: [] }),
  },
);
const updated = await response.json();
```

```json 200
{
  "sid": "mcp_2pR7vK1xN9mQ4tB6wZ3cL8hY5fD",
  "accountSid": "acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa",
  "environmentSid": "prd7k2",
  "bucketSids": [],
  "name": "Jordan's Claude",
  "token": "mcp_Lw3Pz*******6Kp1N",
  "isRevoked": false,
  "createdAt": "2026-10-19T14:20:00.000Z",
  "updatedAt": "2026-10-19T14:25:00.000Z",
  "lastUsedAt": null,
  "revokedAt": null
}
```

## Revoke MCP token

`DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/mcpTokens/{mcpTokenSid}`

Revokes a token. Assistants using it are refused from their next call. A revoked token cannot be restored; create a new one if you need access again. It no longer appears in [List MCP tokens](#list-mcp-tokens), but [Get MCP token](#get-mcp-token) still returns it with `isRevoked: true`.

**Permissions:** owner or admin, or an `administrator` API token.

### Path parameters

- **accountSid (path, string, required)**:
  The account identifier.

- **mcpTokenSid (path, string, required)**:
  The token's identifier.

### Response

- **sid (string, required)**:
  The revoked token's identifier.

- **deleted (boolean, required)**:
  `true`.

```bash cURL
curl -X DELETE https://api.apitraffic.io/v1/accounts/acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa/mcpTokens/mcp_2pR7vK1xN9mQ4tB6wZ3cL8hY5fD \
  -H "Authorization: Bearer $APITRAFFIC_TOKEN"
```

```js Node.js
const accountSid = 'acc_2mXq7RbT4kPz9WvN3cHd8LsYfQa';
const mcpTokenSid = 'mcp_2pR7vK1xN9mQ4tB6wZ3cL8hY5fD';
await fetch(`https://api.apitraffic.io/v1/accounts/${accountSid}/mcpTokens/${mcpTokenSid}`, {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${process.env.APITRAFFIC_TOKEN}` },
});
```

```json 200
{
  "sid": "mcp_2pR7vK1xN9mQ4tB6wZ3cL8hY5fD",
  "deleted": true
}
```

## Errors

| Status | Code | Meaning |
| --- | --- | --- |
| `400` | `1000` | A field is missing or invalid, for example an `mcpTokenSid` in the wrong format. |
| `400` | `3001` | The token could not be created. |
| `403` | `2010` | Creating, changing or revoking a token without owner, admin or `administrator` access. |
| `403` | `2221` | The plan does not include the MCP server (create and update only). |
| `404` | `4000` | No token with that `mcpTokenSid` in this account. |
| `409` | `2213` | The plan's active MCP token limit is reached. Revoke an unused token, or upgrade. |
| `503` | `2108` | The change could not be applied right now. Nothing was changed; retry. |

## Related

- [MCP server](https://www.apitraffic.io/docs/integrations/mcp-server):
    Connect Claude, Cursor and other assistants with your token.

- [MCP tools](https://www.apitraffic.io/docs/integrations/mcp-tools):
    What an assistant can ask once it is connected.