hermes-mcp

MCP server for the Hermes paid swap API. Gives any MCP host (Claude Desktop, Claude Code, ChatGPT with MCP connectors, Cursor and others) Solana swap tools: ranked quotes, transaction building, broadcasting and status tracking.

Payment is per request in USDC via the x402 protocol: no accounts, no API keys. The server pays from a local keypair and the model never sees the key, only tool results. API payments are gasless for the payer wallet (USDC only, no SOL needed).

Tools

Quotes and built transactions stay cached inside the server and are referred to by opaque ids, so bulky provider payloads never enter the model context.

Related MCP server: x402 Payment Gateway MCP Server

Setup

1. Create a dedicated Solana wallet for payments and fund it with a few dollars of USDC. No SOL is needed for API payments. (To also broadcast swaps owned by this wallet, add a little SOL for the swap network fee.)

2. Save its keypair JSON somewhere private, e.g. ~/.keys/hermes-payer.json.

Claude Desktop

Add to claude_desktop_config.json (Settings -> Developer -> Edit Config):

{
  "mcpServers": {
    "hermes-swap": {
      "command": "npx",
      "args": ["-y", "github:swap-dot-io/hermes-mcp"],
      "env": {
        "PAYER_KEYPAIR": "/absolute/path/to/hermes-payer.json"
      }
    }
  }
}

Claude Code

claude mcp add hermes-swap --env PAYER_KEYPAIR=/absolute/path/to/hermes-payer.json -- npx -y github:swap-dot-io/hermes-mcp

(Claude Code users may prefer the hermes-swap plugin instead.)

ChatGPT desktop (and Codex CLI)

ChatGPT desktop shares MCP configuration with Codex CLI on the same machine. Add to ~/.codex/config.toml:

[mcp_servers.hermes-swap]
command = "npx"
args = ["-y", "github:swap-dot-io/hermes-mcp"]

[mcp_servers.hermes-swap.env]
PAYER_KEYPAIR = "/absolute/path/to/hermes-payer.json"

Or let Codex write the entry: codex mcp add hermes-swap -- npx -y github:swap-dot-io/hermes-mcp (then add the env block).

ChatGPT web supports only remote MCP connectors (developer mode). We do not offer a hosted connector: it would require custody of your payment key, which defeats the design. Use ChatGPT desktop or any local MCP host instead.

Environment

Safety model

• The keypair path is configuration; the key itself never reaches the model.

• swap_sign_and_submit refuses to run without confirm: true and is meant to be called only after the user explicitly confirmed the swap.

• A paid call is trusted only when it carries an on-chain settlement receipt (X-PAYMENT-RESPONSE). Failed requests are never charged by Hermes.

Links

• Agent guide: https://hermes.swap.io/llms.txt

• Live payment terms: https://hermes.swap.io/v1/info

• x402 protocol: https://www.x402.org