Connect an MCP client

What is MCP?

MCP (Model Context Protocol) is an open protocol for connecting AI agents to external tools. Conto’s MCP server gives Claude and other MCP clients tools to check balances, request payments, read transactions, and query analytics. Conto checks the agent’s policies before any payment moves. The same @conto_finance/mcp-server package works in Claude Desktop, Claude Code, and other MCP clients. When a user asks for a payment, the client calls a Conto tool. Conto approves the request, denies it, or sends it to a person for approval. Conto sends an approved payment from a managed wallet, and the client reports the receipt. Sandbox payments are simulated. External wallets use approve, your own transfer, then confirm. See wallet custody. See MCP tools for every tool.

MCP vs dashboard assistant vs Conto Pay

Conto has three natural-language surfaces:

Surface	Who acts	Reach it via	Auth	Onchain execution
MCP server	Your own external AI agent (Claude Desktop, Claude Code, other MCP clients)	An MCP client wired to your agent	Agent SDK key (`conto_agent_...`)	Yes, with custody-aware policy checks before execution
Dashboard assistant (Conto AI)	You, working in the dashboard	Dashboard chat panel	Dashboard login	Yes, when you confirm a final approval on a managed wallet or a Conto Pay payment
Conto Pay	A Conto-hosted payment agent	Dashboard chat workspace	Dashboard login	Yes, through the normal request, approval, and execution flow

Prerequisites

An MCP client, such as Claude Desktop or Claude Code
A Conto agent SDK key (conto_agent_...). In the dashboard, open Agents, select the agent, open the SDK Integration tab, and choose Generate SDK Key.
Node.js 20.19+, with Node.js 22 requiring 22.12+ and Node.js 23 requiring 23.2+, because the server runs through npx

The MCP server always uses CONTO_API_KEY=conto_agent_.... Do not use an organization API key (conto_...) or CONTO_ORG_API_KEY here.

Already ran the CLI wizard? Use npx @conto_finance/create-conto-agent mcp as the server command in the configs below and drop the env block. It reads the SDK key and base URL the wizard saved.

Add the server

In each config below, replace conto_agent_xxx... with your SDK key.

Claude Code
Claude Desktop

Add Conto as an MCP server in one command:

claude mcp add conto \
  --env CONTO_API_KEY=conto_agent_xxx... \
  --env CONTO_BASE_URL=https://conto.finance \
  -- npx @conto_finance/mcp-server

Environment flags must come before the --. Everything after -- is the command Claude Code runs for the server, so flags placed there would be passed to npx instead.

Verify

Start a new Claude Code session:

> What are my wallet balances?

Claude calls the get_wallets tool.

Manage the server

claude mcp list      # list configured MCP servers
claude mcp remove conto

Add Conto to your Claude Desktop config file:

{
  "mcpServers": {
    "conto": {
      "command": "npx",
      "args": ["@conto_finance/mcp-server"],
      "env": {
        "CONTO_API_KEY": "conto_agent_xxx...",
        "CONTO_BASE_URL": "https://conto.finance"
      }
    }
  }
}

Config file: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Verify

Restart Claude Desktop.
Look for the tools icon in the chat input. Conto’s tools should appear in the list.
Ask: “What are my wallet balances?”

Configuration reference

Env var	Default	Required
`CONTO_API_KEY`	none	Yes. Agent SDK key, format `conto_agent_...`.
`CONTO_BASE_URL`	`https://conto.finance`	No. API base URL.
`CONTO_BROWSER_RUNTIME_URL`	none	No. HTTPS endpoint for a trusted guarded-browser runtime.
`CONTO_BROWSER_RUNTIME_TOKEN`	none	Yes when the browser runtime URL is configured.
`CONTO_BROWSER_OBSERVATION_URL`	none	No. Same-origin endpoint that enables `observe_browser_session`.
`CONTO_BROWSER_SESSIONS_URL`	none	No. Same-origin endpoint that enables the session create and release tools.

Leave the CONTO_BROWSER_* settings unset unless you run a guarded browser runtime. See guarded browser checkout for the tools they add.

Guarded browser runtime settings

CONTO_BROWSER_RUNTIME_URL and CONTO_BROWSER_RUNTIME_TOKEN enable guarded_browser_checkout. Set both or neither. With only one set, the server exits at startup. The token must contain at least 32 characters and be a dedicated service credential. Conto API keys are rejected. The observation and sessions URLs must be on the same origin as the runtime URL and distinct from it. The browser runtime must own the page and must be the agent’s only route to payment-sensitive click or submit actions. Use createGuardedPlaywrightCheckoutHttpHandler from @conto_finance/sdk/playwright to mount the authenticated endpoint the MCP server calls around your guarded Playwright runtime.

Get started

Integrate

Payments

Conto Commerce

Spending controls

Operate

Conto Pay

Connect an MCP client

What is MCP?

MCP vs dashboard assistant vs Conto Pay

Prerequisites

Add the server

Verify

Manage the server

Verify

Configuration reference

Next steps

MCP tools

Set up with the CLI

​What is MCP?

​MCP vs dashboard assistant vs Conto Pay

​Prerequisites

​Add the server

​Verify

​Manage the server

​Verify

​Configuration reference

​Next steps

MCP tools

Set up with the CLI

What is MCP?

MCP vs dashboard assistant vs Conto Pay

Prerequisites

Add the server

Verify

Manage the server

Verify

Configuration reference

Next steps