> ## 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.
> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.
# MCP
> Connect AI hosts to Natural's hosted MCP server
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](/guides/platform/sdks) or [CLI](/guides/platform/cli) instead.
## Connect your host
[Sign up](https://natural.com/signup) and complete onboarding first; OAuth signs the host into your Natural account. Pick your tool:
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](https://claude.ai) and the Claude Desktop app.
1. In [claude.ai](https://claude.ai) or the Claude Desktop app, open the sidebar, select **Customize**, and go to the **Connectors** tab.
2. Select **Add custom connector** and fill in the fields: name `Natural`, remote MCP server URL `https://mcp.natural.com`.
3. Select **Add**, then **Connect**. Your browser opens Natural's authorization page; approve it, and you are redirected back to Claude.
4. Try it in chat:
```text theme={null}
Use Natural to check my wallet balance.
```
Custom plugins require a paid ChatGPT plan (Plus, Pro, Business, or Enterprise).
1. Open **Settings → Security** and turn on **Developer mode**.
2. Select **Plugins** in the sidebar, then the **+** button, and fill in the fields: name `Natural`, MCP server URL `https://mcp.natural.com`, authentication **OAuth**.
3. Accept ChatGPT's unverified-server disclaimer and select **Create**, then **Sign in with Natural**. Approve Natural's authorization page when it opens.
4. Try it in chat:
```text theme={null}
Use Natural to check my wallet balance.
```
1. Add Natural's hosted MCP server and sign in with OAuth. Your browser opens Natural's authorization page; approve it:
```bash theme={null}
claude mcp add --transport http natural https://mcp.natural.com --scope user && claude mcp login natural
```
2. 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.
3. Try it:
```text theme={null}
Use Natural to check my wallet balance.
```
1. 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`:
```bash theme={null}
codex mcp add natural --url https://mcp.natural.com
```
2. 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.
3. Try it:
```text theme={null}
Use Natural to check my wallet balance.
```
1. Open the Codex app and go to **Plugins** in the sidebar.
2. Open the dropdown (⌄) in the top right, select **Add marketplace**, and paste this into the **Source** field:
```text theme={null}
naturalpay/agent-plugins
```
3. Switch to **Personal** and select **Install**. Your browser opens Natural's authorization page; approve it.
4. Try it in chat:
```text theme={null}
Use Natural to check my wallet balance.
```
1. 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:
```json theme={null}
{
"mcpServers": {
"natural": {
"url": "https://mcp.natural.com"
}
}
}
```
2. 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.
3. Try it:
```text theme={null}
Use Natural to check my wallet balance.
```
For headless or custom agents that can't sign in with browser OAuth: create an [agent
key](/guides/concepts/agent-keys) and use it as the bearer token against `mcp.natural.com`
or the [REST API](/api-reference/about). See the [API-key
fallback](/guides/platform/mcp#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:
```json theme={null}
{
"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:
```bash theme={null}
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.
```json theme={null}
{
"mcpServers": {
"natural": {
"url": "https://mcp.natural.com",
"headers": { "Authorization": "Bearer " }
}
}
}
```
## 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](#api-key-fallback). 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:
```json theme={null}
{
"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](/api-reference/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](/api-reference/sandbox/overview) 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](/api-reference/sandbox/surfaces).
## 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](/api-reference/openapi.json).
```json theme={null}
{
"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.
## 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
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.