MCP: AI Agent Integration

AI agents can now perform cross-chain token swaps through natural language using the Squid MCP — a Model Context Protocol server that connects AI assistants like Claude to Squid Router.

Instead of writing code to interact with swap APIs, developers can give an AI assistant access to Squid's cross-chain infrastructure and let users swap tokens by simply describing what they want. The MCP handles wallet management, route quoting, swap execution, and status tracking — all through conversation.

The MCP-managed wallet stores a private key in the OS keychain. This wallet is intended for development, testing, and small-amount transactions. Do not store significant funds in the agent wallet.

Features

• Wallet management — generate and store a private key in the OS keychain; retrieve the agent wallet address

• Token & chain discovery — list all EVM chains and tokens supported by Squid Router

• Balance checking — query native and ERC-20 balances across all EVM chains

• Cross-chain swaps — get a route quote, review it, then execute with background monitoring

• Swap status — poll the status of any in-flight swap by transaction hash

The Squid MCP currently supports EVM chains only.

---

Getting Started

Requirements

• Node.js ≥ 22

• yarn — npm install -g yarn

• A Squid Integrator ID

1. Clone the repo and build

# Download the repository
git clone https://github.com/0xsquid/squid-mcp.git
cd squid-mcp

# Install dependencies
yarn install

# Compile the source
yarn build

2. Connect to your MCP client

Add the MCP server to your AI client of choice.

Claude Desktop

1. Open the Claude Desktop settings

1. Go to Settings > Desktop app > Developer and click "Edit Config"

1. This will open claude_desktop_config.json in your file explorer

1. Open the file with a text editor and add squid-mcp under mcpServers:

{
  "mcpServers": {
    "squid-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/squid-mcp/dist/index.js"]
    }
  }
}

1. Restart Claude Desktop — you should now see the Squid MCP available and running

Claude Desktop Developer page showing squid-mcp listed with status running

Using fnm or nvm?

Claude Desktop does not inherit your shell environment, so the node shim on your PATH may not resolve correctly. Use the absolute path to the node binary instead:

{
  "mcpServers": {
    "squid-mcp": {
      "command": "/Users/your-user/.local/share/fnm/node-versions/v22.0.0/installation/bin/node",
      "args": ["/absolute/path/to/squid-mcp/dist/index.js"]
    }
  }
}

To find the path for your active version:

ls ~/.local/share/fnm/node-versions/

Claude Code (CLI)

claude mcp add squid-mcp node /absolute/path/to/squid-mcp/dist/index.js

If successful, you should see:

Added stdio MCP server squid-mcp with command: node /Users/your-user/squid-mcp/dist/index.js to local config
File modified: /Users/your-user/.claude.json

To verify it was added successfully, run /mcp in Claude Code.

Claude Code CLI showing squid-mcp listed under Local MCPs with a green checkmark

---

Available Tools

Tool	Description
setup_wallet	Generate a new wallet and store it in the OS keychain
get_agent_address	Return the agent wallet address
get_chains	List all EVM chains supported by Squid Router
get_tokens	List tokens on a given chain (filterable by symbol/name)
get_balances	Show non-zero balances across all chains (or a specific one)
get_route	Get a swap route quote (stores it as a pending route)
execute_swap	Execute the pending route; monitors completion in background
get_status	Poll the status of a swap by transaction hash

---

Typical Swap Workflow

1. setup_wallet        → create the agent wallet (first time only)
2. get_agent_address   → confirm the wallet address and fund it
3. get_balances        → check available funds
4. get_tokens          → look up token addresses if needed
5. get_route           → review quote (amounts, fees, slippage, ETA)
6. execute_swap        → submit (only after you approve the route)
7. get_status          → poll until "success" or "error"

Once the wallet is set up and funded, you can simply tell the AI assistant what you want to do in natural language — for example:

"Swap 1 USDC on Ethereum to ETH on Base"

The assistant will use the tools above to get a quote, present it for your approval, and execute the swap.

---

Export Your Private Key

To back up or import the agent wallet key into another wallet:

yarn build && yarn export-key

The key is printed only to your local terminal — it is never sent to the AI assistant or any MCP context.