MCP

Natural runs a hosted Model Context Protocol server at https://mcp.natural.com. OAuth-capable hosts such as Claude, Claude Code, ChatGPT, Codex, and Cursor connect with browser OAuth. No API key to create or paste.

Use MCP when an AI host (Claude, Cursor, etc.) runs the agent for you. Building your own agent runtime? Use the SDKs or CLI instead.

Connect your host

Everyday use
For developers

Claude

Custom connectors work on every Claude plan, and the Free plan allows one. On Team and Enterprise plans, an Owner must add the connector for your organization before you can connect it. The setup is the same for claude.ai and the Claude Desktop app.

In claude.ai or the Claude Desktop app, open the sidebar, select Customize, and go to the Connectors tab.
Select Add custom connector and fill in the fields: name Natural, remote MCP server URL https://mcp.natural.com.
Select Add, then Connect. Your browser opens Natural’s authorization page; approve it, and you are redirected back to Claude.

Try it in chat:

Use Natural to check my wallet balance.

ChatGPT

Custom plugins require a paid ChatGPT plan (Plus, Pro, Business, or Enterprise).

Open Settings → Security and turn on Developer mode.
Select Plugins in the sidebar, then the + button, and fill in the fields: name Natural, MCP server URL https://mcp.natural.com, authentication OAuth.
Accept ChatGPT’s unverified-server disclaimer and select Create, then Sign in with Natural. Approve Natural’s authorization page when it opens.

Try it in chat:

Use Natural to check my wallet balance.

Claude Code

Add Natural’s hosted MCP server and sign in with OAuth. Your browser opens Natural’s authorization page; approve it:
claude mcp add --transport http natural https://mcp.natural.com --scope user && claude mcp login natural
Start a fresh Claude Code session and run /mcp. Confirm natural shows as connected and authenticated. If it’s not, run claude mcp login natural again to re-authorize.

Try it:

Use Natural to check my wallet balance.

Codex CLI

Add Natural as a remote HTTP server, then approve Natural’s authorization page in your browser. If the browser does not open on its own, run codex mcp login natural:
codex mcp add natural --url https://mcp.natural.com
Start a fresh Codex session and run /mcp. Confirm natural shows as connected and authenticated. If it’s not, run codex mcp login natural again to re-authorize.

Try it:

Use Natural to check my wallet balance.

Codex app

Open the Codex app and go to Plugins in the sidebar.
Open the dropdown (⌄) in the top right, select Add marketplace, and paste this into the Source field:
naturalpay/agent-plugins
Switch to Personal and select Install. Your browser opens Natural’s authorization page; approve it.

Try it in chat:

Use Natural to check my wallet balance.

Cursor

Add Natural to Cursor. Cursor asks you to confirm the install; approve it. Add to Cursor Or add it manually: merge Natural into ~/.cursor/mcp.json and save:
{ "mcpServers": { "natural": { "url": "https://mcp.natural.com" } } }
Open Customize in Cursor’s sidebar, find Natural, and connect it. Your browser opens Natural’s authorization page; approve it, and you are redirected back to Cursor. If Natural doesn’t appear, restart Cursor.

Try it:

Use Natural to check my wallet balance.

Agent key (API)

For headless or custom agents that can’t sign in with browser OAuth: create an agent key and use it as the bearer token against mcp.natural.com or the REST API. See the API-key fallback for details.

Any other MCP-aware host

Most hosts have a UI action, command, or config file for adding a remote MCP server and signing in. Point it at https://mcp.natural.com with no Authorization header so it uses OAuth. For hosts that take mcpServers JSON:

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

Use https://mcp.natural.com; use https://mcp.natural.com/mcp only for legacy clients that require an explicit endpoint path.
Set the auth mode to OAuth if the host has one; a bare URL entry defaults to no auth on many hosts and silently skips sign-in.
After signing in, verify by listing Natural tools or calling a read-only tool like get_account_balance. If tools are missing, reload the host once and check again.

