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 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. swaps_report_fetch answers unavailable_in_public_review here: a full report needs a Swaps account, so use /mcp with a key. No quotes, checkout, report creation or money operations. |
https://www.swaps.app/api/mcp-wallet-screen | None | Wallet Screen only. Screens one public address on an explicitly selected network. OpenAPI contract. |
https://www.swaps.app/api/mcp-claude | Swaps account sign-in (OAuth 2.1) | Swaps in Claude only. Checks one public address on a named network from the person's Swaps account. See Swaps in Claude. |
https://api.swaps.app/v1 | Business key, scopes and account capabilities | Resource API, enabled in production; a paused resource answers 503 temporarily_unavailable. |
The hosted MCP and the /v1 API keep business keys. Supabase Auth's OAuth 2.1 server signs people in for the Claude connector only; its token reaches only this connector's two checks and the person's own sign-in record. 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.
Wallet Screen
Connect to https://www.swaps.app/api/mcp-wallet-screen over Streamable HTTP. MCP 2026-07-28
clients can call server/discover to get a complete result with supportedVersions, the tools
and resources capabilities, and the server identity in _meta["io.modelcontextprotocol/serverInfo"].
The discovery list contains 2026-07-28. Include the version and client capabilities in _meta
on modern requests. Legacy clients use initialize to negotiate 2025-11-25,
2025-06-18, 2025-03-26, 2024-11-05, or 2024-10-07.
Code
Use tools/list to discover the tool definition. screen_wallet_address accepts one public
address and the explicitly requested chain.
Keep the address case intact. If the user has not named or confirmed a network for the address,
ask and wait before calling the tool. EVM address formatting alone does not identify the network.
The result card shows the signal, network, sources and coverage. The tool reports available
sanctions matches or previous screening signals and explains the available coverage.
An inconclusive result does not establish safety. Use the standalone OpenAPI contract
for the exact arguments, outcomes and transport. This server has its own tool catalogue.
Wallet Screen also accepts an optional BCP 47 locale. The card currently supports English and Russian;
other languages show a visible English fallback. The assistant can still explain the result in the conversation language.
One free check in ChatGPT, then sign-up (2026-11-17). With the free-limit flag on, each ChatGPT account (or, without a
subject from outside ChatGPT's egress, each network) gets one free check; after it the tool answers status: "unavailable" with the reason code
free_check_used (or free_checks_network_used) and a Sign up on swaps.app button
(https://www.swaps.app/login?redirect=%2Fsearch with the app's UTM, no address), where the account's first check is
free, then 1 credit ($1). A call from ChatGPT's own egress without openai/subject has no account to count a free
check under and is never counted by its shared network: it answers status: "unavailable" with the reason code
chatgpt_account_unknown and the same button, and nothing is spent. The tool runs the live guard.check; coverage says whether a verdict was screened for this request
(live_screening) or reused from Guard's own recent screening (cached_screening). The additive result fields are
riskScore (0–100, higher means higher risk, nullable), assessedAt (when the screening behind the result was
computed; for a reused one, its original time; nullable), responseAt (the time Guard reported with the response),
reasons (known signals and context), and sourceCoverage (which sources answered in that screening). Neither the
score nor source coverage is a probability of safety. Missing values remain null or empty; response time never
replaces the screening time.
The card offers Basis and Share. Share shows selectable text built from the displayed result, with
the address hidden by default; explicitly including the address affects that text only. ChatGPT's widget
sandbox blocks downloads and does not grant clipboard access by default, so the card produces no file, PNG or
native share: a Copy button appears only when the host grants clipboard write, otherwise the text stays
selectable, and Open on swaps.app opens https://www.swaps.app/login?redirect=%2Fsearch&utm_source=chatgpt_app&utm_medium=app&utm_campaign=wallet-screen (sign-up, back to /search; UTM only) through the host with no address or
result data in the URL. When the handoff is switched on (off by default) it opens
https://www.swaps.app/search/wallet-check?token=<token> instead: an opaque single-use token that stands in for the address
for 24 hours and carries no address; the page redeems it and removes it from the address bar. The result's widget-only _meta.walletScreen binds the selected address and network to
that exact response; older responses without this binding can share only with the address hidden.
The model-facing result contains no address or upstream owner label.
No upload, public link, paid report, credit consumption or website checkout is triggered by these actions.
The versioned widget resource is ui://wallet-screen/result-v11.html; the earlier result-v10.html, result-v9.html, result-v8.html, result-v7.html, result-v6.html, result-v5.html, result-v4.html,
result-v3.html, result-v2.html and result.html URIs remain readable and serve the current card.
Swaps in Claude
The connector is a signed-in MCP server for Claude at https://www.swaps.app/api/mcp-claude over Streamable HTTP,
separate from the surfaces above. Contract: claude-connector.json.
- Sign-in. OAuth 2.1 with PKCE through Supabase Auth's OAuth server, with dynamic client registration and the
consent page at
https://www.swaps.app/oauth/consent.initialize,tools/listandresources/*need no token. Atools/callwithout a valid token answers401withWWW-Authenticate: Bearer … resource_metadata="https://www.swaps.app/.well-known/oauth-protected-resource/api/mcp-claude", scope="openid"; when the sign-in cannot be checked it answers503 auth_unavailablewithRetry-After. The token reaches only this connector's two checks and the person's own sign-in record (Supabase AuthGET /user,/oauth/userinfo). Swaps' edge functions answer it403 oauth_client_not_allowed, the Data APIinsufficient_privilege, and Storage and Realtime return nothing. - What Swaps receives (Privacy Policy, verbatim): for checks in our Claude connector, the sign-in token our sign-in issues to the app when you connect your Swaps account there — it identifies your Swaps account and carries your email address, phone number and other details of your sign-in record, and the app keeps it until you disconnect or it expires — and the address and network you ask to check.
screen_wallet_address(model-visible,readOnlyHint: true):{ address, chain },chainone of the 14 networks. It reads the price and returns the check card; it spends nothing.run_wallet_screen(_meta.ui.visibility: ["app"], called by the card's button):{ address, chain, expected_charge },expected_chargefreeorcredit— the price the button named. Guard never charges more: a changed price answers409 price_changedand the card shows the new button.- Price. The first check on your account is free, then 1 credit ($1) each. A saved report of the last 30 days for the
same account, address and network opens free (
charged: "cached"). Ano_creditscard links tohttps://www.swaps.app/dashboard/settings/credits. - Result. Every tool outcome is HTTP 200 with the card in
structuredContent(ready,resultorrefused); the address travels only in_meta.walletScreen. A refusal carries one ofinvalid_address,network_mismatch,no_credits,signed_out,unavailable,result_lost,busyorrefused_by_swaps. A low risk counts as a verdict only when the address security source (GoPlus) answered, as on the ChatGPT card. A low risk without it (every non-EVM network today) and a result with no level show «Limited data» and «Not enough data for a verdict», with no score. Guard's no-activity report (the network's provider says the account does not exist) is a result and shows Guard's own sentence.
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.mdtwin of every page — see below). - Prompts —
onboard(what this account can do today and the next unblocking step) andpay_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.
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 guide and public API reference route ships an agent-readable .md twin at build time. Zudoku publishes guide twins; the docs postbuild derives every /reference*.md twin from the same processed OpenAPI document as the HTML reference. llms.txt and llms-full.txt link both sets and are the machine-readable entry points for the custom docs landing page. The "Copy page" control in a guide header copies that guide's Markdown body — the same text an agent fetches.
Next: Providers & coverage · back to Get started.