Package Exports

@agent.swaps/mcp-server

Readme

@agent.swaps/mcp-server

Model Context Protocol server for Swaps — the agent-native crypto on-ramp aggregator. Five tools that let LLM agents quote crypto purchases across 6 licensed providers, reason about provider trade-offs, and explain their routing decisions.

What this is

Swaps aggregates Paybis, Transak, Mercuryo, Coinbase, Bridge, and Partna into a single quote-and-checkout surface across 190 countries and 34+ payment methods. With @agent.swaps/mcp-server, your AI agent gains five tools:

swaps_quote — live quote across all 6 providers, returns winner + ranked alternatives + structured LLMExplainPayload
swaps_taxonomy — full 6-axis provider classification (Domain · Flow shape · Integration · Settlement rail · User constraints · Agentic exposure)
swaps_providers_for_corridor — country/method-aware filter
swaps_explain_choice — post-hoc explain by quoteId
swaps_corridors — curated top corridors with preferred-provider ordering

Zero-config. No API key required. 8 KB gzipped. MIT-licensed.

Install

Claude Code (`~/.claude/mcp.json`)

{
  "mcpServers": {
    "swaps": {
      "command": "npx",
      "args": ["-y", "@agent.swaps/mcp-server"]
    }
  }
}

Cursor (`.cursor/mcp.json`)

Same shape as Claude Code.

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json. Same shape.

Windsurf

Same shape.

ChatGPT Apps

A hosted HTTP/SSE variant ships in a future release. For now, stdio works in any local development setup.

Try it

After installing the server in your host, ask:

Use the swaps_quote tool to find the cheapest way to buy 100 USD of BTC in the United States. Then call swaps_explain_choice with the returned quoteId and tell me why the winning provider beat the others.

You'll see your agent compose two tool calls, return a real Paybis quote (~$86k/BTC live), and read back the structured ranking criteria.

Tools

`swaps_quote`

Get the best fiat on-ramp or off-ramp quote across all 6 providers.

Input:

from (string, required) — ISO fiat or crypto symbol the user is paying with (e.g. "USD", "USDT")
to (string, required) — Crypto symbol the user wants to receive (e.g. "BTC")
amount (string, required) — Decimal amount in source currency (e.g. "100")
country (string, required, 2 chars) — ISO-3166-1 alpha-2 country code (e.g. "US", "DE")
side ("buy" | "sell", optional, default "buy")
method (string, optional) — Payment-method slug: card, sepa, ach, pix, apple-pay, etc.

Returns: LLMQuoteResponse with the winning provider, ranked alternatives, and a structured LLMExplainPayload per quote. Full schema at agent.swaps.app/openapi.json.

`swaps_taxonomy`

Get the full 6-axis taxonomy of all 11 Swaps providers.

Input: none.

Returns: machine-readable JSON sourced from agent.swaps.app/taxonomy.json.

`swaps_providers_for_corridor`

Filter the taxonomy down to candidates for a specific country and payment method.

Input:

country (string, required, 2 chars)
paymentMethod (string, optional)

Returns: list of fiat-ramp provider candidates.

`swaps_explain_choice`

Get the post-hoc explanation for a previously-issued quoteId.

Input:

quoteId (string, required) — from a previous swaps_quote call

Returns: the LLMExplainPayload for winner + alternatives. Returns EXPLAIN_EXPIRED if the cache (TTL ~10 min, isolate-scoped) has elapsed — re-call swaps_quote to recover. Recommended pattern: rely on the inline explain field on /quote responses as the source of truth; swaps_explain_choice is for niche post-hoc cases.

`swaps_corridors`

Get the curated top 14 buy + sell corridors with preferred-provider ordering.

Input: none.

Returns: corridor-to-provider matrix mirroring the ## Corridor Matrix section of swaps.app/llms.txt.

Environment overrides

Variable	Default	Purpose
`SWAPS_AGENT_BASE_URL`	`https://agent.swaps.app`	Primary host for all API calls
`SWAPS_AGENT_FALLBACK_URL`	`https://www.swaps.app/agent`	Used on 5xx fallback

Stability commitment

The URL contract at agent.swaps.app/* is permanent. Breaking changes ship at /agent/v2/*; v1 stays live ≥6 months.
JSON envelopes are versioned via _meta.schemaVersion. Within v1.x all changes are additive only.
MCP tool names + Zod input schemas are versioned in this package; breaking changes ship a new tool name (swaps_quote_v2), the old tool stays live ≥6 months.

How it works (architecture)

This package is a thin HTTP client over the public agentic surface at agent.swaps.app. The MCP server itself does no work locally beyond JSON marshalling and Zod input validation. All intelligence lives server-side and is version-controlled via the canonical OpenAPI 3.1 spec at agent.swaps.app/openapi.json.

Transport: STDIO (Anthropic MCP stdio variant). Hosted HTTP/SSE variant planned for v1.2+.
Auth: None for v1. Anonymous-callable. Rate-limited 30/min/IP + 1000/day/anon-key at the upstream.
Cache: None client-side. Upstream caches static endpoints (taxonomy, OpenAPI) for ~5 min at CDN.
Dependencies: @modelcontextprotocol/sdk, zod, zod-to-json-schema.

Roadmap

See CHANGELOG.md for shipped versions and agent.swaps.app/openapi.json for the live contract.

Planned for v1.1.x:

Real router-emitted LLMExplainPayload.rankingCriteria.score (currently synthetic)
Python parity: pip install swaps-mcp
Hosted HTTP/SSE variant at mcp.agent.swaps.app for ChatGPT Apps
DEX/crypto-to-crypto pair routing
MPP-payable variants (HTTP 402 + USDC micropayments)

JSPM