# Agents & MCP

The hosted server is at `https://mcp.agent.swaps.app/mcp` over Streamable HTTP.

> **Availability**
>
> The account tools documented below call the `/v1` resource API, enabled in production.
> Access still depends on scopes, account capabilities and resource availability: a tool whose resource is not switched on answers `503 temporarily_unavailable`. A
> successful MCP connection or tool listing does not establish account access or operational
> availability — call `list_capabilities` with a live key first. The [public MCP
> page](https://www.swaps.app/developers/skills/mcp-server) lists the published surfaces.

## Choose a surface

| Surface                                   | Authorization                                              | Scope                                                                                                                                                                 |
| ----------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Published `@agent.swaps/mcp-server@1.1.0` | No business key                                            | Local stdio: five legacy read-only route tools and `legal://` resources. Shipped independently; not a proxy for hosted MCP.                                           |
| `https://mcp.agent.swaps.app/mcp`         | Business key as Bearer for scoped calls                    | Legacy discovery and Search tools, plus generated account tools whose calls depend on `/v1`. Listing a tool is not permission to execute.                             |
| `https://mcp.agent.swaps.app/mcp-public`  | No business key for the public tool set                    | Six read-only tools: wallet inspection, Search preview, report retrieval/rendering, taxonomy and corridors. No quotes, checkout, report creation or money operations. |
| `https://api.swaps.app/v1`                | Business key, scopes and account capabilities | Resource API, enabled in production; a paused resource answers `503 temporarily_unavailable`.                                                                          |

Swaps operates no public OAuth authorization server. Obtain an existing business key from the account holder through Developers → API keys; automatic key issuance is not promised. A `sk_test_` key reaches only what [Test mode](/test-mode) lists — API-key, request-log and account reads, and webhook endpoints, webhook deliveries and the per-object event lists in the development project — so every account tool below needs a live key: each one's operation answers a test key `503 temporarily_unavailable`.

Connect with the business key and call `list_capabilities` with a live key first. Describe only the actions that response permits. When a call answers `503 temporarily_unavailable`, report the availability error without attempting a money operation.

## What a tool can never do

The server's own system prompt states this in plain terms, and every tool description repeats the parts that apply to it:

- Tools read state, price routes and **prepare** money movement — none of them sign, send, refund or declare something settled.
- Every money step still needs the person's own confirmation per transaction — never chain a quote straight into funding, or a prepared withdrawal into a send.
- Bank details, identity documents and attestations are never tool arguments; a tool hands back a link the person opens themselves.
- Money truth comes from the normalized state a tool returns — a payer's "I've sent it" is a self-report, not settlement.
- A degraded flag or an error means _unknown_ — never zero, never "nothing happened".
- Quotes expire; re-quote rather than reuse. Idempotency keys are yours to generate and safe to reuse on a retry.

Structurally excluded — no tool exists for these, on purpose: payout beneficiary and wallet external-account creation, payment-link activation, payroll execution and funding, sends that broadcast, and any refund. Each is a REST-only, human-attested step.

## New account contract

The statuses below describe implementation, not production availability. The full generated list lives in `docs/api/MCP-v1.md` §4 and regenerates with the spec; this is a representative slice, one row per product:

| Tool                        | Status                    | What it does                                                                                                                          |
| --------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `list_capabilities`         | implemented               | What this account can actually execute right now, per product.                                                                        |
| `create_payment_request`    | implemented               | Draft a payment request the merchant reviews — cannot activate, cannot charge a card.                                                 |
| `check_payment_request`     | implemented               | One request's state, attempts and timeline in a single call.                                                                          |
| `prepare_invoice_payout`    | implemented               | Create a payout for an external invoice and return a draft ready to fund — beneficiary bank details are REST-only, excluded from MCP. |
| `prepare_payroll_run`       | implemented               | Draft a pay run for review — nothing is funded or paid; recipients add their own destination afterwards.                              |
| `get_wallet_balance`        | implemented               | The signed-in person's Tempo balance, every stablecoin plus a server-computed total.                                                  |
| `prepare_wallet_withdrawal` | dark-flag                 | Prepare a cross-chain withdrawal and return the steps the person's own passkey must sign — nothing leaves the wallet until they sign. |
| `get_quote`                 | implemented               | Price a buy or sell across every connected provider; quotes expire.                                                                   |
| `check_address_risk`        | implemented               | Screen a blockchain address before funds are sent to it — a level, a score, named flags.                                              |
| `trace_address_funds`       | implemented               | Follow where value moved from one address, after a risk check flags it — slow and expensive, called deliberately.                     |
| `get_verification_status`   | dark-flag                 | The account's verification state and the single next step — status only, never documents.                                             |
| `create_subscription`       | dark-flag                 | Draft a version-1 crypto subscription — a schedule only, no money moves until each invoice is paid.                                   |

## Resources and prompts

- **Resources** — `legal://swaps/api-terms` (live today), `swaps://capabilities` (the caller's own capability projection), `swaps://docs/<page>` (this site's `.md` twin of every page — see below).
- **Prompts** — `onboard` (what this account can do today and the next unblocking step) and `pay_an_invoice` (the guarded flow: capabilities → draft → hosted beneficiary → funding instructions → confirmation).

## Errors

A failed tool call returns the same REST error envelope (`type`, `code`, `message`, `doc_url`, `request_id`) as structured content with `isError: true` — see [Conventions → Errors](/conventions#errors). There is no separate MCP-only error dialect.

## Connecting a specific client

```shell title="Claude Code"
claude mcp add --scope project --transport http swaps https://mcp.agent.swaps.app/mcp
```

```json title="Claude Code (.mcp.json)"
{
  "mcpServers": {
    "swaps": {
      "type": "http",
      "url": "https://mcp.agent.swaps.app/mcp",
      "headers": { "Authorization": "Bearer ${SWAPS_API_KEY}" }
    }
  }
}
```

```json title="Cursor (~/.cursor/mcp.json)"
{
  "mcpServers": {
    "swaps": {
      "url": "https://mcp.agent.swaps.app/mcp",
      "headers": { "Authorization": "Bearer ${env:SWAPS_API_KEY}" }
    }
  }
}
```

```shell title="Codex"
codex mcp add swaps --url https://mcp.agent.swaps.app/mcp --bearer-token-env-var SWAPS_API_KEY
```

Supply `SWAPS_API_KEY` in the client environment. Do not store the key value in shared configuration. Verify `initialize` and `tools/list`; call `list_capabilities` with a live key before any account action. An authorization or availability error is not an empty capability list.

**Ask your agent**

Use an existing authorized live business key.

> Connect to the Swaps MCP server. Call list_capabilities, then summarize in plain English what this account can and cannot do today, product by product.

## Read it as text

Every page on this site ships an agent-readable `.md` twin, generated at build time (`docs.publishMarkdown` — see [`llms.txt`](/llms.txt) and [`llms-full.txt`](/llms-full.txt)). The "Copy page" control in the page header copies that page's own Markdown body — the same text an agent fetches.

Next: [Providers & coverage](/providers-coverage) · back to [Get started](/get-started).