CLI OAuth fallback

If a host can run terminal commands but has no MCP OAuth flow, sign in with the Natural CLI before reaching for an API key:

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

natural login authenticates locally with OAuth, then the CLI’s full command surface is available.

API-key fallback

Use a key only when neither hosted MCP OAuth nor CLI OAuth works: headless CI, SDK/REST integrations, or non-interactive scripts. Pass it 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 config.

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

Who an OAuth connection acts as

When you approve the connection, pick one of your agents or create a new one. Every tool call runs as that agent, and the audit log records both the agent and you. If there is no agent for you to pick or create, the connection acts as you instead. An agent connection can’t create agents or manage API keys. Do those in the dashboard or with a party API key. To switch agents, disconnect Natural in your AI host and reconnect.

What you can do

Each tool is shaped around an intent.

Tool	Purpose
`get_transaction_status`	Look up a single payment or transfer by id (`pay_` or `trf_`)
`wait_for_transaction`	Block until a payment/transfer reaches a terminal status (event-driven; default 25s, max 60s)
`list_payment_requests`	List open incoming requests or outgoing requests, with pagination, outgoing groups, and optional customerPartyId
`get_payment_request`	Look up a payment request by id (`prq_*`)
`list_transactions`	Paginated transaction history, filterable by wallet and type
`get_account_balance`	Wallet balance
`list_wallets`	Wallet names, IDs, types, status, tags, defaults, and balances; agents see only granted wallets
`get_identity`	Caller party, acting agent when present, handles, and credential permissions
`get_party_limits`	Per-transaction, daily, and monthly spend limits for the party (read-only)
`list_external_accounts`	Linked external accounts and their connection status
`get_external_account`	One linked external account by id (`eac_*`)
`create_payment`	Send a payment. Recipient is an email / phone / `@handle` / `pty_` / `agt_`
`cancel_payment`	Cancel a pending-claim outbound payment by id (`pay_*`) before it is claimed
`cancel_payment_request`	Withdraw an open outgoing payment request (`prq_*`), optionally on behalf of a customer
`request_payment`	Request a payment. Payer is an email / phone / `@handle` / `pty_` / `agt_`
`fulfill_payment_request`	Pay a request after confirming its current amount and currency
`decline_payment_request`	Decline an incoming request (`prq_*`) without paying it
`deposit_funds`	Own-party deposits support automatic account selection and ACH instructions fallback; customer deposits require an explicit account ID
`withdraw_funds`	Own-party withdrawals can auto-select a single eligible account; customer withdrawals require an explicit account ID
`transfer_between_wallets`	Move funds between your own wallets or between one customer’s wallets (`wal_` to `wal_`); returns `trf_*`
`list_agents`	Your agents
`list_customers`	Your customer relationships (`status` is `active`, `pending`, `revoked`, or `all`)
`create_agent`	Create an agent with a name, description, wallet, slug (the last part of its `@handle`), and optional spend limits. Not available on agent connections
`invite_customer`	Invite email, phone, or party-ID recipients with per-agent settings
`get_funding_options`	Party-linked bank accounts + ACH deposit instructions for an optional walletId

Direct payouts

These tools pay third parties by ACH, wire, or realtime payment. Direct must be enabled for your account. If you connected before Direct was available, disconnect and reconnect to get these tools.

Tool	Purpose
`create_external_party`	Add a payee (`epty_*`)
`update_external_party_address`	Set or correct a payee’s address (required for wires)
`list_external_parties`	List your payees
`get_external_party`	Look up one payee by id (`epty_*`)
`create_external_party_account`	Save a payee’s US bank account (`epa_*`)
`list_external_party_accounts`	List a payee’s saved bank accounts
`get_external_party_account`	Look up one saved bank account by id (`epa_*`)
`create_ach_payment`	Send an ACH payment to a payee’s bank account (`ach_*`)
`create_wire_payment`	Send a domestic USD wire to a payee’s bank account (`wire_*`)
`create_realtime_payment`	Send a realtime payment to a payee’s bank account (`rt_*`)
`list_direct_payments`	List ACH, wire, or realtime payments
`get_direct_payment`	Look up one payment by id (`ach_`, `wire_`, or `rt_*`)
`cancel_direct_payment`	Cancel a payment before it is sent to the bank

