# 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.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.squidrouter.com/api-and-sdk-integration/mcp.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.