Claude Desktop Setup

Query your Surfa analytics with natural language through Claude Desktop.

Prerequisites

Claude Desktop installed (download here)
Surfa account with API key (sign up at surfa.dev)
uv package manager (install guide)

Get your Surfa API key from your dashboard.

Step 1: Install the MCP Server

Clone the Surfa MCP repository:

git clone https://github.com/gamladz/surfa-mcp.git
cd surfa-mcp

Create a virtual environment and install dependencies:

uv venv
uv pip install -e .

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

Step 2: Find Your uv Path

You’ll need the full path to uv for the Claude Desktop config. macOS/Linux:

which uv

Common paths:

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

Use the full absolute path, not just uv. Claude Desktop needs the complete path.

Step 3: Configure Claude Desktop

Find your Claude Desktop config file: macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Open the file and add the Surfa MCP server:

{
  "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"
      }
    }
  }
}

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

If You Have Other MCP Servers

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

{
  "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:

Cmd+Q to quit Claude Desktop
Reopen from Applications

Windows:

Right-click system tray → Quit
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.

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

Success! Your Surfa MCP Server is now connected and working.

Using Remote MCP

Want to use a remote MCP instead of local?

Option 1: Fly.io Proxy (Experimental)

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

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.

Option 2: Direct HTTP (Coming Soon)

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

Remote MCP Deployment

Learn how to deploy and test remote MCPs

Example Queries

Try these queries to explore your analytics:

"Show me my Surfa analytics overview"

Troubleshooting

Surfa not showing in MCP servers list

Check:

Config file path is correct
JSON syntax is valid (use jsonlint.com)
No trailing commas in JSON
File saved after editing

Debug: Check Claude Desktop logs:

# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows
type %APPDATA%\Claude\Logs\mcp*.log

Connection failed / Server not responding

Check:

uv path is correct (run which uv again)
Surfa MCP directory path is absolute, not relative
API key is correct (check dashboard)
Internet connection is working

Test manually:

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.

'No data' or empty responses

Check:

You have events in your Surfa dashboard
API key has access to the workspace
Events are from “live” source (not test data)

Verify: Go to your dashboard and confirm you see events.

'Module not found' error

Solution: Reinstall dependencies:

cd /path/to/surfa-mcp
uv pip install -e .

Then restart Claude Desktop.

JSON syntax error in config

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 to validate.Example of valid JSON:

{
  "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"
      }
    }
  }
}

Advanced Configuration

Using Production API

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

{
  "env": {
    "SURFA_API_KEY": "sk_live_your_key_here",
    "SURFA_API_URL": "https://surfa.dev"
  }
}

Custom Timeout

Set a custom timeout (in seconds):

{
  "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:

{
  "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:

cd /path/to/surfa-mcp
git pull
uv pip install -e .

Then restart Claude Desktop.

Uninstalling

To remove the Surfa MCP Server:

Remove the "surfa" entry from claude_desktop_config.json
Restart Claude Desktop
Optionally delete the cloned directory:
```
rm -rf /path/to/surfa-mcp
```

Next Steps

MCP Server Overview

Learn about all 4 analytics tools and example queries

API Reference

Complete API documentation with examples

Quickstart Guide

Start tracking events in 5 minutes

GitHub Repository

View source and contribute

Need Help?

Join Discord

Get help from the community and Surfa team

Getting Started

MCP Server

Guides

Prerequisites

Step 1: Install the MCP Server

Step 2: Find Your uv Path

Step 3: Configure Claude Desktop

If You Have Other MCP Servers

Step 4: Restart Claude Desktop

Step 5: Verify Connection

Step 6: Test Your First Query

Using Remote MCP

Option 1: Fly.io Proxy (Experimental)

Option 2: Direct HTTP (Coming Soon)

Remote MCP Deployment

Example Queries

Troubleshooting

Advanced Configuration

Using Production API

Custom Timeout

Multiple Workspaces

Updating the MCP Server

Uninstalling

Next Steps

MCP Server Overview

API Reference

Quickstart Guide

GitHub Repository

Need Help?

Join Discord

Getting Started

MCP Server

Guides

​Prerequisites

​Step 1: Install the MCP Server

​Step 2: Find Your uv Path

​Step 3: Configure Claude Desktop

​If You Have Other MCP Servers

​Step 4: Restart Claude Desktop

​Step 5: Verify Connection

​Step 6: Test Your First Query

​Using Remote MCP

​Option 1: Fly.io Proxy (Experimental)

​Option 2: Direct HTTP (Coming Soon)

Remote MCP Deployment

​Example Queries

​Troubleshooting

​Advanced Configuration

​Using Production API

​Custom Timeout

​Multiple Workspaces

​Updating the MCP Server

​Uninstalling

​Next Steps

MCP Server Overview

API Reference

Quickstart Guide

GitHub Repository

​Need Help?

Join Discord

Prerequisites

Step 1: Install the MCP Server

Step 2: Find Your uv Path

Step 3: Configure Claude Desktop

If You Have Other MCP Servers

Step 4: Restart Claude Desktop

Step 5: Verify Connection

Step 6: Test Your First Query

Using Remote MCP

Option 1: Fly.io Proxy (Experimental)

Option 2: Direct HTTP (Coming Soon)

Example Queries

Troubleshooting

Advanced Configuration

Using Production API

Custom Timeout

Multiple Workspaces

Updating the MCP Server

Uninstalling

Next Steps

Need Help?