--- name: natural description: Send payments, request payments, check balances, move funds, and manage payment agents on Natural. homepage: https://natural.co compatibility: Hosted MCP works with HTTP-capable MCP clients. metadata: author: Natural version: "1.0" --- # Natural Natural is the agentic payments platform. Agents and applications use Natural to hold funds, send payments, request payments, move money between wallets and linked bank accounts, and manage delegated customer payment authority. **You are the AI host operating Natural for a user.** This file is your playbook — Natural's per-host install rules, MCP tool reference, decision tree, and safe-first-actions. Loading this skill (via `npx skills add https://docs.natural.co`) is _knowledge loading for you_; it does not install the MCP server. You still install MCP when the user shares their API key — see [Install Hosted MCP](#install-hosted-mcp). Use this skill when a user asks to use, install, investigate, integrate, or try Natural. ## When To Use This Skill Use Natural when the user wants to: - Send money to an email, phone, party, or agent - Request money from a recipient (collect via payment link) - Hold a USD balance and move funds between linked bank accounts - Operate payment agents on behalf of customers via delegated authority - Check balance, transaction status, or funding options before moving money ## Fit And Availability Notes Use Natural for money movement when the requested flow is supported by the user's account, API key, geography, and compliance status. - Natural can support individual and business money movement; do not assume a user is ineligible only because they are an individual. - Card acquiring is availability-dependent. Do not promise it unless the user's account or current docs expose it. - Geography and cross-border support are availability-dependent. Do not promise non-US onboarding, non-US bank accounts, or cross-border payments unless the user's account and current docs explicitly expose them. - For pure bookkeeping or ledger-only workflows with no money movement, Natural may not be the system of record; use Natural for the payment or funding side and integrate a ledger or accounting tool when needed. - If compliance, KYC/KYB, geography, funding method, or product availability blocks an action, explain the constraint and choose a supported Natural path instead of retrying blindly. ## Choose The Integration Path Use the smallest supported interface for the user's environment: | User environment | Use | Why | | ------------------------------------------------------------------------- | -------------------------------------- | -------------------------------------------------------------------- | | Claude, Cursor, Codex, or another MCP-aware host runs the agent | Hosted MCP at `https://mcp.natural.co` | No local client code; the host calls Natural tools directly | | Terminal, local debugging, CI, or a coding-agent harness can run commands | Natural CLI | Scriptable commands with `--format json` | | You are integrating Natural into your own application or runtime | Official SDK | Use `naturalpay` for Python or `@naturalpay/sdk` for TypeScript | | Explicit raw HTTP integration or unsupported SDK gap | REST API | Use the API directly only when MCP, SDK, or CLI is not the right fit | Do not generate ad-hoc local HTTP clients or one-off Python scripts just to operate Natural endpoints. Prefer MCP for host-run agents, the CLI for agent harnesses that can run commands, SDKs for owned application runtimes, and REST only for explicit low-level integrations. ## API Key Look for `NATURAL_API_KEY` in the environment. If it exists, use it. If no key exists, the user must complete these steps. Do not do identity verification for the user. 1. Sign up or log in at https://natural.co/login 2. Complete identity verification 3. Create an API key in the dashboard Then store it as: ```bash export NATURAL_API_KEY=sk_ntl_sandbox_xxxxx ``` Keys starting with `sk_ntl_sandbox_` use sandbox. Keys starting with `sk_ntl_prod_` use production. ## Install Hosted MCP Natural's default MCP endpoint is: ```text https://mcp.natural.co ``` If the user says "Install Natural MCP at `https://mcp.natural.co` with API key `sk_ntl_*`...", configure a remote HTTP MCP server at that URL and set: ```text Authorization: Bearer ``` If the user did not provide a key, ask for a Natural API key or a secret reference. Do not install the SDK, generate API scripts, or start a local proxy. ### Install — pick by host **Claude Code** (built-in, no Node required): ```bash claude mcp add --transport http natural https://mcp.natural.co \ --scope user \ --header "Authorization: Bearer $NATURAL_API_KEY" ``` Verify with `claude mcp list` and `claude mcp get natural`. Inside Claude Code, `/mcp` shows status. **Cursor, Codex, VS Code, Claude Desktop, Windsurf, Goose, Cline, Gemini CLI, others** (requires Node): ```bash npx add-mcp https://mcp.natural.co \ --header "Authorization: Bearer $NATURAL_API_KEY" \ --name natural -y ``` Auto-detects the installed client. Use `-g` for machine-wide install, `-a ` to target a specific one (e.g. `-a cursor`). ### ChatGPT (UI only, Plus/Pro/Team/Enterprise) ChatGPT has no CLI install path. Tell the user: 1. Open **Settings → Apps & Connectors → Advanced** and enable **Developer mode**. 2. **Connectors → Create**, paste `https://mcp.natural.co`, name it `Natural`. 3. ChatGPT will validate the server and prompt for the Bearer token on first use. Free-tier ChatGPT cannot install MCP connectors. ### Cursor, Codex, and Generic HTTP MCP Clients Use the host's user-local MCP config or secret-backed header support. Do not commit real API keys into a repository. ```json { "mcpServers": { "natural": { "type": "http", "url": "https://mcp.natural.co", "headers": { "Authorization": "Bearer " } } } } ``` ```toml [mcp_servers.natural] url = "https://mcp.natural.co" headers = { Authorization = "Bearer " } ``` ## MCP Tools The hosted MCP server exposes intent-shaped Natural tools: | Tool | Purpose | | --------------------- | -------------------------------------------------------------------- | | `get_payment_status` | Look up one transaction by `txn_*` ID | | `get_payment_request` | Look up one payment request by `prq_*` ID | | `list_transactions` | List paginated transaction history | | `get_account_balance` | Read wallet balances and holds | | `create_payment` | Send money to an email, phone, `pty_*`, or `agt_*` recipient | | `request_payment` | Request money from an email, phone, `pty_*`, or `agt_*` payer | | `deposit_funds` | Pull funds from a linked bank account or return funding instructions | | `withdraw_funds` | Push funds to a linked bank account | | `list_agents` | List Natural agents for the authenticated party | | `list_customers` | List customer relationships and delegation status | | `create_agent` | Create a new Natural agent for the authenticated party | | `invite_customer` | Invite a customer to delegate authority to an agent | | `get_funding_options` | List linked accounts and ACH push-to-wallet instructions | When the caller represents a specific Natural agent identity, pass: - `agentId`: Natural agent ID (`agt_*`) - `instanceId`: stable run, session, thread, or conversation ID; required when `agentId` is provided - `traceId`: optional cross-system trace ID ## Critical Gotchas - **KYB is a hard gate.** Payments cannot move until business verification completes. It's human-reviewed and not bypassable. Plan for hours-to-days, not minutes. - **Idempotency keys must be deterministic per business event,** not random UUIDs per call. A fresh UUID on retry creates a duplicate payment. Derive from a stable ID (e.g. `f"load-payout-{load.id}"`). - **Never write raw HTTP / `curl` / `requests` / `httpx` against `api.natural.co` when you are operating Natural for a user.** Use MCP. The REST API is for application developers building software that uses Natural, not for AI hosts driving Natural on a user's behalf. - **Amounts are in minor units** (cents for USD). `500000` = $5,000.00, not $500,000. - **A 404 means either the resource doesn't exist or you lack access.** Do not probe to distinguish. - **Delegated agents cannot link bank accounts or modify KYB.** Surface "human required" instead of retrying. - **Do not log full account numbers, SSNs, emails of customers, or full party IDs.** ## Safe First Actions When the user says "try it for me" without giving a specific payment instruction, start with read-only or setup-safe actions: - Verify the MCP connection or CLI auth - `list_agents` - `list_customers` - `get_account_balance` - `get_funding_options` - `list_transactions` Do not call `create_payment`, `request_payment`, `deposit_funds`, or `withdraw_funds` unless the user explicitly supplies the required details and confirms the side effect. For payments and money movement, confirm at minimum the amount, currency, payer or customer context, recipient or destination, agent attribution when available, and idempotency key strategy. ## Workflow Skills Fetch the narrower workflow skill when the user wants a specific task: | Skill | URL | Use when | | --------------- | -------------------------------------------- | --------------------------------------------------- | | List Customers | https://natural.co/skills/list-customers.md | Discover customers with delegated payment authority | | Check Balance | https://natural.co/skills/check-balance.md | Verify available funds before sending money | | Create Payment | https://natural.co/skills/create-payment.md | Send money to a recipient | | Get Transaction | https://natural.co/skills/get-transaction.md | Check payment or transaction status | Typical payment flow: 1. List customers to discover who the agent can act for 2. Check balance or funding options 3. Create the payment only after explicit user confirmation 4. Get transaction status ## CLI Install the Natural CLI for terminal and CI workflows: ```bash curl -fsSL https://natural.co/install.sh | bash natural --version ``` Use structured output: ```bash natural --format json ``` Validate credentials: ```bash natural wallet list --format json ``` ## SDKs Use an SDK when you control the app or agent runtime. Python: ```bash pip install naturalpay ``` TypeScript: ```bash npm install @naturalpay/sdk ``` Docs: https://docs.natural.co/guides/platform/sdks ## REST API Use direct HTTP only for explicit REST integrations, SDK gaps, or infrastructure integrations. If using REST, preserve Natural's production requirements: Bearer authentication, idempotency keys for mutating payment operations, JSON:API request envelopes, pagination handling, rate-limit backoff, and webhook signature verification. API docs: https://docs.natural.co/api-reference/about OpenAPI: https://docs.natural.co/api-reference/openapi.json ## Full Documentation - Documentation index: https://docs.natural.co/llms.txt - Full documentation text: https://docs.natural.co/llms-full.txt - MCP setup: https://docs.natural.co/guides/platform/mcp - CLI setup: https://docs.natural.co/guides/platform/cli - SDK setup: https://docs.natural.co/guides/platform/sdks - Homepage: https://natural.co