> For the complete documentation index, see [llms.txt](https://docs.multitudes.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.multitudes.com/knowledge-base/mcp-server.md).

# Multitudes MCP Server

Query your Multitudes data from AI assistants using the MCP server

The Multitudes MCP server lets AI assistants such as Claude read your Multitudes metrics directly. Ask questions like "How has review wait time changed for the Platform team this quarter?" and the assistant fetches the data and answers.

The server is read-only. It exposes the same data as the [Multitudes API](https://docs.multitudes.com/knowledge-base/multitudes-api.md), and uses the same API keys and rate limits.

## Before you start

* The server is at `https://api.multitudes.co/mcp`.
* Authenticate with an organization API key that has the `data:read` scope, sent as `Authorization: Bearer <your-api-key>`. See how to [generate an API key](https://docs.multitudes.com/configuration-and-setup/api-keys.md).

{% hint style="warning" %}
An API key gives access to your whole organization's data. Treat it like a password and don't commit it to a repository.

Anyone in your Claude organization who can use the connector will be able to query this data, including people who don't have a Multitudes account.
{% endhint %}

## Connect Claude

An admin of your Claude organization needs to add Multitudes as a custom connector. You only need to do this once to enable this connection for your entire Claude organization.

{% stepper %}
{% step %}
Open [Admin settings > Connectors](https://claude.ai/admin-settings/connectors?modal=add-custom-connector). This link opens the "Add custom connector" dialog directly.
{% endstep %}

{% step %}
Enter a name, such as `Multitudes`, and the MCP server URL `https://api.multitudes.co/mcp`, then click **Continue**.

<figure><img src="https://3759751588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eOL1LoKX0USQQUCSepS%2Fuploads%2Fgit-blob-222f4f8e4a96de592c36c31f9e4075d0db85c7a3%2Fclaude-add-custom-connector-url.png?alt=media" alt="The Add custom connector dialog with the name Multitudes and the URL https://api.multitudes.co/mcp"><figcaption></figcaption></figure>
{% endstep %}

{% step %}
Under **Authentication**, select **No sign-in**. Multitudes uses an API key instead of OAuth.
{% endstep %}

{% step %}
Under **Request headers**, click **+ Add header** and select `authorization`. In the value field, enter `Bearer <your-api-key>`, using an organization API key with the `data:read` scope. Include the word `Bearer` and a space before the key.

<figure><img src="https://3759751588-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1eOL1LoKX0USQQUCSepS%2Fuploads%2Fgit-blob-6541096974cbbe4a2c84645652cfefb88195326e%2Fclaude-add-custom-connector-auth.png?alt=media" alt="The Add custom connector dialog with No sign-in selected and an authorization header"><figcaption></figcaption></figure>
{% endstep %}

{% step %}
Click **Add**.
{% endstep %}
{% endstepper %}

Claude stores the header value securely and doesn't show it again, so keep a copy of the key somewhere safe. Everyone using the connector shares the key's [rate limits](#rate-limits).

## Tools

| Tool                | What it does                                                                                                              |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `list_teams`        | Lists your teams and their IDs.                                                                                           |
| `list_metrics`      | Lists the available metrics and the optional parameters each accepts.                                                     |
| `fetch_chart`       | Fetches a metric's chart data for a date range, by team, repository, or (for some metrics) person.                        |
| `fetch_drilldown`   | Fetches the underlying records, such as pull requests, behind a metric.                                                   |
| `list_repositories` | Lists repositories with recent activity, for filtering charts by repository.                                              |
| `list_super_users`  | Lists super users from the last 28 days.                                                                                  |
| `fetch_docs`        | Reads Multitudes documentation, including metric definitions and the API reference, so the assistant can explain results. |

The assistant picks the tools for you and can query any data that can be fetched from the [REST API](https://docs.multitudes.com/knowledge-base/multitudes-api.md).

## Rate limits

MCP calls count against the same per-key limits as the REST API:

* 6 requests per second
* 30 requests per minute
* 150 requests per hour

`fetch_docs` calls don't count towards the limits. When a limit is exceeded, the assistant is told how long to wait before retrying.

## Tips

* Ask for a specific team, metric, and date range. Broad questions across every team and metric can fill your assistant's context with data you don't need, and use up your rate limit quickly.
* If a result looks unusual, ask the assistant to look at the drilldown data, which has the underlying records, to investigate likely causes.
* Ask the assistant for a `curl` command that returns the same data directly from the [REST API](https://docs.multitudes.com/knowledge-base/multitudes-api.md), so you can reuse the query in a script. The command uses a placeholder where your API key goes.
* Per-person data is only available for some metrics. The assistant checks which with `list_metrics`.
