> For the complete documentation index, see [llms.txt](https://docs.doma.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.doma.xyz/agentic-commerce/mcp-server/connect.md).

# 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
```

{% hint style="success" %}
**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.
{% endhint %}

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](/agentic-commerce/mcp-server/authorization.md).

## Claude Code

```bash
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):

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

## VS Code (GitHub Copilot)

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

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

## Codex CLI

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

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

## Windsurf

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

```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:

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

{% hint style="info" %}
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.
{% endhint %}

## 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](/agentic-commerce/mcp-server/authorization.md).                         |
| 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](/agentic-commerce/mcp-server/authorization.md#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](/agentic-commerce/doma-cli.md) with a dedicated wallet. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.doma.xyz/agentic-commerce/mcp-server/connect.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.