Amounts and currencies

MCP payment tools use a decimal amount and a three-letter currency code:

{
  "amount": "10.50",
  "currency": "USD"
}

Natural preserves the amount you give it: $5 becomes "5.00" and $5.3 becomes "5.30" without changing the value. If an amount cannot be represented exactly (for example, a USD amount with fractions of a cent), Natural rejects it; ask for an exact amount instead of rounding. The payment tool accepts only exact decimal amounts without currency symbols or commas, and currency is always required. In manual approval mode, your host shows the amount, currency, and destination before the payment runs. When paying a payment request, Natural checks its current amount and currency again and stops if either changed.

This format applies to MCP. Natural’s REST API and SDKs use integer cents. See Data formats.

Attribution for production agents

With an agent-scoped OAuth grant or an agent key, agent identity is carried by the credential. For money-moving tools, pass instanceId every run so each is auditable. With a user-scoped grant or a party API key, tool calls are user/party actions and need no attribution fields. Tools do not take an agentId argument: agent identity comes only from an agent-scoped OAuth grant or an agent key.

Test in the sandbox

The sandbox runs its own MCP server at https://mcp.sandbox.natural.com. Connect it like the production server; it adds sandbox-only tools (simulate_customer_deposit, simulate_customer_invitation_accept, and others) so an agent can drive both sides of a flow. See Sandbox from MCP, CLI, and SDKs.

Docs MCP server

This documentation runs its own MCP server at https://docs.natural.com/mcp, separate from the payments server at mcp.natural.com. It requires no Natural account or credentials, so an agent can use it before signup or OAuth. Its tools search these docs, read full pages, and pull the exact request shape of any endpoint from the OpenAPI spec.

{
  "mcpServers": {
    "natural-docs": {
      "url": "https://docs.natural.com/mcp"
    }
  }
}

Connect it alongside the payments server while integrating; it is read-only and moves no money.

Troubleshooting

Missing tools after connecting: Reload the host’s MCP tools or restart the host window after OAuth completes.
Auth fails after a previous success: Disconnect Natural in the host, reconnect, and approve the OAuth screen again.
Tool reports missing account setup: Finish KYC/KYB, wallet, or linked-bank setup in the Natural dashboard, then reconnect.

For support, include the host name, server URL used, approximate timestamp, your Natural email, any request ID, any visible identifier (txn_*, prq_*, pay_*), and the exact error text.

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

Overview

Agents

Customers

Payments

Transactions

Transfers

Payment Requests

Payment Intents

Plans

Card Payments

Voice Sessions

Refunds

Chargebacks

Approvals

Limits

Parties

Party Invitations

Wallets

Wallet Access

External Accounts

Cards

Agent checkout

API Keys

Agent Keys

Webhooks

Events

Errors

Connect your host

Any other MCP-aware host

CLI OAuth fallback

API-key fallback

Who an OAuth connection acts as

What you can do

Direct payouts

Amounts and currencies

Attribution for production agents

Test in the sandbox

Docs MCP server

Troubleshooting

​Connect your host

​Any other MCP-aware host

​CLI OAuth fallback

​API-key fallback

​Who an OAuth connection acts as

​What you can do

​Direct payouts

​Amounts and currencies

​Attribution for production agents

​Test in the sandbox

​Docs MCP server

​Troubleshooting

​Related

Connect your host

Any other MCP-aware host

CLI OAuth fallback

API-key fallback

Who an OAuth connection acts as

What you can do

Direct payouts

Amounts and currencies

Attribution for production agents

Test in the sandbox

Docs MCP server

Troubleshooting

Related