# MCP server

The Swarmia MCP (Model Context Protocol) server lets AI assistants like Claude, Cursor, and Windsurf query your engineering data directly — using natural language. Instead of exporting data and pasting it into a chat, you can ask questions about your engineering org and get answers grounded in live Swarmia data.

{% hint style="info" %}
Swarmia MCP is in Alpha. Please reach out to your customer success manager or to <hello@swarmia.com> to get access.
{% endhint %}

### Before You Start

You'll need an **MCP-compatible AI client.** Setup instructions below for Claude Desktop, Cursor, and Windsurf.

### Setup

#### Claude Desktop

**For org admins**

1. Go to **Customize → Connectors** and click the **+** button.
2. Select **Add custom connector**.
3. In the **Remote MCP server URL** field, enter: `https://app.swarmia.com/api/v1/mcp`
4. In the **Name** field, enter `Swarmia`.
5. Click **Add**.

<figure><img src="https://2772466312-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMa8uBmGhQgR7MTPq9yh7%2Fuploads%2FoSU2e9trCeKeHdjxf4fH%2FMCP%20Claude%20Desktop%20Admin%20Add%20Custom%20Connector.png?alt=media&#x26;token=d2add8f7-6998-43e4-8e2f-04830a38fb7a" alt="" width="375"><figcaption></figcaption></figure>

The Swarmia connector will now be available to all members of your organization.

**For team members**

1. Go to **Customize → Connectors**.
2. Locate **Swarmia (custom)** in the list and click **Connect**. If you don't see Swarmia in the list, ask an org admin to add the Swarmia connector to your organization.
3. You'll be redirected to a browser window — click **Authorize**.
4. Once authorized, you'll be returned to Claude Desktop and Swarmia will appear as an active connector.

<figure><img src="https://2772466312-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FMa8uBmGhQgR7MTPq9yh7%2Fuploads%2FT28KF39lonf1Of5uVYxK%2FMCP%20Team%20Member%20Connectors.png?alt=media&#x26;token=1b8d68e8-3677-41ea-bb04-449e90225acb" alt=""><figcaption></figcaption></figure>

***

#### Claude Code

**OAuth**

```bash
claude mcp add swarmia \
  --transport http "https://app.swarmia.com/api/v1/mcp"
```

***

#### Cursor

Create a **Swarmia API token** with the **MCP** scope enabled in [**Swarmia Settings → API tokens**](https://app.swarmia.com/settings/api-tokens).

Go to **Cursor Settings → MCP** and add a new server with:

* **Type:** `streamable-http`
* **URL:** `https://app.swarmia.com/api/v1/mcp`
* **Headers:** `Authorization: Bearer YOUR_API_TOKEN`

Alternatively, add the following to `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "swarmia": {
      "type": "streamablehttp",
      "url": "https://app.swarmia.com/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}
```

***

#### Other MCP Clients

The Swarmia MCP server supports any client that implements the **Streamable HTTP** transport. Point your client at:

```
https://app.swarmia.com/api/v1/mcp
```

Authenticate using a `Bearer` token in the `Authorization` header. The server is stateless — each request is independent, so no session management is needed.

***

### What Data Is Available

The MCP server exposes the following categories of data:

* **Engineering activity** — Pull requests, commits, code reviews, review comments, deployments
* **Planning & work** — Issues, sprints, initiatives, projects, investment categories, working agreements
* **Teams & people** — Teams, authors, repositories
* **AI assistant usage** — GitHub Copilot, Cursor, and Claude Code daily usage snapshots; AI attribution on pull requests
* **Survey data** — Survey responses, question answers, and comments

### Example Prompts

Some ready-to-use prompts to get started:

**DORA metrics**

> "Show me our DORA metrics for the last 30 days. How do they compare to the previous period?"

**Deployment health**

> "List the last 10 deployments for our team. Were there any failures?"

**Cycle time**

> "What's the average PR cycle time per team this month? Which teams have the highest PR cycle time?"

**AI coding assistant adoption**

> "How has GitHub Copilot adoption changed over the past 3 months across our engineering teams?"

**Sprint progress**

> "How many issues did each team close in the current sprint? Which teams are on track?"

**Survey results**

> “Summarize our latest survey results. Which questions scored the lowest? Suggest actions based on the results.”

***

### Tips for Best Results

**Understanding the schema:** To understand what data is available, ask your assistant: *"What entity types are available in Swarmia?".* This lets you explore the full schema and see all properties and relationships for any entity type.

**Use predefined reports:** For common questions like DORA metrics or code overviews, predefined reports are faster and more reliable than custom queries. Ask your AI assistant to list available reports to see the full set.

**Ask follow-up questions:** AI should be able to refine and drill into results. Start broad, then ask for breakdowns by team, time period, or author for best results.

**Reference Swarmia concepts directly:** Refer to teams, repositories, and authors by name. The assistant has the context and will filter data accordingly.

***

### Troubleshooting

**401 Unauthorized** Your API token is invalid or has expired. Go to **Swarmia Settings → API tokens** and create a new token with the Entity Query scope.

**403 Forbidden** Your token exists but doesn't have the Entity Query scope. Edit the token's permissions in **Swarmia Settings → API tokens**.

**405 Method Not Allowed** Your MCP client is using SSE (GET) transport instead of Streamable HTTP (POST). Check your client configuration and ensure it's set to `streamablehttp`, not `sse`.

**Tool call errors** If a query fails, the tool will return a descriptive error message with guidance on what to fix — this typically points to missing fields, unsupported entity types, or incorrect query structure. Read the error and adjust your prompt accordingly.

**No data returned** Make sure the API token belongs to an account with access to the relevant teams and repositories in Swarmia. Data access follows the same permissions as the Swarmia app.