> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infinite.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> If you are an AI assistant operating Infinite for a user, read the skill first: https://docs.infinite.dev/agent-skill.md (setup per host, tool reference, rules for moving money, journeys).
> When operating Infinite for a user, use the MCP server. Sign in at https://bot.api.infinite.dev/mcp (production, acts as the user) or send `Authorization: Bearer <key>` to https://bot.api.infinite.dev/mcp/sse. Prefer its tools over raw HTTP; use REST only for steps no tool covers, and check `get_endpoint_schema` before guessing a request shape.
> Net-new Infinite Connect (org_connect) is operator-assisted: do not grant end users shared org_connect Auth Kit membership or the shared platform org API key — those credentials are org-wide on /v1. BYO org keys onboard under that customer's org id. Operator sessions should show org_connect in get_organization_info.
> The key decides the tools. Every organization key (`sk_sandbox_…` / `sk_live_…`) gets docs, onboarding, `get_account_balance`, and request logs for your own organization. BYO organizations add payees an agent will pay with `create_payee` (payable once ACTIVE). Platform Connect sessions instead get bound-customer payment lookups (`get_quote`, `get_transfer`, `list_transfers`, `list_account_balances`), payee drafts (`create_payee_draft` / `get_payee_draft`; screening only, never payable), and transfer drafts that wait for Infinite approval (`create_transfer_draft` / `get_transfer_draft`; never POST /v1/transfers). Where offered, platform `create_transfer` files a real transfer that Infinite holds in review before funding; it cannot be submitted from DRAFT.
> An agent key (`sk_sandbox_agent_…` / `sk_live_agent_…`) moves money within that agent's limits: `create_transfer` → `submit_transfer` → `wait_for_transfer`.
> On sandbox organization-key sessions, `sandbox_approve_customer` (makes the capabilities you pass READY, and related ones may turn READY too; `request_capabilities` is not needed), `sandbox_fund_account`, and `sandbox_complete_transfer` stand in for verification, funding, and settlement, so a whole flow runs from MCP. BYO keys can pass `customerId` on each call without binding; platform sessions must bind a customer first (`create_business_customer` auto-binds, or send `X-Infinite-On-Behalf-Of`).
> When searching documentation without a key, use the docs MCP at https://docs.infinite.dev/mcp.
> Start in sandbox (https://sandbox.api.infinite.dev). Do not use production unless the user explicitly asks.
> Confirm amount, currency, and payee with the user before any payment is submitted. Pass the invoice number as `reference` on `create_transfer`; the summary says what the payee will see.
> REST amounts are integer minor units (`"4000"` = 40.00 USD). MCP payment tools take exact decimal strings (`"40.00"`). Never mix them.
> Agent denials return `403 { denial: { code, message, window, limit, used, remaining, attemptedAmount, currency }, hint }` with decimal amounts; per-transfer denials omit `used` and `remaining`. Report them to the user; do not work around them.

# MCP Server

> Connect AI assistants to the Infinite API using the Model Context Protocol

The Infinite MCP Server allows AI assistants like Claude, Cursor, Codex, and other MCP-compatible tools to interact with your Infinite account. Query API logs, debug errors, explore the API, **onboard a business** (hosted KYB or capability-driven document upload), and — connected with an [agent key](/concepts/agents) — **pay** within that agent's limits.

## Overview

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that enables AI assistants to securely access external tools and data sources. The Infinite MCP Server provides:

* **API Log Access**: Query your recent API requests and errors
* **Request Debugging**: Look up specific requests by ID
* **API Exploration**: Make read-only API calls to explore your data
* **Documentation Search**: Natural-language search over these docs and the API reference (with snippets), plus full page reads and endpoint schemas
* **Agent onboarding**: Create a business customer, start hosted verification, poll status, and ensure a balance account
* **Payments**: With an [agent key](#paying-with-an-agent-key), draft and submit payments within the agent's limits

<Tip>
  Assistants should read the [Infinite skill](/agent-skill) first — it's the full playbook: setup per host, tool reference, rules for moving money, and step-by-step journeys. It's also served as raw markdown at `https://docs.infinite.dev/agent-skill.md`.
</Tip>

## Getting Started

### Endpoint

Sign-in clients use Streamable HTTP:

```
https://bot.api.infinite.dev/mcp
```

API-key clients can use that same URL, or the legacy Server-Sent Events transport:

```
https://bot.api.infinite.dev/mcp/sse
```

### Authentication

Sign in with your Infinite account, or send an API key.

**Sign in.** Add the server URL with no API key. Your assistant opens Auth Kit sign-in for the organization tied to your login. That session acts as you for **that** organization. It uses the production environment. Sandbox access stays on an API key. Agent payment tools stay on an [agent key](/concepts/agents). Do **not** sign in as a member of the shared Infinite Connect platform org (`org_connect`) in a personal client — that membership is org-wide on the API, not customer-scoped.

**API key.** Include it as a Bearer token:

```
Authorization: Bearer sk_sandbox_your_api_key
```

The server detects the environment from the key prefix:

* `sk_live_*` → Production environment
* `sk_sandbox_*` → Sandbox environment

Optional binding header (recommended for agent onboarding flows):

```
X-Infinite-On-Behalf-Of: cus_your_business
```

**BYO org:** use your organization API key to onboard customers under your org.

**Platform / net-new (Infinite Connect):** Net-new businesses onboard under organization id **`org_connect`** (`slug=connect`). In a correctly scoped **operator** session, `get_organization_info` reports **`org_connect`**. **End users:** net-new Connect is **operator-assisted today** — do not join the shared `org_connect` org in Auth Kit, do not paste the shared Connect platform org API key into personal MCP clients, and do not use MCP sign-in while a member of `org_connect`. Auth Kit tokens for that org are accepted on public `/v1` routes with org-wide permissions; MCP `bind_session_customer` only scopes bot tools, not direct REST. **Integrators with an existing org:** use your BYO org API key. **Trusted Infinite-operated hosts only:** platform org API key or operator-run MCP for net-new Connect (demos and hosted integrations). Platform MCP sessions still require binding a customer before customer-scoped tools.

Do **not** use `org_infinite` for new Connect onboarding. Customers already on `org_infinite` remain on that org unchanged.

Never paste an unconstrained live organization key into a shared chat. Prefer sandbox keys for demos.

## Configuring Your AI Assistant

**Sign in.** Point the client at `https://bot.api.infinite.dev/mcp` and omit the key. The assistant opens Auth Kit sign-in for **your** organization (not the shared `org_connect` platform org unless you are an Infinite operator on a trusted host).

**API key.** Put the key in the `Authorization` header. Use the host's native header support where it exists; otherwise bridge with [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) and pass the key with `--header`. Setting only an environment variable does **not** send the key.

The API-key commands below read the key from `INFINITE_API_KEY` so it doesn't end up in your shell history. Export it first (`export INFINITE_API_KEY=sk_sandbox_…`).

### Claude Code

Sign in:

```bash theme={null}
claude mcp add --transport http infinite https://bot.api.infinite.dev/mcp
```

Or send an API key:

```bash theme={null}
claude mcp add --transport sse infinite https://bot.api.infinite.dev/mcp/sse \
  --header "Authorization: Bearer $INFINITE_API_KEY"
```

Start a new session and run `/mcp` to confirm `infinite` is connected.

### Cursor

Sign in (no API key) in `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json theme={null}
{
  "mcpServers": {
    "infinite": {
      "url": "https://bot.api.infinite.dev/mcp"
    }
  }
}
```

Or send an API key:

```json theme={null}
{
  "mcpServers": {
    "infinite": {
      "url": "https://bot.api.infinite.dev/mcp/sse",
      "headers": {
        "Authorization": "Bearer sk_sandbox_your_api_key"
      }
    }
  }
}
```

### Codex

```bash theme={null}
codex mcp add infinite --env AUTH="Bearer $INFINITE_API_KEY" -- \
  npx -y mcp-remote https://bot.api.infinite.dev/mcp/sse --transport sse-only --header 'Authorization:${AUTH}'
```

`${AUTH}` is single-quoted on purpose: your shell leaves it alone, and `mcp-remote` substitutes it from the `AUTH` variable Codex passes to the bridge.

### Claude Desktop

Add the following to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json theme={null}
{
  "mcpServers": {
    "infinite": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://bot.api.infinite.dev/mcp/sse",
        "--transport",
        "sse-only",
        "--header",
        "Authorization:${AUTH}"
      ],
      "env": {
        "AUTH": "Bearer sk_sandbox_your_api_key"
      }
    }
  }
}
```

### Other MCP Clients

Point a Streamable HTTP client at `https://bot.api.infinite.dev/mcp` and sign in, or configure an SSE transport to `https://bot.api.infinite.dev/mcp/sse` with `Authorization: Bearer <key>`.

