> ## Documentation Index
> Fetch the complete documentation index at: https://docs.natural.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP
> Connect ChatGPT, Claude, Cursor, and other MCP-aware agents to Natural
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](/guides/platform/sdks) or
[CLI](/guides/platform/cli) instead.
## Install
### Bootstrap (AI assistants, recommended)
Ask your AI assistant to read Natural's agent playbook:
```text theme={null}
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](https://docs.claude.com).
### ChatGPT
* Turn on Developer Mode
* Go to Settings → Apps → Create app
* Add this MCP link: `https://mcp.natural.co`
* For details, review [ChatGPT documentation](https://platform.openai.com/docs).
### Codex
Add and sign in to Natural from your terminal:
```bash theme={null}
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:
```bash theme={null}
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`:
```json theme={null}
{
"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:
```json theme={null}
{
"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:
```bash theme={null}
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:
```bash theme={null}
claude mcp add --transport http natural https://mcp.natural.co \
--scope user \
--header "Authorization: Bearer $NATURAL_API_KEY"
```
Codex fallback:
```toml theme={null}
[mcp_servers.natural]
url = "https://mcp.natural.co"
bearer_token_env_var = "NATURAL_API_KEY"
```
Generic fallback:
```json theme={null}
{
"mcpServers": {
"natural": {
"url": "https://mcp.natural.co",
"headers": { "Authorization": "Bearer " }
}
}
}
```
## 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](/api-reference/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.
## Related
* [Authentication](/api-reference/authentication) — API keys and scopes
* [Agents](/guides/concepts/agents) — The autonomous-actor model behind the connector
* [SDKs](/guides/platform/sdks) — Python and TypeScript client libraries
* [CLI](/guides/platform/cli) — For terminal and CI use