MCP - Natural Docs

Natural runs a hosted Model Context Protocol server at https://mcp.natural.co. Connect OAuth-capable MCP clients such as Claude, Claude Code, ChatGPT, Codex, and Cursor without creating or pasting an API key.

MCP is the right path when an AI host application (Claude, Cursor, etc.) runs the agent for you. If you’re building your own agent runtime, reach for the SDKs or CLI instead.

Install

Bootstrap (AI assistants, recommended)

Ask your AI assistant to read Natural’s agent playbook:

Read https://natural.co/skill.md and set up Natural for me. Connect this agent to Natural with OAuth, then use Natural's MCP tools for my request.

The assistant should install the MCP server, start OAuth, and tell you when to approve the Natural authorization page in your browser.

Claude Desktop

Go to Settings → Connectors → Add custom connector
Add this MCP link: https://mcp.natural.co
For details, review Claude Desktop documentation.

ChatGPT

Turn on Developer Mode
Go to Settings → Apps → Create app
Add this MCP link: https://mcp.natural.co
For details, review ChatGPT documentation.

Codex

Add and sign in to Natural from your terminal:

codex mcp add natural --url https://mcp.natural.co
codex mcp login natural

codex mcp login opens the browser OAuth flow
MCP connector grants access to: payments, wallet balances and bank movement, agent reads and creation, and customer invitations
Does not include: team administration, API-key management, wallet lifecycle, or agent deletion

Claude Code

Add and sign in to Natural from your terminal:

claude mcp add --transport http natural https://mcp.natural.co --scope user

Run /mcp inside Claude Code, choose natural, and select Authenticate
Claude Code opens the browser OAuth flow from there

Cursor / cursor-agent

Merge Natural into ~/.cursor/mcp.json or .cursor/mcp.json:

{
  "mcpServers": {
    "natural": {
      "url": "https://mcp.natural.co"
    }
  }
}

Authenticate: run agent mcp login natural
Verify with agent mcp list-tools natural (cursor-agent also works as an alias)
If the Cursor editor does not show Natural immediately, refresh MCP tools or restart the window
Cursor asks for the same Natural MCP access during OAuth

Any other MCP-aware host

If your host is not listed above, look for its MCP server or connector settings — most hosts have a command, config file, or UI action for adding a remote MCP server and signing in
If it can add a remote MCP server, configure Natural with no Authorization header. Use the host’s own config shape; for hosts that use mcpServers JSON, it looks like this:

{
  "mcpServers": {
    "natural": {
      "url": "https://mcp.natural.co"
    }
  }
}

Use HTTP or streamable HTTP if the host asks for a transport. Use https://mcp.natural.co for Claude and directory review; use https://mcp.natural.co/mcp only for legacy or custom clients that require an explicit endpoint path
If the host exposes an OAuth login or authenticate action, start it. If the host lets you choose scopes, use the same scope list shown in the Codex example
Verify before proceeding by listing Natural tools or calling a read-only tool such as get_account_balance, list_agents, or list_transactions. If tools are missing right after auth, reload the host once and verify again
OpenClaw is config-only: openclaw mcp set natural '{"url":"https://mcp.natural.co","transport":"streamable-http"}' saves the server definition, but OpenClaw exposes no MCP-server OAuth login, so after adding Natural use the CLI OAuth fallback below (natural login)

CLI OAuth fallback

If a host can run terminal commands but can configure no MCP OAuth flow, use the Natural CLI’s browser OAuth before asking for an API key:

curl -fsSL https://natural.co/install.sh | bash
natural login
natural status

natural login signs the CLI in locally with OAuth so you can keep working without creating or pasting an API key. After sign-in, the CLI supports its full command surface.

API-key fallback

Use an API key only when hosted MCP OAuth and CLI OAuth cannot work: headless CI, SDK or REST integrations, non-interactive scripts, or MCP hosts that support neither remote-server OAuth nor a CLI. Keep keys out of chat, source control, and committed MCP config. Claude Code fallback:

claude mcp add --transport http natural https://mcp.natural.co \
  --scope user \
  --header "Authorization: Bearer $NATURAL_API_KEY"

Codex fallback:

[mcp_servers.natural]
url = "https://mcp.natural.co"
bearer_token_env_var = "NATURAL_API_KEY"

Generic fallback:

{
  "mcpServers": {
    "natural": {
      "url": "https://mcp.natural.co",
      "headers": { "Authorization": "Bearer <NATURAL_API_KEY>" }
    }
  }
}

What you can do

The connector exposes 14 tools, each an intent-shaped wrapper around the Natural API. Each tool absorbs the orchestration (wallet resolution, payer-kind detection, single-account auto-select) so the agent expresses what it wants without chaining calls.

Tool	Purpose
`get_payment_status`	Look up a single transaction by id (`txn_*`)
`get_payment_request`	Look up an inbound payment request by id (`prq_*`)
`list_transactions`	Paginated transaction history
`get_account_balance`	Wallet balances + holds
`create_payment`	Send a payment. Recipient is a flat email / phone / `pty_` / `agt_` string
`cancel_payment`	Cancel a pending-claim outbound payment by id (`pay_*`) before it is claimed
`request_payment`	Request a payment. Payer is a flat email / phone / `pty_` / `agt_` string
`deposit_funds`	ACH pull from a linked account; falls back to push-to-wallet instructions
`withdraw_funds`	ACH push to a linked account; auto-selects when exactly one is linked
`list_agents`	Your agents
`list_customers`	Your customer relationships (`status` is `active`, `pending`, or `all`)
`create_agent`	Mint a new programmatic actor (your own party only)
`invite_customer`	Send a customer invitation by email
`get_funding_options`	Linked bank accounts + ACH push-to-wallet instructions in one view

Attribution for production agents

When the calling agent represents a specific Natural agent identity, pass attribution fields so transactions are auditable:

agentId: Natural agent id (agt_*)
instanceId: stable run / session / conversation id; required whenever agentId is provided
traceId: optional cross-system trace id for correlating MCP and downstream API calls

Troubleshooting

Use the root server URL, https://mcp.natural.co, for Claude, Claude Code, and directory review. OAuth sign-in requires a Natural account that is ready to use the payment and agent surfaces exposed by the connector. If a tool reports missing account setup, KYC/KYB, wallet, or linked-bank-account state, finish that setup in the Natural dashboard and reconnect the MCP host. If a host connects but tools are missing, reload the host’s MCP tools or restart the host window after OAuth completes. If authentication fails after a previous successful connection, disconnect Natural in the host, reconnect, and approve the Natural OAuth screen again. For support, include the MCP host name, the server URL used, the approximate timestamp, the Natural user email, any request ID from the error response or response headers, any visible Natural identifier such as txn_*, prq_*, or pay_*, and the exact error text from the host or tool response.

Authentication — API keys and scopes
Agents — The autonomous-actor model behind the connector
SDKs — Python and TypeScript client libraries
CLI — For terminal and CI use

​Install

​Bootstrap (AI assistants, recommended)

​Claude Desktop

​ChatGPT

​Codex

​Claude Code

​Cursor / cursor-agent

​Any other MCP-aware host

​CLI OAuth fallback

​API-key fallback

​What you can do

​Attribution for production agents

​Troubleshooting

​Related

Install

Bootstrap (AI assistants, recommended)

Claude Desktop

ChatGPT

Codex

Claude Code

Cursor / cursor-agent

Any other MCP-aware host

CLI OAuth fallback

API-key fallback

What you can do

Attribution for production agents

Troubleshooting

Related