# MCP: AI Agent Integration
AI agents can now perform cross-chain token swaps through natural language using the **Squid MCP** — a [Model Context Protocol](https://modelcontextprotocol.io) server that connects AI assistants like Claude to [Squid Router](https://squidrouter.com).
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.
{% hint style="warning" %}
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.
{% endhint %}
## 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
{% hint style="info" %}
The Squid MCP currently supports **EVM chains only**.
{% endhint %}
***
## Getting Started
### Requirements
* [**Node.js** ≥ 22](https://nodejs.org/en/download)
* **yarn** — `npm install -g yarn`
* A [**Squid Integrator ID**](https://squidrouter.typeform.com/integrator-id)
### 1. Clone the repo and build
```bash
# 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
2. Go to **Settings > Desktop app > Developer** and click **"Edit Config"**
3. This will open `claude_desktop_config.json` in your file explorer
4. Open the file with a text editor and add `squid-mcp` under `mcpServers`:
```json
{
"mcpServers": {
"squid-mcp": {
"command": "node",
"args": ["/absolute/path/to/squid-mcp/dist/index.js"]
}
}
}
```
5. Restart Claude Desktop — you should now see the Squid MCP available and 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:
```json
{
"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:
```bash
ls ~/.local/share/fnm/node-versions/
```
#### Claude Code (CLI)
```bash
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.
***
## 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:
```bash
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.