> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onebalance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server Setup

> How to connect the OneBalance Toolkit to your preferred AI tools like Claude and Cursor, using MCP to speed up your development process.

## Overview

The Model Context Protocol (MCP) connects OneBalance's documentation and API directly to your AI tools using our hosted MCP server for instant setup.

## Setup Instructions

### General

Our MCP server supports the Streamable HTTP transport and is centrally hosted at:

```
https://docs.onebalance.io/mcp
```

When using API endpoints, AI tools will prompt you for your OneBalance API key as needed. For testing purposes, you can use our public API key with limited usage: `42bb629272001ee1163ca0dbbbc07bcbb0ef57a57baf16c4b1d4672db4562c11`

### Claude

**Team, Enterprise (Claude.ai)**

1. Navigate to [Connectors](https://claude.ai/settings/connectors) in Claude settings
2. Select **Add custom connector**
3. Enter name: "OneBalance MCP" and URL: `https://docs.onebalance.io/mcp`
4. Select **Add**
5. When chatting with Claude, select the attachments button (plus icon)
6. Select "OneBalance MCP" to query Claude with OneBalance context and API access

**Free, Pro (Claude desktop)**

1. Open the file `~/Library/Application Support/Claude/claude_desktop_config.json`
2. Add the following and restart the Claude desktop app:

```json theme={null}
{
  "mcpServers": {
    "onebalance": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://docs.onebalance.io/mcp"]
    }
  }
}
```

### Cursor

Install from Cursor's settings or add manually:

1. Press <kbd>Command</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> (or <kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> on Windows)
2. Search for "Open MCP settings"
3. Add to your `mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "onebalance": {
      "url": "https://docs.onebalance.io/mcp"
    }
  }
}
```

4. Ask in Cursor chat: "What tools do you have available?" to confirm connection

### Visual Studio Code

1. Press <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>P</kbd> and search for **MCP: Add Server**
2. Select **Command (stdio)**
3. Enter the following configuration:

```bash theme={null}
npx mcp-remote https://docs.onebalance.io/mcp
```

4. Enter the name **OneBalance** and press enter
5. Activate using **MCP: List Servers**, select **OneBalance**, then **Start Server**

### Windsurf

1. Press <kbd>Ctrl</kbd>/<kbd>Cmd</kbd> + <kbd>,</kbd> to open Windsurf settings
2. Scroll to **Cascade** → **MCP servers**
3. Select **Add Server** → **Add custom server**
4. Add the following:

```json theme={null}
{
  "mcpServers": {
    "onebalance": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://docs.onebalance.io/mcp"]
    }
  }
}
```

### Zed

1. Press <kbd>Cmd</kbd> + <kbd>,</kbd> to open Zed settings
2. Add the following:

```json theme={null}
{
  "context_servers": {
    "onebalance": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://docs.onebalance.io/mcp"],
      "env": {}
    }
  }
}
```

### Other MCP-Compatible Tools

Many other tools support MCP servers. Configure them with these settings:

* **Command**: `npx`
* **Arguments**: `-y mcp-remote https://docs.onebalance.io/mcp`
* **Environment**: None

## Available Tools

The hosted MCP server provides these capabilities:

**Documentation:**

* `SearchOneBalanceDocs` - Search across the OneBalance Docs knowledge base

**Account Management:**

* `predictAddress` - Predict smart account addresses before deployment
* `listAggregatedAssets` - List all supported aggregated assets
* `getAggregatedBalance` - Fetch aggregated balances for EVM accounts
* `getAggregatedBalanceV3` - Fetch balances with multi-chain support (EVM + Solana)
* `supportedChains` - List all supported blockchain networks

**Transaction Status & History:**

* `getCallsStatus` - Check quote execution status and transaction hashes
* `getCallsStatusV3` - Check status with multi-blockchain support
* `getCallsHistory` - Retrieve transaction history for EVM accounts
* `getCallsHistoryV3` - Retrieve history with multi-chain support

**Quote Generation & Execution:**

* `getQuote` - Request transfer/swap quotes for EVM chains
* `getQuoteV3` - Request quotes with multi-account support (EVM + Solana)
* `prepareCallQuote` - Prepare contract call operations
* `getCallQuote` - Get quotes for contract interactions
* `executeQuote` - Execute transfer/swap quotes
* `executeQuoteV3` - Execute quotes with multi-chain support
* `prepareCallQuoteV3` - Prepare contract calls with multi-account support
* `getCallQuoteV3` - Get contract quotes with multi-account support

## Authentication

Get your production API key from the [authentication page](/api-reference/authentication). For testing purposes, you can use our public API key: `42bb629272001ee1163ca0dbbbc07bcbb0ef57a57baf16c4b1d4672db4562c11`

AI tools will prompt you for the API key when accessing OneBalance functions. The MCP server handles authentication automatically once configured.

## Usage

Once configured, use these functions directly in your AI tools:

* Ask questions about OneBalance integration
* Get live data from your smart contract accounts
* Generate code with current API context
* Search docs without leaving your editor

## FAQ

<AccordionGroup>
  <Accordion title="Why am I seeing a connection error when trying to connect?">
    Check that you're using the correct URL: `https://docs.onebalance.io/mcp`. If you're using Claude Desktop or other clients that require `mcp-remote`, ensure you have the latest version of Node.js installed.
  </Accordion>

  <Accordion title="I'm not being prompted for my API key">
    The MCP server will only prompt for API keys when you try to use OneBalance API functions. Documentation search works without authentication. Try asking: "What's my aggregated balance?" to trigger the API key prompt.
  </Accordion>

  <Accordion title="Can I use my own API keys instead of the public test key?">
    Yes! Get your production API key from the [authentication page](/api-reference/authentication). The MCP server will prompt you to enter it when accessing OneBalance functions, and it will be securely stored for future use.
  </Accordion>

  <Accordion title="Which transport protocol does OneBalance MCP support?">
    OneBalance MCP server supports Streamable HTTP transport at `https://docs.onebalance.io/mcp`. For clients that don't support direct HTTP connections, use `mcp-remote` as shown in the setup instructions.
  </Accordion>

  <Accordion title="I'm using WSL on Windows and seeing errors">
    Try updating your configuration to use WSL explicitly:

    ```json theme={null}
    {
      "mcpServers": {
        "onebalance": {
          "command": "wsl",
          "args": ["npx", "-y", "mcp-remote", "https://docs.onebalance.io/mcp"]
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

<CardGroup cols={2}>
  <Card title="Example Prompts" icon="message-square" href="/ai/mcp-prompts">
    Ready-to-use prompts to explore OneBalance capabilities
  </Card>

  <Card title="Building with LLMs" icon="brain" href="/ai/building-with-llms">
    Learn about other AI integration options with OneBalance
  </Card>
</CardGroup>

<Note>
  Need help? Use the **Intercom chat widget** in the bottom right corner for instant assistance, or contact [support@onebalance.io](mailto:support@onebalance.io).
</Note>