SurfSense MCP Server

The SurfSense MCP server exposes your workspace to any Model Context Protocol client. Your agent gets 18 native, typed tools: every scraper (Reddit, YouTube, Google Maps, Google Search, web crawl), full knowledge-base access (search, read, add, upload, update, delete), and a workspace selector.

Connect it two ways: the hosted server at https://mcp.surfsense.com/mcp (nothing to install — just an API key), or run it yourself over stdio against any SurfSense backend, cloud or self-hosted.

Create an API key

You need a SurfSense API key either way. In SurfSense, open API Playground → API Keys in your workspace sidebar:

1. Toggle API key access on for the workspace.
2. Create a personal API key (ss_pat_…) and copy it — it is shown only once.

Connect (hosted)

The hosted server runs at https://mcp.surfsense.com/mcp. Point your client at it and send the key as a Bearer token — there is nothing to install and no backend to run. For clients that read an mcpServers map (Cursor, and others):

{
  "mcpServers": {
    "surfsense": {
      "url": "https://mcp.surfsense.com/mcp",
      "headers": { "Authorization": "Bearer ss_pat_your_key_here" }
    }
  }
}

Claude Code, from a terminal:

claude mcp add --transport http surfsense https://mcp.surfsense.com/mcp \
  --header "Authorization: Bearer ss_pat_your_key_here"

Most MCP clients accept this url + headers form; check your client's docs for its exact remote-server field.

Self-host (stdio)

Run the server yourself when you host your own backend or use a client without remote support. It runs with uv — install it once, then from the SurfSense repository run:

cd surfsense_mcp
uv sync

Point the server at your backend with SURFSENSE_BASE_URL:

• SurfSense Cloud: https://api.surfsense.com
• Self-hosted: wherever your backend runs, e.g. http://localhost:8000

Every client below launches the same command — uv run --directory <path-to>/surfsense_mcp python -m mcp_server — and passes SURFSENSE_BASE_URL and SURFSENSE_API_KEY as environment variables. Replace the placeholder paths and key with yours.

claude mcp add surfsense \
  -e SURFSENSE_BASE_URL=https://api.surfsense.com \
  -e SURFSENSE_API_KEY=ss_pat_your_key_here \
  -- uv run --directory /path/to/SurfSense/surfsense_mcp python -m mcp_server

[mcp_servers.surfsense]
command = "uv"
args = ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"]

[mcp_servers.surfsense.env]
SURFSENSE_BASE_URL = "https://api.surfsense.com"
SURFSENSE_API_KEY = "ss_pat_your_key_here"

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "surfsense": {
      "type": "local",
      "command": ["uv", "run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"],
      "enabled": true,
      "environment": {
        "SURFSENSE_BASE_URL": "https://api.surfsense.com",
        "SURFSENSE_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "surfsense": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"],
      "env": {
        "SURFSENSE_BASE_URL": "https://api.surfsense.com",
        "SURFSENSE_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "surfsense": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"],
      "env": {
        "SURFSENSE_BASE_URL": "https://api.surfsense.com",
        "SURFSENSE_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

{
  "servers": {
    "surfsense": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"],
      "env": {
        "SURFSENSE_BASE_URL": "https://api.surfsense.com",
        "SURFSENSE_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "surfsense": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"],
      "env": {
        "SURFSENSE_BASE_URL": "https://api.surfsense.com",
        "SURFSENSE_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "surfsense": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/SurfSense/surfsense_mcp", "python", "-m", "mcp_server"],
      "env": {
        "SURFSENSE_BASE_URL": "https://api.surfsense.com",
        "SURFSENSE_API_KEY": "ss_pat_your_key_here"
      }
    }
  }
}

Test it

In a fresh agent session, try:

list my SurfSense workspaces

That calls surfsense_list_workspaces — the simplest end-to-end check of the key, backend, and server. Then try a real task:

find the top subreddits discussing NotebookLM and save a summary note to my workspace

Configuration reference

For self-host (stdio), all settings are environment variables passed by the client. The hosted server needs only your API key in the Authorization header:

Troubleshooting

• 401 errors — the API key is wrong or expired; create a new one.
• 403 errors — API access is disabled for the workspace; toggle API key access on under API Playground → API Keys.
• "Could not reach SurfSense" — the backend isn't running or SURFSENSE_BASE_URL is wrong.
• Server won't start — run uv run python -m mcp_server.selfcheck inside surfsense_mcp; it verifies all 18 tools register without needing a backend.

Tools reference

Usage is billed exactly like the REST API — scraper tools are metered per returned item, and every call is recorded under API Playground → Runs.