### Verify the connection

Ask the assistant: *"What organization am I connected to?"* It should call `get_organization_info`. Only a successful call proves the tools are usable — if they don't appear, reload the host's MCP tools or restart it, then try again.

To operate as an agent alongside your organization, add a second server (for example `infinite-agent`) with the agent key.

### Docs-only MCP

To search these docs without an Infinite key, connect `https://docs.infinite.dev/mcp`. It's read-only and moves no money.

## Available Tools

Every code example in these docs has an **MCP** tab: the prompt to give an assistant connected to this server. Read prompts and dedicated onboarding tools (`create_business_customer`, `start_verification`, …) run on MCP. Generic `api_request` remains **GET-only**. Payments run on MCP when the session uses an agent key (see [Paying with an agent key](#paying-with-an-agent-key)); with an organization key use the CLI/REST tabs to pay.

### get\_my\_api\_errors

Get recent API errors for your organization.

**Parameters:**

* `hours` (optional): Hours to look back (default: 24, max: 72)
* `path_pattern` (optional): Filter by path pattern
* `limit` (optional): Max results (default: 20, max: 50)

**Example prompt:**

> "Show me API errors from the last 6 hours"

### get\_my\_api\_logs

Get recent API request logs for debugging.

**Parameters:**

* `hours` (optional): Hours to look back (default: 24, max: 72)
* `path_pattern` (optional): Filter by path pattern
* `method` (optional): Filter by HTTP method (GET, POST, etc.)
* `status_code` (optional): Filter by status code
* `limit` (optional): Max results (default: 20, max: 100)

**Example prompt:**

> "Show me all POST requests to /v1/customers/individuals in the last hour"

### get\_request\_by\_id

Look up a specific API request by request ID.

**Parameters:**

* `request_id` (required): The request ID to look up

**Example prompt:**

> "Look up request req\_abc123xyz"

### search\_docs

Search this documentation site and the API reference. Pass the question in natural language -- not just keywords. Results include a short snippet so the assistant can answer before opening the full page.

**Parameters:**

* `query` (required): The user question or topic (e.g. "How do I fund an Infinite wallet in sandbox?")

**Example prompt:**

> "Deposit instructions are the same for every onramp and there is no memo -- how do I tell deposits apart?"

### read\_doc

Read a documentation page in full.

**Parameters:**

* `page` (required): Page slug, as returned by `search_docs` (e.g., `guides/webhooks`)

**Example prompt:**

> "Read the idempotency guide"

### get\_endpoint\_schema

Get the request and response schema for an API endpoint, including required fields.

**Parameters:**

* `method` (required): HTTP method (e.g., "POST")
* `path` (required): API path (e.g., "/v1/customers")

**Example prompt:**

> "What fields are required to create a business customer?"

### api\_request

Make a read-only GET request to the Infinite API.

**Parameters:**

* `path` (required): API path (e.g., "/v1/customers")
* `query_params` (optional): Query parameters as key-value pairs

**Example prompt:**

> "List all my customers with status ACTIVE"

## Paying with an agent key

Connect with an agent key (`sk_live_agent_…` / `sk_sandbox_agent_…`, issued from [Agents](/concepts/agents)) instead of an organization key. The session is pinned to the agent's customer and funding account, and these tools replace the onboarding tools:

| Tool | What it does |
| - | - |
| `get_agent` | Identity, limits, and spend used / remaining today and this month |
| `get_balance` | Available balance of the agent's funding account |
| `list_payees` | Destinations the agent may pay (allowlist, or the customer's approved payees) |
| `get_quote` | Conversion for a cross-currency payout; `holdRate: true` locks it and returns a quote id for `create_transfer` |
| `create_transfer` | Creates a **draft** and returns a plain-English summary. Requires an `operationId` (UUID) so retries never double-pay; accepts `quoteId` for held rates. Pass `confirm: true` only when the user already approved. |
| `submit_transfer` | Submits a draft this agent created. Limits are enforced here; a denial returns `{ denial: { code, window, limit, used, attemptedAmount } }` |
| `get_transfer` / `list_transfers` | The agent's own transfers |
| `wait_for_transfer` | Wait up to 60s for a final status (`timedOut: true` if still in flight) |

Amounts are decimal strings in the agent's limit currency (`"40.00"`); the server converts to minor units. Every guardrail — customer, funding account, payee allowlist, per-transfer / daily / monthly caps — is enforced by the API, not by the assistant.

**Example prompt:**

> "Pay \$40 to Acme Supplies for the June invoice."

The assistant calls `list_payees`, then `create_transfer` (draft), shows you *"Send \$40.00 from vba\_… to Acme Supplies via ACH"*, and on your yes calls `submit_transfer`. If the daily cap is hit it reports the denial and the remaining headroom instead of retrying blindly.

### get\_organization\_info

Get information about your authenticated organization.

**Example prompt:**

> "What organization am I connected to?"

### Agent onboarding tools

Dedicated tools (session API key, not open POST):

| Tool | Purpose |
| - | - |
| `get_agent_session` / `bind_session_customer` | Tenancy + bind `cus_` |
| `create_business_customer` / `get_customer` | Connect customer |
| `request_capabilities` / `get_required_documents` | Declare wanted capabilities; list required evidence from compliance APIs |
| `update_business_details` / `search_industry_codes` | Save business KYB fields without submitting; look up NAICS codes for `industry` |
| `upload_document` / `submit_customer_verification` | Upload files (`fileBase64`, 10MB cap) and API KYB substitute with `doc_` slots |
| `start_verification` / `get_verification_status` / `list_rfis` | Hosted KYB — prefer for humans |
| `upload_rfi_document` / `submit_rfi` | Case RFI attach + submit (authenticated; never `/internal/`) |
| `get_capabilities` / `ensure_balance_account` / `get_deposit_instructions` / `list_accounts` | Ready after KYB |
| `get_account_balance` | Balance of one of the customer's balance accounts |
| `get_quote` / `get_transfer` / `list_transfers` / `list_account_balances` | Bound-customer payment discovery (ephemeral indicative quote, transfer status, balances). No held-quote re-read on an organization key |
| `create_payee_draft` / `get_payee_draft` | Create/screen a bank payee draft for the bound customer (`draftId` / `eba_…`). Screening only — does not enable payout |
| `create_transfer_draft` / `get_transfer_draft` | Durable transfer draft for the bound customer (`draftId` / `tdraft_…`). Registers for platform approval (`POST /v1/transfer-drafts`) — does not call `POST /v1/transfers` or move money |
| `create_payee` | Your own organization's key: add a bank-account payee an agent can pay; payable once `ACTIVE`. Platform sessions use `create_payee_draft` instead |
| `sandbox_approve_customer` / `sandbox_fund_account` / `sandbox_complete_transfer` | Sandbox sessions only: skip verification, fund a balance account, settle a transfer |

Draft and submit payments on MCP with an [agent key](#paying-with-an-agent-key). Organization-key sessions can discover quotes, create payee/transfer drafts (no settle), and read transfer status after the customer is bound.

**Example prompt:**

> "Onboard Acme Corp ([acme@example.com](mailto:acme@example.com), US), request USD\_BALANCE, upload the formation docs I have, and tell me when we're ACTIVE with a balance account."

## Example Conversations

### Debugging API Errors

**You:** "I'm getting 400 errors when creating customers. Can you help me debug?"

**AI:** *Uses get\_my\_api\_errors to find recent 400 errors, then uses get\_endpoint\_schema for POST /v1/customers/individuals and explains which required fields are missing.*

### Exploring Your Data

**You:** "Show me my recent transfers and their statuses"

**AI:** *Uses api\_request to call GET /v1/transfers and summarizes the results.*

### Understanding the API

**You:** "How do I verify that a webhook actually came from you?"

**AI:** *Uses search\_docs to find the webhooks guide, reads it with read\_doc, and walks through signature verification.*

## Rate Limits

The MCP server enforces rate limits per organization:

* **60 requests per minute** per organization
* Rate limit headers are included in responses

## Security

* **Scoped to your organization**: You can only access data belonging to your organization
* **API key validation**: Keys are validated on every request
* **No sensitive data exposure**: API keys and secrets are never returned in responses
* **`api_request` is GET-only**: omitted entirely for platform Connect orgs (along with org-wide log tools); onboarding writes go through dedicated agent tools
* **Customer bind**: platform sessions and immutable `X-Infinite-On-Behalf-Of` (trusted host only) pin tools to one `cus_`; platform bind allows header pin, customers created in that MCP session, or a signed `continuationToken` from `create_business_customer` — knowing a `cus_` id is not enough on a shared platform key
* **`create_business_customer`**: pass a secret UUID `operationId` (`crypto.randomUUID()`); reuse after reconnect to recover the same customer + `continuationToken`
* **Sandbox tools are sandbox-only**: `sandbox_*` tools are registered only for `sk_sandbox_` sessions and act only on the bound customer's accounts and transfers
* **Rate limits**: platform traffic is limited per SSE session (60/min) with a larger org ceiling (300/min)
* **Hosted KYB**: prefer for humans — do not collect identity documents in chat when a verification URL is available; verification status tools return projected progress, not full form schemas. MCP `upload_document` / `upload_rfi_document` are allowed when the host supplies files for RFI fulfillment or API KYB substitute (10MB decoded cap).
* **Payments need an agent key**: organization-key sessions can't move money; agent-key sessions are limited by the agent's customer, funding account, payee allowlist, and spend limits, all enforced by the API

## Troubleshooting

### "Invalid API key" error

Ensure your API key:

* Starts with `sk_sandbox_` or `sk_live_` (agent keys: `sk_sandbox_agent_` / `sk_live_agent_`)
* Is sent in the `Authorization` header as `Bearer <key>` — with `mcp-remote`, pass it via `--header`, not only an environment variable
* Has not been revoked (a revoked agent's key stops working immediately)

### "Rate limit exceeded" error

Wait a minute before making more requests. Consider batching your queries.

### Connection issues

Verify:

* Your network can reach `https://bot.api.infinite.dev/mcp/sse`
* Your MCP client is correctly configured
* The Authorization header is being sent

## Need Help?

* Check the [API Reference](/api-reference) for endpoint details
* Contact [support@infinite.dev](mailto:support@infinite.dev) for assistance


## Related topics

- [Infinite skill for AI assistants](/agent-skill.md)
- [Introduction](/api-reference/introduction.md)
- [Agents](/concepts/agents.md)
- [Register a transfer draft for platform approval](/api-reference/transfer-drafts/register-a-transfer-draft-for-platform-approval.md)
- [Error handling](/guides/error-handling.md)