Connecting to the Swarmtix MCP Server

Every client needs the same two things: the server URL, and one trip through a browser to approve the connection. There is no API key, no token to paste, and no local process to install.

Quick Start

Add the URL in your client, approve the consent screen in the browser window that opens, and the tools appear.

Claude (Web and Desktop)

Claude calls remote MCP servers connectors.

1. Open Settings
2. Go to Connectors
3. Click Add custom connector
4. Paste the URL:

https://swarmtix.com/mcp/v1

5. Click Add, then Connect
6. A Swarmtix page opens in your browser. Sign in, choose the organisation, review the permissions, and click Allow

Claude shows the connector as connected and its tools become available in new conversations. If you have more than one organisation, add the connector once per organisation and give each one a name you will recognise.

ChatGPT

1. Open Settings
2. Go to Connectors
3. Create a new connector
4. Paste the URL:

https://swarmtix.com/mcp/v1

5. Choose OAuth as the authentication method — leave any API key field empty
6. Save, then click Connect
7. Approve the Swarmtix consent page that opens in your browser

Claude Code

Add the server from the terminal:

claude mcp add --transport http swarmtix https://swarmtix.com/mcp/v1

Add --scope user to make it available in every project rather than just the current one:

claude mcp add --transport http --scope user swarmtix https://swarmtix.com/mcp/v1

Then, inside Claude Code, run:

/mcp

Pick swarmtix and choose to authenticate. Your browser opens the consent page. Once you approve, /mcp shows the server as connected and lists its tools.

To check or remove it later:

claude mcp list
claude mcp remove swarmtix

VS Code

Create .vscode/mcp.json in your workspace (or use MCP: Add Server from the Command Palette and choose an HTTP server):

{
  "servers": {
    "swarmtix": {
      "type": "http",
      "url": "https://swarmtix.com/mcp/v1"
    }
  }
}

Save the file. VS Code offers to start the server; the first tool call triggers the browser sign-in. Approve the consent page and the tools appear in the Copilot Chat tool picker.

To make it available in every workspace instead, put the same servers block in your user mcp.json through MCP: Open User Configuration.

Cursor

Create .cursor/mcp.json in your project, or ~/.cursor/mcp.json for every project:

{
  "mcpServers": {
    "swarmtix": {
      "url": "https://swarmtix.com/mcp/v1"
    }
  }
}

Save the file, then open Settings → MCP. The Swarmtix entry shows that it needs to sign in; click it, approve the consent page, and the indicator turns green.

Raw HTTP

The endpoint speaks JSON-RPC 2.0 over Streamable HTTP. Everything below is a plain POST to the same URL.

1. Discover how to authenticate

An unauthenticated request tells you where the authorization server is:

curl -i -X POST https://swarmtix.com/mcp/v1 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://swarmtix.com/.well-known/oauth-protected-resource", scope="events:read"

Follow the resource_metadata URL for the protected-resource document, which names the authorization server. From there the standard metadata documents describe the rest:

https://swarmtix.com/.well-known/oauth-protected-resource
https://swarmtix.com/.well-known/oauth-authorization-server
https://swarmtix.com/.well-known/jwks

2. Get a token

Run the authorization code flow with PKCE (S256 is required — a request without a code challenge is refused). The endpoints are /connect/authorize and /connect/token. Register your client with Dynamic Client Registration, or publish a Client ID Metadata Document; both are supported.

The full flow, including what the user sees, is described in Authentication and Scopes.

3. Call the server

curl -X POST https://swarmtix.com/mcp/v1 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Calling a tool follows the same shape:

curl -X POST https://swarmtix.com/mcp/v1 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" \
  -H "Mcp-Method: tools/call" \
  -H "Mcp-Name: swarmtix_events_list" \
  -d '{
        "jsonrpc":"2.0",
        "id":2,
        "method":"tools/call",
        "params":{"name":"swarmtix_events_list","arguments":{"limit":10}}
      }'

Protocol revisions

The server supports five revisions:

2026-07-28  2025-11-25  2025-06-18  2025-03-26  2024-11-05

You do not pick a mode. A client that opens with initialize is served with a session, the way it expects; a 2026-07-28 client is served statelessly on the same URL. Both work against the same endpoint.

On 2026-07-28, the MCP-Protocol-Version, Mcp-Method and Mcp-Name headers are mandatory and must agree with the request body. A header that contradicts the body is rejected with JSON-RPC error -32020.

What Happens When You Connect

1. Your client fetches the protected-resource document and finds the Swarmtix authorization server
2. It registers itself, or identifies itself with a metadata document
3. It opens /connect/authorize in your browser with a PKCE challenge
4. You sign in to Swarmtix, or you are recognised if you already have a session
5. The consent page shows the client's name, the organisation being granted, and each permission in plain English
6. You click Allow
7. Swarmtix redirects back to your client with a code, which the client exchanges at /connect/token
8. The client calls tools/list, and sees only the tools your approved scopes allow

Troubleshooting

The tool list is empty, or a tool you expected is missing

Scopes gate tool visibility, not just invocation. A tool whose scope you did not approve is filtered out of the list entirely rather than failing when called, so there is no error to read — it is simply not there. Disconnect and reconnect, approving the permission the tool needs; the tool reference names the scope for each one.

If a tool is visible but calling it returns This connection is not authorized for <scope>. Reconnect and grant it to use this tool., the same fix applies — the message names the exact scope to approve.

The browser window opens blank, or the consent page will not load

The consent flow has to be a top-level page. Swarmtix sends X-Frame-Options: SAMEORIGIN, so any client that tries to embed the consent page in an iframe gets a blank frame. Use a client that opens your system browser.

The client reports 401 even though you approved the connection

• The connection was revoked in Settings → Developers → Connections. Revocation is immediate — tokens are checked against the server on every call — so this takes effect straight away, including for a client mid-session. Approve it again.
• The refresh token has passed its 30 days. Reconnect. Access tokens last an hour and a working client renews them on its own, so plain expiry is rarely the cause.
• A rotated refresh token was replayed. They are single-use, and presenting a consumed one revokes the whole grant on purpose. Reconnect, and store the replacement your client receives each time.
• The token was issued for a different resource. Swarmtix checks the audience on every call; a token minted for something else is refused even if it is otherwise valid.

The client reports -32020

A required header disagrees with the request body — usually Mcp-Method naming a different method than the body, or Mcp-Name naming a different tool. Send the headers that match, or drop to an older protocol revision where they are not required.

429, with the message "Rate limit reached. Retry in <n> seconds."

You went past 60 requests a minute, which is the per-organisation limit. It is a sliding window and it counts every credential your organisation holds together, so two assistants and a Zapier integration draw on the same budget.

Wait the number of seconds in the Retry-After header and try again. Most clients do this without being told.

This limit sits on top of the site-wide per-IP limit that applies to all Swarmtix traffic — clearing one does not exempt you from the other.

You cannot see the right organisation on the consent page

One connection covers one organisation. If your account belongs to several, the consent page asks which one. To use two, connect twice — once per organisation.