> ## 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 connects to Ankra over OAuth, so you do not need to create or copy a token first. Where you add the connection depends on which Claude you use:

* **Claude web and desktop apps** - add Ankra as a custom connector in Settings.
* **Claude Code** (the terminal client) - add Ankra with the `claude mcp add` command.

<Tabs>
  <Tab title="Claude web and desktop">
    Custom connectors require a paid Claude plan. On Team and Enterprise plans an owner may need to add the connector for the organisation.

    <Steps>
      <Step title="Open the Connectors settings">
        In Claude, select your profile icon in the bottom left corner, then **Settings**. In the settings sidebar, select **Connectors** under the **Customize** heading. You see a list of available connectors such as Slack and Gmail - Ankra is not in this list yet, which is why you add it as a custom connector.
      </Step>

      <Step title="Add a custom connector">
        Select the **Add** button in the top right of the Connectors page, then select **Add custom connector** from the menu.

        <Frame caption="The Add menu in the top right of Claude's Connectors settings">
          <img src="https://mintcdn.com/ankra/-eNKDu16kjR2YgJe/images/mcp-claude-add-connector-menu.png?fit=max&auto=format&n=-eNKDu16kjR2YgJe&q=85&s=95633216e834947a2405549e5255db77" alt="Claude Connectors settings with the Add menu open, showing Browse connectors and Add custom connector" width="1031" height="775" data-path="images/mcp-claude-add-connector-menu.png" />
        </Frame>
      </Step>

      <Step title="Enter the Ankra server details">
        In the **Add custom connector** dialog, enter `Ankra` as the name and this URL in the **Remote MCP server URL** field:

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

        Leave the **OAuth Client ID** and **OAuth Client Secret** fields under Advanced settings empty - Ankra does not need them. Then select **Add**.

        <Frame caption="The completed Add custom connector dialog">
          <img src="https://mintcdn.com/ankra/-eNKDu16kjR2YgJe/images/mcp-claude-custom-connector-dialog.png?fit=max&auto=format&n=-eNKDu16kjR2YgJe&q=85&s=59009613da3e8b6b709b95ca9b78dc01" alt="Claude Add custom connector dialog filled in with the name Ankra and the Ankra MCP server URL" width="982" height="737" data-path="images/mcp-claude-custom-connector-dialog.png" />
        </Frame>
      </Step>

      <Step title="Connect and sign in to Ankra">
        Ankra now appears in your connector list with a **Connect** button. Select it. Claude opens Ankra's OAuth consent page in a new window - sign in to Ankra if you are not signed in already, select the organisation the connection should use, review the requested `mcp:read` or `mcp:write` access, then approve the connection. Claude then shows Ankra as connected.
      </Step>

      <Step title="Enable Ankra in a chat">
        Open a new chat and select the tools menu (the sliders icon below the message box). Check that **Ankra** is listed and enabled. To verify the connection works end to end, ask Claude to list your Ankra clusters - it should call the `list_clusters` tool and return the clusters in your organisation.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    <Steps>
      <Step title="Add the server">
        Run this once from your terminal:

        ```bash theme={null}
        claude mcp add --transport http ankra https://platform.ankra.app/api/v1/mcp
        ```

        This registers the server for your user in the current project. Add `--scope user` to make it available in every project.
      </Step>

      <Step title="Authenticate">
        Start Claude Code and run the `/mcp` command. It lists every configured MCP server with its connection status - **ankra** shows as needing authentication. Select it, then choose **Authenticate**. Your browser opens Ankra's OAuth consent page - sign in, select the organisation, review the requested access, then approve the connection and return to the terminal.
      </Step>

      <Step title="Verify the connection">
        Run `/mcp` again and confirm that **ankra** shows as connected. Then ask Claude Code to list your Ankra clusters - it should call the `list_clusters` tool and return the clusters in your organisation.
      </Step>
    </Steps>

    If you prefer a long-lived token over OAuth, create an [MCP token](#create-an-mcp-token) and register the server with an authorisation header instead:

    ```bash theme={null}
    claude mcp add --transport http ankra https://platform.ankra.app/api/v1/mcp \
      --header "Authorization: Bearer <your-token>"
    ```
  </Tab>
</Tabs>

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 when the grant expires, reconnect: select **Connect** on the Ankra connector in Claude's Connectors settings, or run `/mcp` and authenticate again in Claude Code.

## How Tool Access Works

The [MCP Tool Reference](/platform/mcp-tools) lists every available tool with the scope it requires and whether it needs a `cluster_id`.

* `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. For Claude clients connected with OAuth this usually means the seven-day grant expired - reconnect the Ankra connector in Claude's settings, or run `/mcp` and authenticate again in Claude Code.

### 403 Token has no MCP scope

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

### Claude reports "Couldn't register with Ankra's sign-in service"

Claude could not reach Ankra's OAuth discovery endpoints, so it could not register itself as an OAuth client. This is a platform-side routing problem, not a mistake in your connector configuration - the server URL field only accepts the MCP endpoint, and no OAuth Client ID is needed. Ask your Ankra administrator to confirm that `/oauth/` and the `/.well-known/oauth-*` discovery paths on the platform host route to the API service, then select **Connect** on the Ankra connector again.

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