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://www.natural.co/skill.md and set up Natural for me. Connect my assistant 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 a 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. Both Natural key types are accepted as the bearer token:

API key (sk_ntl_…) — tool calls act as your party.
Agent key (ak_ntl_…) — tool calls act as the bound agent, verified by the credential.

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>" }
    }
  }
}

User-scoped vs agent-scoped OAuth

Natural’s OAuth consent screen lets you choose who the connection acts as:

As me (user-scoped) — tool calls are your own user/party actions. Money movement works without any agent attribution. This is the default, and grants created before agent-scoped consent existed continue to work user-scoped until you reconnect and reconsent.
As an agent (agent-scoped) — choose New agent to create an agent during OAuth approval, or pick one of your existing agents. Every tool call then acts as that agent with a verified binding, and audit records the selected agent plus the authorizing user. Reconnecting later can create another agent only if you choose New agent again; choose an existing agent to reuse it. Agent-scoped connections are clamped by the agent credential policy — they cannot call create_agent or manage API/agent keys after authorization.

To switch an existing connection between modes, disconnect Natural in the host and reconnect with the other selection.

What you can do

The connector exposes 16 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_transaction_status`	Look up a single payment or transfer by id (`pay_` or `trf_`)
`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
`fulfill_payment_request`	Pay an incoming request (`prq_*`) from your wallet or a linked bank account
`decline_payment_request`	Decline an incoming request (`prq_*`) without paying it
`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

Amounts are integer US cents

Every money parameter and result field is an integer in US cents (minor units): 1050 is

10.50, `500000` is

5,000.00. Convert dollar amounts before calling a money tool — never send 10.5 or "10.50". Tool results also carry display siblings (amountDisplay, balanceDisplay, e.g. "$10.50") so agents can report amounts to users without converting. See Data formats for the platform-wide convention.

Attribution for production agents

With an agent-scoped OAuth grant or an agent key, agent identity is already carried by the credential. For money-moving tools, pass instanceId every time so each run is auditable. With a user-scoped grant or a party API key, tool calls are user/party actions by default and need no attribution fields. Existing integrations that still use claimed agent attribution can pass agentId for now; prefer agent-scoped OAuth or agent keys for new agent integrations.

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

​User-scoped vs agent-scoped OAuth

​What you can do

​Amounts are integer US cents

​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

User-scoped vs agent-scoped OAuth

What you can do

Amounts are integer US cents

Attribution for production agents

Troubleshooting

Related