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

# MCP Server Setup

> Connect FlipsideAI to Claude Desktop, Claude Code, and Cursor using the Model Context Protocol

The Flipside MCP (Model Context Protocol) server lets you access Flipside blockchain data directly
from Claude Desktop, Claude Code, and Cursor. Once configured, you can query Flipside data without
leaving your development environment.

## Prerequisites

Before setting up the MCP server, you'll need:

* A Flipside API key
  ([Get your API key](https://app.flipsidecrypto.xyz/settings/organization/api-keys))
* One of the supported applications: Claude Desktop, Claude Code, or Cursor

## Configuration

The setup process varies slightly by application. Select your platform below:

<Tabs>
  <Tab title="Claude Desktop">
    <Steps>
      <Step title="Open Claude Desktop">
        Launch the Claude Desktop application on your computer.
      </Step>

      <Step title="Access Settings">
        Click on your profile icon and select **Settings**.
      </Step>

      <Step title="Navigate to Developer">
        Click on the **Developer** tab in the settings sidebar.
      </Step>

      <Step title="Open Config File">
        Click **Edit Config**. This will open the folder where the `claude_desktop_config.json` file is located.
      </Step>

      <Step title="Edit Configuration">
        Open the `claude_desktop_config.json` file in a text editor. Add the following configuration to your `mcpServers` section:

        ```json theme={null}
        "flipside": {
          "type": "http",
          "url": "https://mcp.flipsidecrypto.xyz/mcp?apiKey=API_KEY"
        }
        ```

        Replace `API_KEY` with your actual Flipside API key.
      </Step>

      <Step title="Save and Restart">
        Save the file and restart Claude Desktop to apply the changes.
      </Step>
    </Steps>

    <Note>
      Your `claude_desktop_config.json` file should have a structure like this:

      ```json theme={null}
      {
        "mcpServers": {
          "flipside": {
            "type": "http",
            "url": "https://mcp.flipsidecrypto.xyz/mcp?apiKey=YOUR_API_KEY"
          }
        }
      }
      ```
    </Note>
  </Tab>

  <Tab title="Claude Code">
    ### Option 1: CLI Command

    Run this command in your terminal (must be on a single line):

    ```bash theme={null}
    claude mcp add flipside -- npx mcp-remote https://mcp.flipsidecrypto.xyz/mcp --header "x-api-key:YOUR_API_KEY"
    ```

    Replace `YOUR_API_KEY` with your actual Flipside API key (starts with `fv_`).

    <Warning>
      When pasting this command, ensure it stays on a single line. If the terminal breaks the line, the command will fail. Use the settings file method below instead.
    </Warning>

    <Tip>
      To remove or update the server, use `claude mcp remove flipside` or edit your settings file directly.
    </Tip>

    ### Option 2: Edit Settings File

    <Steps>
      <Step title="Open Claude Code Settings">
        You can configure the MCP at either:

        * **Project-level**: Create or edit `.claude/settings.json` in your project root
        * **User-level**: Edit `~/.claude/settings.json` for MCPs you want everywhere
      </Step>

      <Step title="Add MCP Configuration">
        Add the following configuration to your settings file:

        ```json theme={null}
        {
          "mcpServers": {
            "flipside": {
              "command": "npx",
              "args": [
                "mcp-remote",
                "https://mcp.flipsidecrypto.xyz/mcp",
                "--header",
                "x-api-key:YOUR_API_KEY"
              ]
            }
          }
        }
        ```

        Replace `YOUR_API_KEY` with your actual Flipside API key (starts with `fv_`).
      </Step>

      <Step title="Restart Claude Code">
        Restart Claude Code to apply the changes. You can verify by running `/mcp` to see connected servers.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Cursor">
    <Steps>
      <Step title="Open Settings">
        Open Cursor and press `Cmd + ,` (Mac) or `Ctrl + ,` (Windows/Linux) to open settings.
      </Step>

      <Step title="Navigate to MCP Settings">
        Search for "MCP" in the settings search bar, or navigate to the MCP settings section.
      </Step>

      <Step title="Add MCP Server">
        Click on **Add a custom MCP server** or **Edit Config** to open the MCP configuration file.
      </Step>

      <Step title="Edit Configuration">
        Add the following configuration to your MCP servers list:

        ```json theme={null}
        "flipside": {
          "type": "http",
          "url": "https://mcp.flipsidecrypto.xyz/mcp?apiKey=API_KEY"
        }
        ```

        Replace `API_KEY` with your actual Flipside API key.
      </Step>

      <Step title="Save and Restart">
        Save the configuration file and restart Cursor to apply the changes.
      </Step>
    </Steps>

    <Note>
      The MCP configuration file location varies by platform:

      * **macOS**: `~/Library/Application Support/Cursor/User/globalStorage/mcp.json`
      * **Windows**: `%APPDATA%\Cursor\User\globalStorage\mcp.json`
      * **Linux**: `~/.config/Cursor/User/globalStorage/mcp.json`
    </Note>
  </Tab>
</Tabs>

## Verifying Your Setup

After configuring the MCP server, you can verify it's working by:

1. **In Claude Desktop**: Start a new conversation and ask about Flipside data. The MCP server
   should be available as a tool.
2. **In Claude Code**: Use the MCP tools in your code editor to query Flipside data.
3. **In Cursor**: The MCP server should appear in your available tools when working with code.

## Getting Your API Key

If you don't have a Flipside API key yet:

1. Visit
   [Flipspace Settings → API Keys](https://app.flipsidecrypto.xyz/settings/organization/api-keys)
2. Sign in or create an account
3. Generate a new API key (it will start with `fv_`)
4. Copy the key and use it in your MCP configuration

<Warning>
  Keep your API key secure. Never commit it to version control or share it publicly. If your key is
  compromised, revoke it immediately and generate a new one.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="MCP server not appearing" icon="question">
    * Verify your API key is correct and active
    * Check that the configuration JSON is valid (no syntax errors)
    * Ensure you've restarted the application after making changes
    * Check the application's logs for error messages
  </Accordion>

  <Accordion title="Connection errors" icon="wifi">
    * Verify your internet connection - Check that the URL is correct:
      `https://mcp.flipsidecrypto.xyz/mcp?apiKey=YOUR_KEY` - Ensure your API key hasn't been revoked or
      expired - Try regenerating your API key if issues persist
  </Accordion>

  <Accordion title="Configuration file not found" icon="file">
    * For Claude Desktop: Use the "Edit Config" button in Settings → Developer
    * For Cursor: The config file may need to be created manually in the globalStorage directory
    * Ensure you have write permissions to the configuration directory
  </Accordion>
</AccordionGroup>

## What You Can Do with MCP

Once connected, you can:

* Query Flipside blockchain data directly from your editor
* Access data across 30+ networks and 7+ trillion data points
* Get real-time blockchain intelligence without switching applications
* Integrate Flipside data into your development workflow

## Next Steps

<CardGroup cols={2}>
  <Card title="Get your API key" icon="key" href="https://app.flipsidecrypto.xyz/settings/organization/api-keys">
    Generate a Flipside API key to get started
  </Card>

  <Card title="Explore FlipsideAI" icon="robot" href="/flipsideai/quickstart">
    Learn how to use FlipsideAI in the web interface
  </Card>

  <Card title="API Documentation" icon="book" href="/api">
    Explore the full Flipside API reference
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/flipsideai/troubleshooting">
    Get help with common issues
  </Card>
</CardGroup>