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

# MCP Server

> Connect Cursor, Claude, and other MCP clients to Ankra with scoped access to platform tools.

Ankra exposes a remote [Model Context Protocol](https://modelcontextprotocol.io/) server at:

```text theme={null}
https://platform.ankra.app/api/v1/mcp
```

Use it to inspect clusters, workloads, logs, alerts, and related platform data from an MCP client. Write access can also apply changes through Ankra's agent tools.

## Choose an Access Scope

| Scope       | Access                                                                                                                             |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `mcp:read`  | Read-only platform tools and Ankra's safe ask-mode tools, including temporary workspace operations and isolated pull request demos |
| `mcp:write` | The read surface plus mutating tools such as apply, scale, delete, and pull request creation                                       |

`mcp:write` implies read access. When creating a write token in the portal, Ankra selects both scopes.

<Warning>
  MCP clients own the confirmation experience. Ankra does not show a second server-side confirmation prompt before a write tool runs. Only grant `mcp:write` to clients you trust.
</Warning>

## Create an MCP Token

<Tabs>
  <Tab title="Ankra Platform">
    <Steps>
      <Step title="Open API Tokens">
        Open your profile, select **API Tokens**, then select **Add Token**.
      </Step>

      <Step title="Choose MCP access">
        Enter a descriptive name and select **mcp:read**. Select **mcp:write** only if the client needs to change resources.
      </Step>

      <Step title="Copy the token">
        Copy the generated token immediately and store it securely. Ankra only shows it once.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Ankra CLI">
    Create a read-only token:

    ```bash theme={null}
    ankra tokens create cursor --scopes mcp:read
    ```

    Create a token with read and write access:

    ```bash theme={null}
    ankra tokens create cursor --scopes mcp:read,mcp:write
    ```
  </Tab>
</Tabs>

MCP-scoped tokens work only with the MCP endpoint and stay bound to the organisation selected when the token was created. They cannot call Ankra's REST API or override their organisation.

## Connect Cursor

Add Ankra to your Cursor MCP configuration:

```json theme={null}
{
  "mcpServers": {
    "ankra": {
      "url": "https://platform.ankra.app/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <ankra-token>"
      }
    }
  }
}
```

Restart or refresh MCP servers in Cursor after saving the configuration. Ankra then appears as an available MCP server with tools filtered by the token's scopes.

<Tip>
  Keep personal tokens out of shared project configuration. Use a user-level MCP configuration or a local file that is excluded from version control.
</Tip>

## Connect Claude with OAuth

Claude clients that support remote MCP connectors can connect without a manually copied token.

<Steps>
  <Step title="Add the connector">
    Add a custom MCP connector in Claude and use `https://platform.ankra.app/api/v1/mcp` as the server URL.
  </Step>

  <Step title="Sign in to Ankra">
    Claude opens Ankra's OAuth consent flow. Sign in if needed.
  </Step>

  <Step title="Choose the organisation and scope">
    Select the organisation, review the requested `mcp:read` or `mcp:write` access, then approve the connection.
  </Step>
</Steps>

By default, Ankra issues a seven-day MCP-only token to the client. The flow uses OAuth 2.1 authorization code with PKCE. No client secret or refresh token is issued, so reconnect when the grant expires.

## How Tool Access Works

* `tools/list` only returns tools allowed by the token.
* Cluster-scoped tools require a `cluster_id`. Call `list_clusters` to discover IDs.
* Ankra verifies that the cluster belongs to the token's organisation before dispatch.
* Draft-only chat tools are not available over MCP.
* Parameters containing literal secrets are refused before a mutating tool runs.
* Tool calls are rate limited per token. Write calls also use a fail-closed platform write limit.
* Every resolved tool call, including refused calls, is written to the organisation audit log.

## Troubleshooting

### 401 Invalid or missing bearer token

The token is missing, expired, revoked, or copied incorrectly. Create a new MCP token and update the client.

### 403 Token has no MCP scope

The token is REST-only. Recreate it with `mcp:read` or `mcp:read,mcp:write`.

### 403 Origin not allowed

A browser-based client is calling from an origin that Ankra does not allow. Contact your Ankra administrator to review the configured origins.

### A tool reports that it needs mcp:write

The requested tool changes state and is outside the read surface. Use a write-scoped token only if the client should make that change.

### A tool reports a rate limit

Wait one minute and retry. If normal usage regularly reaches the limit, ask your Ankra administrator to review the MCP rate limits.

## Related

* [API Tokens](/reference/tokens)
* [AI Provider](/platform/ai-provider)
* [Hermes Integration](/integrations/hermes)