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

# Claude Desktop Setup

> Install and configure the Surfa MCP Server for Claude Desktop

Query your Surfa analytics with natural language through Claude Desktop.

## Prerequisites

* Claude Desktop installed ([download here](https://claude.ai/download))
* Surfa account with API key ([sign up at surfa.dev](https://surfa.dev))
* `uv` package manager ([install guide](https://docs.astral.sh/uv/getting-started/installation/))

<Note>
  Get your Surfa API key from your [dashboard](https://surfa-web.vercel.app/dashboard).
</Note>

## Step 1: Install the MCP Server

Clone the Surfa MCP repository:

```bash theme={null}
git clone https://github.com/gamladz/surfa-mcp.git
cd surfa-mcp
```

Create a virtual environment and install dependencies:

```bash theme={null}
uv venv
uv pip install -e .
```

<Tip>
  The `-e` flag installs in editable mode, so you can update the code later with `git pull`.
</Tip>

## Step 2: Find Your uv Path

You'll need the full path to `uv` for the Claude Desktop config.

**macOS/Linux:**

```bash theme={null}
which uv
```

**Common paths:**

* `/Users/yourname/.local/bin/uv` (macOS)
* `/home/yourname/.local/bin/uv` (Linux)
* `/opt/homebrew/bin/uv` (macOS with Homebrew)

<Warning>
  Use the **full absolute path**, not just `uv`. Claude Desktop needs the complete path.
</Warning>

## Step 3: Configure Claude Desktop

Find your Claude Desktop config file:

**macOS:**

```bash theme={null}
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Windows:**

```bash theme={null}
%APPDATA%\Claude\claude_desktop_config.json
```

**Linux:**

```bash theme={null}
~/.config/Claude/claude_desktop_config.json
```

Open the file and add the Surfa MCP server:

```json theme={null}
{
  "mcpServers": {
    "surfa": {
      "command": "/Users/yourname/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/yourname/path/to/surfa-mcp",
        "run",
        "surfa-mcp"
      ],
      "env": {
        "SURFA_API_KEY": "sk_live_your_key_here",
        "SURFA_API_URL": "https://surfa-web.vercel.app"
      }
    }
  }
}
```

<Warning>
  **Replace these values:**

  * `/Users/yourname/.local/bin/uv` → Your actual `uv` path from Step 2
  * `/Users/yourname/path/to/surfa-mcp` → Your actual clone directory
  * `sk_live_your_key_here` → Your Surfa API key
</Warning>

### If You Have Other MCP Servers

If you already have MCP servers configured, just add Surfa to the existing `mcpServers` object:

```json theme={null}
{
  "mcpServers": {
    "existing-server": {
      "command": "...",
      "args": [...]
    },
    "surfa": {
      "command": "/Users/yourname/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/yourname/path/to/surfa-mcp",
        "run",
        "surfa-mcp"
      ],
      "env": {
        "SURFA_API_KEY": "sk_live_your_key_here",
        "SURFA_API_URL": "https://surfa-web.vercel.app"
      }
    }
  }
}
```

## Step 4: Restart Claude Desktop

**Important:** You must completely quit and reopen Claude Desktop for changes to take effect.

**macOS:**

1. Cmd+Q to quit Claude Desktop
2. Reopen from Applications

**Windows:**

1. Right-click system tray → Quit
2. Reopen from Start menu

## Step 5: Verify Connection

Look for the 🔌 icon in the bottom-right corner of Claude Desktop.

Click it to see connected MCP servers. You should see **"surfa"** in the list.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/surfa/images/claude-mcp-icon.png" alt="MCP Icon in Claude Desktop" />
</Frame>

## Step 6: Test Your First Query

Ask Claude:

```
Show me my Surfa analytics overview
```

You should get a response like:

```
Your Surfa analytics:
- Total Sessions: 35
- Success Rate: 85%
- Average Execution Time: 245ms
- Active Sessions: 2
```

<Check>
  **Success!** Your Surfa MCP Server is now connected and working.
</Check>

## Using Remote MCP

Want to use a remote MCP instead of local?

### Option 1: Fly.io Proxy (Experimental)

```json theme={null}
{
  "mcpServers": {
    "surfa-remote": {
      "command": "fly",
      "args": ["mcp", "proxy", "https://surfa-mcp.fly.dev/sse"],
      "env": {
        "SURFA_API_KEY": "sk_live_your_key"
      }
    }
  }
}
```

<Warning>
  The `fly mcp proxy` command is experimental and may have issues. For production use, we recommend using the Surfa web platform to test remote MCPs.
</Warning>

### Option 2: Direct HTTP (Coming Soon)

Claude Desktop doesn't yet support direct HTTP MCP connections. Use the Surfa web platform instead.

<Card title="Remote MCP Deployment" icon="cloud" href="/remote-mcp-deployment" horizontal>
  Learn how to deploy and test remote MCPs
</Card>

## Example Queries

Try these queries to explore your analytics:

<CodeGroup>
  ```text Get Started theme={null}
  "Show me my Surfa analytics overview"
  ```

  ```text Find Errors theme={null}
  "Show me all errors from the last 24 hours"
  ```

  ```text Performance theme={null}
  "What were the slowest queries this week?"
  ```

  ```text Deep Dive theme={null}
  "Analyze my product health and give me recommendations"
  ```
</CodeGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Surfa not showing in MCP servers list" icon="circle-exclamation">
    **Check:**

    1. Config file path is correct
    2. JSON syntax is valid (use [jsonlint.com](https://jsonlint.com))
    3. No trailing commas in JSON
    4. File saved after editing

    **Debug:**
    Check Claude Desktop logs:

    ```bash theme={null}
    # macOS
    tail -f ~/Library/Logs/Claude/mcp*.log

    # Windows
    type %APPDATA%\Claude\Logs\mcp*.log
    ```
  </Accordion>

  <Accordion title="Connection failed / Server not responding" icon="circle-exclamation">
    **Check:**

    1. `uv` path is correct (run `which uv` again)
    2. Surfa MCP directory path is absolute, not relative
    3. API key is correct (check dashboard)
    4. Internet connection is working

    **Test manually:**

    ```bash theme={null}
    cd /path/to/surfa-mcp
    export SURFA_API_KEY=sk_live_your_key
    export SURFA_API_URL=https://surfa-web.vercel.app
    uv run surfa-mcp
    ```

    If this works, the issue is in your Claude Desktop config.
  </Accordion>

  <Accordion title="'No data' or empty responses" icon="circle-exclamation">
    **Check:**

    1. You have events in your Surfa dashboard
    2. API key has access to the workspace
    3. Events are from "live" source (not test data)

    **Verify:**
    Go to [your dashboard](https://surfa-web.vercel.app/dashboard) and confirm you see events.
  </Accordion>

  <Accordion title="'Module not found' error" icon="circle-exclamation">
    **Solution:**
    Reinstall dependencies:

    ```bash theme={null}
    cd /path/to/surfa-mcp
    uv pip install -e .
    ```

    Then restart Claude Desktop.
  </Accordion>

  <Accordion title="JSON syntax error in config" icon="circle-exclamation">
    **Common mistakes:**

    * Trailing comma after last item
    * Missing quotes around strings
    * Backslashes in Windows paths (use forward slashes or double backslashes)

    **Fix:**
    Copy your config to [jsonlint.com](https://jsonlint.com) to validate.

    **Example of valid JSON:**

    ```json theme={null}
    {
      "mcpServers": {
        "surfa": {
          "command": "/path/to/uv",
          "args": ["--directory", "/path/to/surfa-mcp", "run", "surfa-mcp"],
          "env": {
            "SURFA_API_KEY": "sk_live_key",
            "SURFA_API_URL": "https://surfa-web.vercel.app"
          }
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Advanced Configuration

### Using Production API

If you're using the production Surfa API (not localhost):

```json theme={null}
{
  "env": {
    "SURFA_API_KEY": "sk_live_your_key_here",
    "SURFA_API_URL": "https://surfa.dev"
  }
}
```

### Custom Timeout

Set a custom timeout (in seconds):

```json theme={null}
{
  "env": {
    "SURFA_API_KEY": "sk_live_your_key_here",
    "SURFA_API_URL": "https://surfa-web.vercel.app",
    "SURFA_TIMEOUT": "60"
  }
}
```

### Multiple Workspaces

Use different API keys for different workspaces:

```json theme={null}
{
  "mcpServers": {
    "surfa-production": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/surfa-mcp", "run", "surfa-mcp"],
      "env": {
        "SURFA_API_KEY": "sk_live_prod_key",
        "SURFA_API_URL": "https://surfa.dev"
      }
    },
    "surfa-staging": {
      "command": "/path/to/uv",
      "args": ["--directory", "/path/to/surfa-mcp", "run", "surfa-mcp"],
      "env": {
        "SURFA_API_KEY": "sk_live_staging_key",
        "SURFA_API_URL": "https://staging.surfa.dev"
      }
    }
  }
}
```

## Updating the MCP Server

To update to the latest version:

```bash theme={null}
cd /path/to/surfa-mcp
git pull
uv pip install -e .
```

Then restart Claude Desktop.

## Uninstalling

To remove the Surfa MCP Server:

1. Remove the `"surfa"` entry from `claude_desktop_config.json`
2. Restart Claude Desktop
3. Optionally delete the cloned directory:
   ```bash theme={null}
   rm -rf /path/to/surfa-mcp
   ```

## Next Steps

<CardGroup cols={2}>
  <Card title="MCP Server Overview" icon="book-open" href="/mcp-server-overview">
    Learn about all 4 analytics tools and example queries
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference">
    Complete API documentation with examples
  </Card>

  <Card title="Quickstart Guide" icon="rocket" href="/quickstart">
    Start tracking events in 5 minutes
  </Card>

  <Card title="GitHub Repository" icon="github" href="https://github.com/gamladz/surfa-mcp">
    View source and contribute
  </Card>
</CardGroup>

## Need Help?

<Card title="Join Discord" icon="discord" href="https://discord.gg/surfa" horizontal>
  Get help from the community and Surfa team
</Card>