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 can:

Compare provider rates in real time, with the explanation of why each won or lost
Reason about which provider fits a use case using the canonical 6-axis taxonomy
Hand off the user to a one-click checkout URL when ready to buy

No API key required for v1. Zero-friction install in any MCP-aware host. ─────────────────────────────────────────────────

Install

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

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

Cursor (`.cursor/mcp.json` in your project root)

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

Claude Desktop (`claude_desktop_config.json`)

Same shape as Claude Code. On macOS the file lives at: ~/Library/Application Support/Claude/claude_desktop_config.json

Windsurf

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

ChatGPT Apps (Apps SDK)

The MCP HTTP/SSE transport variant for ChatGPT Apps ships in a future release. For now, stdio works in any local development setup.

Tools

`swaps_quote`

Get the best on-ramp or off-ramp quote across all 6 fiat 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. See agent.swaps.app/openapi.json for the full schema.

`swaps_taxonomy`

Get the full 6-axis taxonomy of all 11 Swaps providers: Domain · Flow shape · Integration · Settlement rail · User constraints · Agentic exposure.

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. Useful when the agent already discarded the original swaps_quote response but needs to re-justify a decision.

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) has elapsed — re-call swaps_quote to recover.

`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.

Example prompts

After installing the server, try these in your MCP-aware host:

Use the swaps_quote tool to find the cheapest way to buy 100 USD of BTC in the United States.

Compare the available on-ramp providers for buying USDT in India with bank transfer. Use swaps_providers_for_corridor and then swaps_quote.

Buy 200 EUR of USDC in Germany via SEPA. Call swaps_quote, then explain via swaps_explain_choice why the winner beat the others.

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

Tool names and input schemas are versioned — breaking changes ship a new tool name (e.g. swaps_quote_v2); the old tool stays live for ≥6 months.
The underlying HTTP API is contracted at agent.swaps.app/openapi.json. Schema changes are additive within info.version minor bumps.

License

MIT

JSPM