Connect Your Client

Add one URL to your MCP client and you're done. Pick the network you want:

https://mcp.doma.xyz/mcp           # Doma Mainnet
https://mcp-testnet.doma.xyz/mcp   # Doma Testnet

Start on testnet. The read tools behave identically on both networks, and testnet lets you exercise the buy and swap flows without spending real money. New tools also reach testnet first.

No API key, token, or account is needed to connect. Authorization only comes up the first time the agent calls a tool that spends money — see Authorization & Spend Controls.

Claude Code

claude mcp add --transport http doma https://mcp.doma.xyz/mcp

Then run /mcp inside Claude Code to check the connection and, when you want the execute tools, to start the authorization flow.

Claude (web and desktop)

Open Settings → Connectors → Add custom connector, then paste the URL. Claude walks you through authorization in the browser when it's needed.

Cursor

Add the server to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "doma": {
      "url": "https://mcp.doma.xyz/mcp"
    }
  }
}

VS Code (GitHub Copilot)

Add it to .vscode/mcp.json in your workspace:

{
  "servers": {
    "doma": {
      "type": "http",
      "url": "https://mcp.doma.xyz/mcp"
    }
  }
}

Codex CLI

Add it to ~/.codex/config.toml:

[mcp_servers.doma]
url = "https://mcp.doma.xyz/mcp"

Windsurf

Add it to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "doma": {
      "serverUrl": "https://mcp.doma.xyz/mcp"
    }
  }
}

Any other MCP client

The server is a standard remote MCP server: Streamable HTTP transport, OAuth 2.1 with dynamic client registration (RFC 7591) and mandatory S256 PKCE, and RFC 9728 protected-resource metadata for discovery. Any spec-compliant client works with just the URL — most use a config block shaped like the Cursor example above.

If your client only supports local stdio servers, bridge to the remote one:

{
  "mcpServers": {
    "doma": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.doma.xyz/mcp"]
    }
  }
}

Client config formats change faster than these docs — if a block above doesn't match what your client expects, check its own MCP documentation. The only Doma-specific value is the URL.

Verify the connection

Ask the agent:

Ping the Doma MCP server and tell me which network it's on.

Then try a read:

Look up example.com on Doma and tell me if it's tokenized.

Troubleshooting

Symptom	Cause and fix
Client connects but lists no tools	Almost always a transport mismatch — the client is trying stdio or SSE against an HTTP server. Set the transport explicitly (--transport http, "type": "http"), or use the mcp-remote bridge above.
Tools list fine, but a buy or swap returns a 401	Expected. That's the authorization challenge; complete the OAuth flow in your client (in Claude Code, /mcp). See Authorization.
Authorization opens a browser and stalls on "Handing you back to your MCP client…"	Click the Return to your MCP client link on the page. Some browsers block the automatic hand-off; the link completes it.
A buy or swap is refused for insufficient allowance	Your spend cap is used up. Re-authorize to refill it — see Managing the allowance.
Everything works interactively but fails in CI	Headless environments can't complete a browser consent step. The read tier works unauthenticated in CI; for automated execution use the Doma CLI with a dedicated wallet.