> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://natural.ferndocs.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://natural.ferndocs.com/_mcp/server.

# MCP

Natural runs a hosted Model Context Protocol server at `https://mcp.natural.co`. Connect OAuth-capable MCP clients such as Codex, Cursor, and Claude Code without creating or pasting an API key.

> **Note**
>
> 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
Read https://natural.co/skill.md and set up Natural for me.
Connect this agent 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.

### Codex

```bash
codex mcp add natural --url https://mcp.natural.co
codex mcp login natural
```

`codex mcp login` opens the browser OAuth flow. Natural's MCP connector grants its tools access to payments, wallet balances and bank movement, agent reads and creation, and customer invitations.

### Cursor / cursor-agent

Merge Natural into `~/.cursor/mcp.json` or `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "natural": {
      "url": "https://mcp.natural.co"
    }
  }
}
```

Then authenticate:

```bash
agent mcp login natural
```

Use `agent mcp list-tools natural` to verify. If the Cursor editor does not show Natural immediately, refresh MCP tools or restart the window.

### Claude Code

```bash
claude mcp add --transport http natural https://mcp.natural.co --scope user
```

Then run `/mcp` inside Claude Code, choose `natural`, and select **Authenticate**. Claude Code opens the browser OAuth flow from there.

### 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.

Configure Natural with no `Authorization` header:

```json
{
  "mcpServers": {
    "natural": {
      "url": "https://mcp.natural.co"
    }
  }
}
```

### CLI OAuth fallback

If a host can run terminal commands but cannot do MCP OAuth, use the Natural CLI's browser OAuth:

```bash
curl -fsSL https://natural.co/install.sh | bash
natural login
natural status
```

### API-key fallback

Use an API 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.

Claude Code fallback:

```bash
claude mcp add --transport http natural https://mcp.natural.co \
  --scope user \
  --header "Authorization: Bearer $NATURAL_API_TOKEN"
```

## What you can do

The connector exposes 14 tools, each an intent-shaped wrapper around the Natural API. Each tool absorbs the orchestration (wallet resolution, idempotency keys, agent headers) so the agent sends a single natural-language call.

| Tool                     | Description                                     |
| ------------------------ | ----------------------------------------------- |
| `send_payment`           | Pay a counterparty by email, phone, or party ID |
| `request_payment`        | Create a payment link to collect funds          |
| `get_account_balance`    | Check available and pending balances            |
| `list_transactions`      | View recent transactions with filters           |
| `list_agents`            | List agents for the authenticated party         |
| `create_agent`           | Register a new agent                            |
| `invite_customer`        | Add a customer to an agent                      |
| `list_customers`         | List an agent's customers                       |
| `get_transaction`        | Get details for a single transaction            |
| `list_external_accounts` | View linked bank accounts                       |
| `initiate_deposit`       | Pull funds from bank to wallet                  |
| `initiate_withdrawal`    | Push funds from wallet to bank                  |
| `get_party`              | View party details                              |
| `create_payment_claim`   | Generate a hosted claim link                    |