swaps-mcp

Swaps Plugin — Agent-Native Crypto On-Ramp Aggregator

Install once, quote anywhere. Live on-ramp quotes from Paybis, Transak, Mercuryo, Coinbase Onramp, Bridge, and Partna — surfaced as MCP tools to any AI agent.

This is the canonical Swaps plugin distribution. One repo, one source of truth, one install command per host.

Free, open-source (MIT), no API key.

Five tools your agent gets

Tool	What it does
swaps_quote	Live quote + ranked alternatives, with inline ranking rationale (winner.explain). Primary tool.
swaps_taxonomy	6-axis provider taxonomy snapshot.
swaps_providers_for_corridor	Provider candidates for a given country + payment method.
swaps_corridors	Curated top buy/sell corridors.
swaps_explain_choice	Post-hoc audit by quoteId (currently degraded — prefer inline winner.explain on swaps_quote).

Install — by host

Claude Code

/plugin marketplace add swapsapp/swaps-plugin
/plugin install swaps-mcp@swaps-plugins
/reload-plugins

OpenAI Codex (local plugin)

# Clone into your Codex plugins directory
git clone https://github.com/swapsapp/swaps-plugin ~/plugins/swaps-mcp

# Register in ~/.agents/plugins/marketplace.json under "plugins"
# Restart Codex to load

Gemini CLI

Paste into ~/.gemini/settings.json (user scope) or .gemini/settings.json (project scope):

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

Cursor

Paste into .cursor/mcp.json (workspace) or ~/.cursor/mcp.json (global):

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

Windsurf

Paste into ~/.codeium/windsurf/mcp_config.json:

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

Claude Desktop

Paste into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or platform equivalent:

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

Restart the host application after editing the config file.

Try it

After install, ask the agent:

Use swaps_quote to find the cheapest way to buy 100 USD of BTC in the US,
then read winner.explain and tell me why the winning provider beat the others.

You'll see a real-time quote with provider, fees, ETA, KYC tier, checkout URL, and the full ranking rationale.

Stable public endpoints (host-agnostic)

The MCP server is a thin wrapper around four public HTTP endpoints any language can call directly:

Endpoint	Description
https://agent.swaps.app/openapi.json	OpenAPI 3.1 spec
https://agent.swaps.app/taxonomy.json	Provider taxonomy snapshot
https://agent.swaps.app/llm/quote	Live quote
https://agent.swaps.app/llm/routing-explainer	Post-hoc explainer (currently degraded)

These URLs are permanent. Breaking changes ship under /agent/v2/* while v1 stays live for at least six months.

Architecture

AI agent (Claude / Codex / Gemini / Cursor / Windsurf / Claude Desktop)
    ↓
this plugin (manifest + auto-loaded skill)
    ↓
@agent.swaps/[email protected] (npm)
    ↓
agent.swaps.app/llm/quote (Vercel rewrite → Supabase Edge Function)
    ↓
SmartRouter (6 provider adapters)

Repo layout

swaps-plugin/
├── .claude-plugin/
│   ├── plugin.json          ← Claude Code plugin manifest
│   └── marketplace.json     ← self-hosted marketplace catalog
├── .codex-plugin/
│   └── plugin.json          ← OpenAI Codex local plugin manifest
├── .mcp.json                ← universal MCP server config
├── skills/
│   └── swaps-mcp/
│       └── SKILL.md         ← auto-loaded skill with tool-usage guidance
├── tests/
│   └── smoke.mjs            ← MCP handshake + tool round-trip verification
├── assets/                  ← icons + screenshots for marketplace listings
├── README.md                ← this file
├── LICENSE                  ← MIT
└── CHANGELOG.md

Verifying your install

After install, run a smoke check from your terminal:

git clone https://github.com/swapsapp/swaps-plugin && cd swaps-plugin
mkdir -p /private/tmp/swaps-mcp-test-deps
cd /private/tmp/swaps-mcp-test-deps && npm install @modelcontextprotocol/sdk
cd - && node tests/smoke.mjs

Expected: pass-with-warnings (9 PASS + 1 WARN on swaps_explain_choice, known v1.1.x backlog). Exit code 0.

Versioning