The 1inch [MCP Server](ecosystem.md) and [AI Skills](ecosystem.md#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](#claude-desktop) | [Install](#ai-skills-installation) |
| Claude Code | [Instructions](#claude-code) | [Install](#ai-skills-installation) |
| OpenAI Codex | [Instructions](#openai-codex) | [Install](#ai-skills-installation) |
| Gemini CLI | [Instructions](#gemini-cli) | [Install](#ai-skills-installation) |
| 
Cursor | [Instructions](#cursor) | [Install](#ai-skills-installation) |
| 
Windsurf | [Instructions](#windsurf) | [Install](#ai-skills-installation) |
| 
VS Code (Copilot) | [Instructions](#vs-code-copilot) | [Install](#ai-skills-installation) |
| JetBrains IDEs | [Instructions](#jetbrains-ides) | [Install](#ai-skills-installation) |
The following clients are also MCP-compatible and can connect using the [generic setup](#other-mcp-clients) 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
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
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
gemini mcp add \
--transport http \
1inch-business \
https://api.1inch.com/mcp/protocol
```
### Claude Desktop
Claude Desktop communicates via stdio, so you use [`supergateway`](https://www.npmjs.com/package/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
{
"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)`).
:::info
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
{
"mcpServers": {
"1inch-business": {
"url": "https://api.1inch.com/mcp/protocol"
}
}
}
```
### Windsurf
Create or edit `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"1inch-business": {
"serverUrl": "https://api.1inch.com/mcp/protocol"
}
}
}
```
### VS Code (Copilot)
Create or edit `.vscode/mcp.json` in your project root:
```json
{
"servers": {
"1inch-business": {
"type": "http",
"url": "https://api.1inch.com/mcp/protocol"
}
}
}
```
:::info
VS Code also supports configuring MCP servers through `settings.json` under the `"mcp"` key. See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) 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
{
"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`](https://www.npmjs.com/package/supergateway) to bridge to the HTTP server (requires Node.js 18+):
```bash
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
npx skills add 1inch/1inch-ai
```
No npm package required — distribution is git-based. For more details, see [AI Skills](ecosystem.md#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](#claude-desktop) 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`, `debug`), pass your API key via the `Authorization` header. Get a key from the [1inch Business Portal](https://business.1inch.com/portal).
For the conceptual overview of API key vs OAuth authentication, see [Authentication](ecosystem.md#authentication).
**Claude Code:**
```bash
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
{
"mcpServers": {
"1inch-business": {
"url": "https://api.1inch.com/mcp/protocol",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
**VS Code Copilot** (`.vscode/mcp.json`):
```json
{
"servers": {
"1inch-business": {
"type": "http",
"url": "https://api.1inch.com/mcp/protocol",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}
```
**Claude Desktop** (supergateway):
```json
{
"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.
## 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](#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 |