Supported Clients

The 1inch MCP Server and AI Skills work with a wide range of AI coding assistants. This page covers setup instructions, authentication configuration, and troubleshooting for each supported client.

Supported clients

Client MCP Setup AI Skills
Claude Desktop Instructions Install
Claude Code Instructions Install
OpenAI Codex Instructions Install
Gemini CLI Instructions Install
Cursor Instructions Install
Windsurf Instructions Install
VS Code (Copilot) Instructions Install
JetBrains IDEs Instructions Install

The following clients are also MCP-compatible and can connect using the generic setup below:

  • Continue — open-source AI assistant for VS Code and JetBrains
  • Zed — AI-native code editor
  • Amazon Q Developer — AWS AI coding assistant

MCP is an open standard with rapidly growing adoption. Any MCP-compatible client can connect to the 1inch MCP Server.

MCP Server setup

Claude Code

Claude Code supports HTTP MCP servers natively:


         
         

           Bash
         

 
         
         

           
           

             
1
2
3
4
5

           

 
           
           
claude mcp add \
  --transport http \
  --scope user \
  1inch-business \
  https://api.1inch.com/mcp/protocol

OpenAI Codex

Codex supports MCP servers in both the CLI and the VS Code extension:


         
         

           Bash
         

 
         
         

           
           

             
1

           

 
           
           
codex --mcp-server "https://api.1inch.com/mcp/protocol"

For the VS Code extension, add the server in the Codex MCP settings panel with the same URL.

Gemini CLI

Gemini CLI supports HTTP MCP servers natively:


         
         

           Bash
         

 
         
         

           
           

             
1
2
3
4

           

 
           
           
gemini mcp add \
  --transport http \
  1inch-business \
  https://api.1inch.com/mcp/protocol

Claude Desktop

Claude Desktop communicates via stdio, so you use supergateway to bridge to the HTTP server. This requires Node.js 18+.

Add the following to your configuration file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

         
         

           JSON
         

 
         
         

           
           

             
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

           

 
           
           
{
  "mcpServers": {
    "1inch-business": {
      "command": "/absolute/path/to/node/bin/npx",
      "args": [
        "-y",
        "supergateway",
        "--streamableHttp",
        "https://api.1inch.com/mcp/protocol",
        "--outputTransport",
        "stdio"
      ],
      "env": {
        "PATH": "/absolute/path/to/node/bin:/usr/bin:/bin"
      }
    }
  }
}

Replace /absolute/path/to/node/bin with the path to your Node.js installation (e.g., /usr/local/bin or the output of dirname $(which node)).

The command and PATH fields require absolute paths because AI clients do not inherit your shell's PATH. Using npx -y ensures the latest version of supergateway is downloaded automatically.

Cursor

Create or edit .cursor/mcp.json in your project root:


         
         

           JSON
         

 
         
         

           
           

             
1
2
3
4
5
6
7

           

 
           
           
{
  "mcpServers": {
    "1inch-business": {
      "url": "https://api.1inch.com/mcp/protocol"
    }
  }
}

Windsurf

Create or edit ~/.codeium/windsurf/mcp_config.json:


         
         

           JSON
         

 
         
         

           
           

             
1
2
3
4
5
6
7

           

 
           
           
{
  "mcpServers": {
    "1inch-business": {
      "serverUrl": "https://api.1inch.com/mcp/protocol"
    }
  }
}

VS Code (Copilot)

Create or edit .vscode/mcp.json in your project root:


         
         

           JSON
         

 
         
         

           
           

             
1
2
3
4
5
6
7
8

           

 
           
           
{
  "servers": {
    "1inch-business": {
      "type": "http",
      "url": "https://api.1inch.com/mcp/protocol"
    }
  }
}

VS Code also supports configuring MCP servers through settings.json under the "mcp" key. See the VS Code MCP documentation for additional options.

JetBrains IDEs

IntelliJ IDEA, WebStorm, PyCharm, and other JetBrains IDEs support MCP through the AI Assistant (2025.1+).

  1. Open Settings → Tools → AI Assistant → Model Context Protocol (MCP)
  2. Click Add, select HTTP, and paste the following JSON snippet:

         
         

           JSON
         

 
         
         

           
           

             
1
2
3
4
5
6
7

           

 
           
           
{
  "mcpServers": {
    "1inch-business": {
      "url": "https://api.1inch.com/mcp/protocol"
    }
  }
}

The 1inch MCP tools will be available in the AI Assistant chat within your IDE.

Other MCP clients

Most MCP clients support HTTP transport and can connect directly to the server URL:

  • Server URL: https://api.1inch.com/mcp/protocol

For clients that only support stdio transport, use supergateway to bridge to the HTTP server (requires Node.js 18+):


         
         

           Bash
         

 
         
         

           
           

             
1
2
3

           

 
           
           
npx -y supergateway \
  --streamableHttp https://api.1inch.com/mcp/protocol \
  --outputTransport stdio

Configure your client to launch this as a subprocess and communicate over stdin/stdout.

AI Skills installation

Install the 1inch AI Skill so your agent knows the server URL, tools, and auth patterns automatically:


         
         

           Bash
         

 
         
         

           
           

             
1

           

 
           
           
npx skills add 1inch/1inch-ai

No npm package required — distribution is git-based. For more details, see AI Skills.

For stdio-only clients (e.g. Claude Desktop), the skill documents the same URLs and auth patterns, but you still need the supergateway setup above for the actual MCP connection.

