Connecting External Agents

Any MCP-capable client can connect to your project's endpoint — remote SSE (FastMCP) at <pod-address>/mcp/sse, authenticated with an X-Api-Token header. Get the URL and a paired token with:

machina connect --probe                      # resolve + verify, token masked
machina connect <project-id> --mint --reveal  # durable dedicated key, revealed

See connect and mcp for the full flag reference.

Claude Code

claude mcp add --transport sse <name> <url> --header "X-Api-Token: <key>"

Cursor

~/.cursor/mcp.json (or your project's .cursor/mcp.json):

{
  "mcpServers": {
    "<name>": {
      "type": "sse",
      "url": "<url>",
      "headers": { "X-Api-Token": "<key>" }
    }
  }
}

Codex

Codex speaks stdio only, not remote SSE with custom headers, so it goes through the mcp-remote bridge. ~/.codex/config.toml:

[mcp_servers.<name>]
command = "npx"
args = ["-y", "mcp-remote", "<url>", "--header", "X-Api-Token:<key>"]

Claude Desktop

Same bridge situation as Codex — Claude Desktop's config is stdio-only and can't send custom headers natively. claude_desktop_config.json:

{
  "mcpServers": {
    "<name>": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "<url>", "--header", "X-Api-Token:<key>"]
    }
  }
}

Any other MCP client

If your client isn't listed above, the raw connection facts:

Transport:  SSE (remote)
URL:        <url>
Header:     X-Api-Token: <key>

# Clients that only speak stdio (no custom headers) can bridge via:
#   npx -y mcp-remote <url> --header "X-Api-Token:<key>"

SportsClaw

SportsClaw is the reference external agent this connection flow was built around — see Ecosystem → SportsClaw for its own sportsclaw mcp add command and how it fits together end to end.

Related

• MCP Overview — the shared endpoint these snippets connect to.
• connect — mint a durable, project-scoped token instead of using an ambient session/API key.