Connecting agents

Tandem exposes a Model Context Protocol (MCP) server so AI agents can deploy services, read logs, restart things, and manage your organization on your behalf. Any MCP-capable client can connect — this guide gives copy-paste setup for the common ones.

Every client needs the same two facts:

What Value
Endpoint https://portal.launchtandem.com/mcp
Transport Streamable HTTP
Auth Authorization: Bearer <token> header

The token is a Tandem agent token — it looks like tdm_ followed by 48 hex characters. The rest of this guide assumes you already have one.

Getting a token

You have two options:

  • Bootstrap from a fresh agent. If your agent supports MCP but isn’t connected yet, point it at the endpoint with no auth and have it call the create_account_and_claim_link tool — the only tool reachable anonymously. The response includes a token and a ready-to-run setupHint command. This is how a brand-new Claude Code session onboards itself. See Bootstrapping an account for the full self-onboarding walkthrough (including a no-MCP curl path).
  • Mint one from the portal. If you already have an account, open Settings → Tokens, create an agent token, and copy the value. You can scope it to specific actions (deploy, restart, logs, …) and to a single project or service. The token is shown once — copy it immediately.

Keep tokens secret. Treat an agent token like a password. Don’t commit it to a repo, paste it into chat logs, or write it to a world-readable file. If one leaks, revoke it from Settings → Tokens.

Claude Code

Claude Code reads MCP servers from its own config. The fastest path is the CLI:

claude mcp add --scope user --transport http tandem \
  https://portal.launchtandem.com/mcp \
  --header "Authorization: Bearer tdm_xxxxxxxx"

--scope user persists the server across all your projects. To reset an existing entry, remove it first:

claude mcp remove tandem && claude mcp add --scope user --transport http tandem \
  https://portal.launchtandem.com/mcp \
  --header "Authorization: Bearer tdm_xxxxxxxx"

Restart Claude Code afterward so it picks up the new server. The bootstrap flow returns this exact command as setupHint, so a self-onboarding agent can run it verbatim.

Claude (desktop & web)

The Claude desktop and web apps add MCP servers through Settings → Connectors → Add custom connector.

  1. Open Settings → Connectors.
  2. Click Add custom connector.
  3. Name it Tandem and set the URL to https://portal.launchtandem.com/mcp.
  4. Under authentication, add a header Authorization with the value Bearer tdm_xxxxxxxx.
  5. Save and enable the connector. Tandem’s tools now appear in the connector menu of any chat.

OpenAI (ChatGPT / Agents)

OpenAI’s Agents and ChatGPT (developer mode) connect to remote MCP servers over HTTP.

For the Responses / Agents API, add Tandem as a hosted MCP tool:

{
  "type": "mcp",
  "server_label": "tandem",
  "server_url": "https://portal.launchtandem.com/mcp",
  "headers": {
    "Authorization": "Bearer tdm_xxxxxxxx"
  }
}

In ChatGPT, enable developer mode, go to Settings → Connectors → Create, supply the URL https://portal.launchtandem.com/mcp, and add the Authorization: Bearer tdm_xxxxxxxx header.

Codex

Codex (the OpenAI Codex CLI) stores MCP servers in ~/.codex/config.toml. Add a streamable-HTTP server:

[mcp_servers.tandem]
url = "https://portal.launchtandem.com/mcp"

[mcp_servers.tandem.headers]
Authorization = "Bearer tdm_xxxxxxxx"

Or add it from the CLI:

codex mcp add tandem --url https://portal.launchtandem.com/mcp \
  --header "Authorization: Bearer tdm_xxxxxxxx"

Restart Codex so it reloads the config.

Cursor

Cursor reads MCP servers from .cursor/mcp.json (per-project) or ~/.cursor/mcp.json (global). Add Tandem under mcpServers:

{
  "mcpServers": {
    "tandem": {
      "url": "https://portal.launchtandem.com/mcp",
      "headers": {
        "Authorization": "Bearer tdm_xxxxxxxx"
      }
    }
  }
}

Open Cursor Settings → MCP to confirm Tandem shows up as connected. The per-project file lets you commit a checked-in config — but never commit the token; reference an environment variable or keep .cursor/mcp.json out of version control.

OpenClaw

OpenClaw connects to remote MCP servers over streamable HTTP. Add Tandem to its MCP server list with the standard endpoint and bearer header:

{
  "mcpServers": {
    "tandem": {
      "transport": "http",
      "url": "https://portal.launchtandem.com/mcp",
      "headers": {
        "Authorization": "Bearer tdm_xxxxxxxx"
      }
    }
  }
}

Reload OpenClaw’s MCP config (or restart it) after saving. If OpenClaw exposes a CLI for adding servers, point it at the same URL and pass the Authorization header.

Hermes

Hermes uses the same streamable-HTTP MCP contract. Register Tandem as a remote server:

{
  "mcpServers": {
    "tandem": {
      "transport": "http",
      "url": "https://portal.launchtandem.com/mcp",
      "headers": {
        "Authorization": "Bearer tdm_xxxxxxxx"
      }
    }
  }
}

Restart Hermes so it establishes the session. Tandem’s tools become available to the agent once the connection is live.

Other MCP clients

Any client that speaks MCP over streamable HTTP can connect — the four things above are all you need. Configure:

  • Server URL: https://portal.launchtandem.com/mcp
  • Transport: streamable HTTP (HTTP POST with an optional Mcp-Session-Id header)
  • Auth header: Authorization: Bearer tdm_xxxxxxxx

A quick sanity check from a terminal — a JSON-RPC ping to POST /mcp answers without auth:

curl -s https://portal.launchtandem.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"ping"}'
# {"jsonrpc":"2.0","id":1,"result":{}}

(GET /mcp returns 405 Method Not Allowed — Tandem does not offer a server-initiated SSE stream, so all traffic goes over POST.)

Tool calls go to POST /mcp as JSON-RPC and require the bearer token. If your client manages sessions, Tandem honors the Mcp-Session-Id response header — echo it back on subsequent requests to reuse the authenticated session.

Troubleshooting

  • 401 / unauthorized — the token is missing, malformed, or revoked. Confirm the header is exactly Authorization: Bearer tdm_... and mint a fresh token from Settings → Tokens if needed.
  • Tool calls rejected with an action error — the token is action-scoped and doesn’t permit that operation. Create a token with the actions you need (deploy, restart, rollback, logs, read, manage).
  • Only create_account_and_claim_link is visible — the client connected anonymously. Your auth header isn’t reaching the server; re-check how your client attaches headers.
  • Connection works in one session but not the next — for CLI clients, make sure you persisted the server (e.g. Claude Code’s --scope user) rather than adding it for a single run.