Authentication setup

The public tools (search, list_examples, get_example) work without authentication. To use the execution tools (swap, orderbook, product_api, walletconnect, debug), pass your API key via the Authorization header. Get a key from the 1inch Business Portal.

For the conceptual overview of API key vs OAuth authentication, see Authentication.

Claude Code:


         
         

           Bash
         

 
         
         

           
           

             
1
2
3
4
5
6

           

 
           
           
claude mcp add \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --scope user \
  1inch-business \
  https://api.1inch.com/mcp/protocol

Cursor (.cursor/mcp.json):


         
         

           JSON
         

 
         
         

           
           

             
1
2
3
4
5
6
7
8
9
10

           

 
           
           
{
  "mcpServers": {
    "1inch-business": {
      "url": "https://api.1inch.com/mcp/protocol",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

VS Code Copilot (.vscode/mcp.json):


         
         

           JSON
         

 
         
         

           
           

             
1
2
3
4
5
6
7
8
9
10
11

           

 
           
           
{
  "servers": {
    "1inch-business": {
      "type": "http",
      "url": "https://api.1inch.com/mcp/protocol",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Claude Desktop (supergateway):


         
         

           JSON
         

 
         
         

           
           

             
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

           

 
           
           
{
  "mcpServers": {
    "1inch-business": {
      "command": "/absolute/path/to/node/bin/npx",
      "args": [
        "-y",
        "supergateway",
        "--streamableHttp",
        "https://api.1inch.com/mcp/protocol",
        "--header",
        "Authorization: Bearer YOUR_API_KEY",
        "--outputTransport",
        "stdio"
      ],
      "env": {
        "PATH": "/absolute/path/to/node/bin:/usr/bin:/bin"
      }
    }
  }
}

For other clients, consult the client's MCP documentation for how to set custom HTTP headers on the transport.

Wallet pairing (WalletConnect)

The walletconnect tool returns the pairing QR as an MCP resource link (pairingQrResourceUri) plus a fallback wc: URI. How that's surfaced depends on your client:

Client Pairing UX
Cursor / VS Code (Copilot) / Windsurf The assistant fetches the QR via resources/read in the same MCP session and renders it inline in chat (or opens it from disk). If your tool host doesn't render images, ask the assistant to print the wc: URI in a code block.
Claude Desktop / Claude Code Same as above — the assistant reads the resource and renders the PNG. On macOS / Linux it can also open the file with open / xdg-open.
OpenAI Codex / Gemini CLI If the CLI doesn't render images, the assistant prints the wc: URI; copy/paste it into your wallet app or another QR generator. The pairing URI is short-lived (~10 min).
Mobile-first usage (any client) The response also includes mobileDeeplinks for supported wallets — tap the wallet's HTTPS link and it opens the wallet app directly without scanning a QR.

Tips:

  • Don't call connect again to refresh — while pairing is still in progress, calling connect with the same pairingTarget returns the same URI. Repeated connect calls used to invalidate the active QR; now they don't, but only as long as the pairingTarget matches.
  • status: "pending" is success — keep polling. The wallet pairing only fails when status returns kind: "error".
  • Solana sessions: call connect with "pairingTarget": "solana" (Solana only) or "both" (EVM + Solana). Many mobile wallets reject pairings that propose eip155 and solana together — start with one namespace if you only need one.
  • Sticky Mcp-Session-Id is optional. WalletConnect state survives restarts and replicas because it's persisted server-side, keyed by your authenticated org/app rather than the MCP session id.

Troubleshooting

Issue Solution
Connection refused Verify the command path is absolute. Check that https://api.1inch.com/mcp/protocol is reachable from your network
Server not appearing Restart your AI client after modifying the configuration file. Check that the JSON is valid (no trailing commas)
npx not found Ensure Node.js 18+ is installed. Use an absolute path to npx in the command field (e.g., /usr/local/bin/npx)
Too many sessions (429) Each AI client window opens a separate session. Close windows you're not using, or wait 15 minutes for idle sessions to expire. This limit is specific to MCP sessions and does not affect your API usage
Tools not loading Check the AI client's MCP logs for connection errors. In Cursor, use Developer: Open MCP Log from the command palette
Auth prompt not appearing If using OAuth, ensure your MCP client supports OAuth flows. Alternatively, use an API key via the Authorization header (see Authentication setup). Some clients may require a restart after configuration changes
Stale results Documentation indexes are updated periodically. If recently published content is missing, try again in a few minutes
WalletConnect QR expired The pairing URI expires after ~10 minutes. Ask the assistant to call walletconnect connect again to get a fresh QR. If your earlier connect succeeded but you waited too long to scan, the wallet will show "expired" — start over with a new connect.
Wallet won't approve EVM + Solana Many mobile wallets reject pairings that propose eip155 and solana together. Reconnect with pairingTarget: "eth" or "solana" only, or use a wallet listed as supporting both (supported wallets).
solana_namespace_not_available The active WalletConnect session was approved for EVM only. Ask the assistant to disconnect, then connect again with "pairingTarget": "solana" or "both" and approve the Solana namespace in the wallet.
QR doesn't render in chat If the MCP host can't render the QR resource inline, ask the assistant to print the wc: URI in a fenced code block, or to open the PNG locally (open / xdg-open / start). On mobile, use the mobileDeeplinks from the response.

Did you find what you need?