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 require a paid Claude plan (Pro, Max, Team, or Enterprise). 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

In Cursor, open Settings → Tools & MCPs, select New MCP Server (this opens mcp.json), merge Natural into the config, and save:
{ "mcpServers": { "natural": { "url": "https://mcp.natural.com" } } }
Find Natural under Settings → Tools & MCPs 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>" }
    }
  }
}

User-scoped vs agent-scoped OAuth

Natural’s consent screen determines who the connection acts as:

As an agent (agent-scoped) — The default: pick one of your existing agents or create a new one during approval. Every tool call then acts as that agent with a verified binding, and audit records both the agent and the authorizing user. Agent-scoped connections can’t call create_agent or manage keys.
As me (user-scoped) — Tool calls are your own user/party actions, with no agent attribution needed. A consent screen with no agent selection grants user-scoped access.

To switch modes, disconnect Natural in the host and reconnect with the other selection.

What you can do

The connector exposes 24 tools, each shaped around an intent. Each one handles the orchestration for you (finding the right wallet, detecting the payer type, auto-selecting a single account), so the agent just says what it wants instead of chaining calls.

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; max 60s)
`get_payment_request`	Look up a payment request by id (`prq_*`)
`list_transactions`	Paginated transaction history
`get_account_balance`	Wallet balance (available plus pending claims)
`list_wallets`	Wallet IDs, names, status, default flags, and balances for user/party callers
`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 provider connection status
`get_external_account`	One linked external account by id (`eac_*`)
`create_external_account_from_processor_token`	Link or refresh external accounts from a Plaid processor token
`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
`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`	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 active
`transfer_between_wallets`	Move funds between two of your own wallets (`wal_` to `wal_`); returns `trf_*`
`list_agents`	Your agents
`list_customers`	Your customer relationships (`status` is `active`, `pending`, `revoked`, 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 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), the agent should ask which exact amount to send instead of rounding it. 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 minor units. 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. Older integrations can still pass agentId for claimed attribution; prefer agent-scoped OAuth or agent keys for new agent integrations.

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

Approvals

Limits

Parties

Party Invitations

Wallets

Wallet Access

External Accounts

API keys

Agent keys

Webhooks

Events

Errors

Connect your host

Any other MCP-aware host

CLI OAuth fallback

API-key fallback

User-scoped vs agent-scoped OAuth

What you can do

Amounts and currencies

Attribution for production agents

Troubleshooting

​Connect your host

​Any other MCP-aware host

​CLI OAuth fallback

​API-key fallback

​User-scoped vs agent-scoped OAuth

​What you can do

​Amounts and currencies

​Attribution for production agents

​Troubleshooting

​Related

Connect your host

Any other MCP-aware host

CLI OAuth fallback

API-key fallback

User-scoped vs agent-scoped OAuth

What you can do

Amounts and currencies

Attribution for production agents

Troubleshooting

Related