> For the complete documentation index, see [llms.txt](https://help.swarmia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.swarmia.com/settings/integrations/mcp-server.md). # MCP server How to connect Swarmia MCP to your AI client The Swarmia MCP (Model Context Protocol) server lets AI assistants like Claude and Cursor 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. ### Before You Start You'll need an **MCP-compatible AI client.** Setup instructions below for Claude Desktop, Claude Code, and Cursor. ### 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**.
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.
*** #### Claude Code **OAuth** ```bash claude mcp add swarmia \ --transport http "https://app.swarmia.com/api/v1/mcp" ``` **Re-authentication in Claude Code and Claude desktop** If you're prompted to re-authenticate with Swarmia via MCP, this is a known issue with how these clients handle OAuth token refresh — not a problem with your account or session. To re-authenticate: * **Claude Code** — run `/mcp` * **Claude desktop** — go to **Customize → Connectors** and reconnect *** #### 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, Claude Code, and Codex daily usage snapshots; AI attribution on pull requests * **Survey data** — Survey responses, question answers, and comments Most tools are read-only. A few [actions](/settings/integrations/mcp-server/mcp-server-actions.md) let your assistant prepare changes, such as a working agreement or a key metric, and nothing changes until you confirm it in Swarmia. ### Example prompts Some ready-to-use prompts to get started: **Delivery bottlenecks** > "Where is delivery getting stuck in each team? For the last 90 days, break change lead time into stages (coding, waiting for first review, review, waiting to merge, waiting to deploy) and look at issues too: issue cycle time, flow efficiency and issues stuck in progress. For each team's biggest bottleneck, look at the slowest pull requests or issues and tell me what they have in common. Render it as an HTML page with a chart and a short summary." **Where engineering time goes** > "How did engineering effort split across our investment categories in the last two quarters, in FTEs and %? For each category that moved more than 2 percentage points, name the 3 to 5 epics or projects that drove the change, and group the titles of pull requests not linked to any issue into themes with counts. End with what to rebalance. Render it as an HTML page with a chart and a short summary." **Maintenance work** > "How much engineering time went to keeping the lights on (bugs, incidents, maintenance, upgrades) in the last 3 full months, by month and team? Dig into the work: name the issues and epics that took the most effort, group the rest and any pull requests without an issue into themes with example titles, and flag repeats like the same system fixed again, manual dependency updates or flaky tests. Say what to prevent, automate or invest in. Render it as an HTML page with a chart and a short summary." Find tested prompts for every role, from CTOs to platform engineers, in the [prompt library](/guides/prompt-library.md). *** ### 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.swarmia.com/settings/integrations/mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.