Copy page

Agents & MCP

Agents & MCP

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

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 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. There is no separate MCP-only error dialect.

Connecting a specific client

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.

Read it as text

Every page on this site ships an agent-readable .md twin, generated at build time (docs.publishMarkdown — see llms.txt and 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 · back to Get started.