Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.natural.co/llms.txt

Use this file to discover all available pages before exploring further.

Natural runs a hosted Model Context Protocol server at https://mcp.natural.co. Connect any MCP-aware client — Claude Code, Cursor, Codex, Claude Desktop — with a Natural API key. No install required.
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.

​
Connect

Get an API key from the Developers tab of the dashboard — it’s shown once, store it in a secret manager. Then point your client at the MCP endpoint with the key as a bearer header.

​
Claude Code

claude mcp add --transport http natural https://mcp.natural.co \
  --scope user \
  --header "Authorization: Bearer sk_ntl_prod_..."
If Claude has trouble with the bare host endpoint, use https://mcp.natural.co/mcp. Verify with claude mcp list and claude mcp get natural; inside Claude Code, /mcp shows connection status.

​
Cursor, Codex, and other MCP clients

Point any MCP client at the endpoint with a JSON or TOML config: 
{
  "mcpServers": {
    "natural": {
      "type": "http",
      "url": "https://mcp.natural.co",
      "headers": { "Authorization": "Bearer sk_ntl_prod_..." }
    }
  }
}

[mcp_servers.natural]
url = "https://mcp.natural.co"
headers = { Authorization = "Bearer sk_ntl_prod_..." }
Do not commit a real key in shared repo config — use a user-local config or secret-backed header support.

​
What you can do

The connector exposes 13 tools — intent-shaped wrappers 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.
ToolPurpose
get_payment_statusLook up a single transaction by id (txn_*)
get_payment_requestLook up a single payment request by id (prq_*) — inbound counterpart
list_transactionsPaginated transaction history
get_account_balanceWallet balances + holds
create_paymentSend a payment — recipient is a flat email / phone / pty_* / agt_* string
request_paymentRequest a payment — payer is a flat email / phone / pty_* / agt_* string
deposit_fundsACH pull from a linked account; falls back to push-to-wallet instructions
withdraw_fundsACH push to a linked account; auto-selects when exactly one is linked
list_agentsYour agents
list_customersYour customer relationships (status is active, pending, or all)
create_agentMint a new programmatic actor (your own party only)
invite_customerSend a delegation invitation by email
get_funding_optionsLinked bank accounts + ACH push-to-wallet instructions in one view

​
Attribution for production agents

When the calling agent represents a specific Natural agent identity, pass attribution fields so transactions are auditable:
  • agentId — Natural agent id (agt_*)
  • instanceId — stable run / session / conversation id; required whenever agentId is provided
  • traceId — optional cross-system trace id for correlating MCP and downstream API calls
  • Authentication — API keys and scopes
  • Agents — the autonomous-actor model behind the connector
  • SDKs — for your own agent runtime
  • CLI — for terminal and CI use