MCP server

How to connect Swarmia MCP to your AI client

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.

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.

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

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.

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:

{
  "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.