diff --git a/README.es.md b/README.es.md
index 82cfcae1d..70ccd5eb1 100644
--- a/README.es.md
+++ b/README.es.md
@@ -138,7 +138,7 @@ Agrega el servidor MCP de SurfSense a Claude, Cursor o tu propio framework de ag
{
"mcpServers": {
"surfsense": {
- "url": "https://mcp.surfsense.com",
+ "url": "https://mcp.surfsense.com/mcp",
"headers": { "Authorization": "Bearer ${SURFSENSE_API_KEY}" }
}
}
diff --git a/README.hi.md b/README.hi.md
index 1c9cfa4a7..cbf9ae8fa 100644
--- a/README.hi.md
+++ b/README.hi.md
@@ -138,7 +138,7 @@ SurfSense MCP सर्वर को Claude, Cursor या अपने एज
{
"mcpServers": {
"surfsense": {
- "url": "https://mcp.surfsense.com",
+ "url": "https://mcp.surfsense.com/mcp",
"headers": { "Authorization": "Bearer ${SURFSENSE_API_KEY}" }
}
}
diff --git a/README.md b/README.md
index a05548d66..8f2e65118 100644
--- a/README.md
+++ b/README.md
@@ -138,7 +138,7 @@ Add the SurfSense MCP server to Claude, Cursor, or your own agent framework:
{
"mcpServers": {
"surfsense": {
- "url": "https://mcp.surfsense.com",
+ "url": "https://mcp.surfsense.com/mcp",
"headers": { "Authorization": "Bearer ${SURFSENSE_API_KEY}" }
}
}
diff --git a/README.pt-BR.md b/README.pt-BR.md
index 4f2b945f4..076736bcf 100644
--- a/README.pt-BR.md
+++ b/README.pt-BR.md
@@ -138,7 +138,7 @@ Adicione o servidor MCP do SurfSense ao Claude, ao Cursor ou ao seu próprio fra
{
"mcpServers": {
"surfsense": {
- "url": "https://mcp.surfsense.com",
+ "url": "https://mcp.surfsense.com/mcp",
"headers": { "Authorization": "Bearer ${SURFSENSE_API_KEY}" }
}
}
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 22410a727..7d2ae35c3 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -138,7 +138,7 @@ curl -X POST "$SURFSENSE_API_URL/workspaces/$WORKSPACE_ID/scrapers/reddit/scrape
{
"mcpServers": {
"surfsense": {
- "url": "https://mcp.surfsense.com",
+ "url": "https://mcp.surfsense.com/mcp",
"headers": { "Authorization": "Bearer ${SURFSENSE_API_KEY}" }
}
}
diff --git a/surfsense_mcp/README.md b/surfsense_mcp/README.md
index 47dabf55c..cc5ef19c5 100644
--- a/surfsense_mcp/README.md
+++ b/surfsense_mcp/README.md
@@ -2,9 +2,15 @@
A [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes
SurfSense to MCP clients like **Claude Code**, **Cursor**, and **Claude Desktop**.
-It talks to a running SurfSense backend purely over its REST API using a SurfSense
-API key — it imports no backend code and can point at any instance (local or
-hosted) by changing two environment variables.
+It talks to a SurfSense backend purely over its REST API using a SurfSense API
+key — it imports no backend code.
+
+Connect it two ways:
+
+- **Hosted** (recommended) — point your client at `https://mcp.surfsense.com/mcp`
+ and pass your API key in a header. Nothing to install or keep running.
+- **Self-host (stdio)** — run the server yourself against any backend (cloud or
+ your own). Best for self-hosters and clients without remote-server support.
## Tools
@@ -29,15 +35,42 @@ Workspace-scoped tools default to the active workspace; pass `workspace` (a name
or id) to override for a single call. Ids never need to be typed by hand — the
model carries them between calls.
-## Prerequisites
+## Get an API key
-1. A running SurfSense backend (default `http://localhost:8000`).
-2. A **SurfSense API key**: SurfSense → Settings → API → create key (`ss_pat_…`).
-3. **API access enabled** on the workspace(s) you want to use (workspace settings).
+1. SurfSense → **API Playground → API Keys**: create a personal key (`ss_pat_…`).
+ It is shown only once.
+2. Toggle **API key access** on for the workspace(s) you want to use.
-## Setup
+## Connect (hosted)
-Uses [uv](https://github.com/astral-sh/uv):
+Point your client at the hosted server and send the key as a Bearer token. For
+clients that read an `mcpServers` map (Cursor, Claude Desktop, and others):
+
+```json
+{
+ "mcpServers": {
+ "surfsense": {
+ "url": "https://mcp.surfsense.com/mcp",
+ "headers": { "Authorization": "Bearer ss_pat_your_key_here" }
+ }
+ }
+}
+```
+
+Claude Code, from a terminal:
+
+```bash
+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 uses [uv](https://github.com/astral-sh/uv):
```bash
cd surfsense_mcp
@@ -45,11 +78,8 @@ uv sync
uv run python -m surfsense_mcp.selfcheck # verify tools register correctly
```
-## Connect it to a client
-
-### Cursor
-
-Add to `~/.cursor/mcp.json` (or a project `.cursor/mcp.json`):
+Then add it to your client. Cursor (`~/.cursor/mcp.json` or a project
+`.cursor/mcp.json`):
```json
{
@@ -66,7 +96,7 @@ Add to `~/.cursor/mcp.json` (or a project `.cursor/mcp.json`):
}
```
-### Claude Code
+Claude Code:
```bash
claude mcp add surfsense \
@@ -75,15 +105,13 @@ claude mcp add surfsense \
-- uv run --directory /absolute/path/to/SurfSense/surfsense_mcp python -m surfsense_mcp
```
-### Claude Desktop
-
-Add the same `mcpServers` block as Cursor to
+Claude Desktop: add the same `mcpServers` block as Cursor to
`claude_desktop_config.json` (Settings → Developer → Edit Config).
## Configuration
-See `.env.example`. Secrets are passed as environment variables by the client;
-never commit tokens.
+See `.env.example`. For self-host, secrets are passed as environment variables by
+the client; never commit tokens.
## Backend dependency
diff --git a/surfsense_web/content/docs/how-to/mcp-server.mdx b/surfsense_web/content/docs/how-to/mcp-server.mdx
index ffdb4fd56..62628a659 100644
--- a/surfsense_web/content/docs/how-to/mcp-server.mdx
+++ b/surfsense_web/content/docs/how-to/mcp-server.mdx
@@ -4,51 +4,58 @@ description: Connect the SurfSense MCP server to Claude Code, Codex, OpenCode, C
---
import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
-import { Step, Steps } from 'fumadocs-ui/components/steps';
# SurfSense MCP Server
The SurfSense MCP server exposes your workspace to any [Model Context Protocol](https://modelcontextprotocol.io/) 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.
-It talks to SurfSense purely over the REST API — point it at SurfSense Cloud or your own self-hosted instance by changing one environment variable.
+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.
-## Prerequisites
+## Create an API key
-
-
+You need a SurfSense API key either way. In SurfSense, open **API Playground → API Keys** in your workspace sidebar:
-### Install uv
+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.
-The server runs with [uv](https://github.com/astral-sh/uv). Install it once, then from the SurfSense repository run:
+## 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):
+
+```json
+{
+ "mcpServers": {
+ "surfsense": {
+ "url": "https://mcp.surfsense.com/mcp",
+ "headers": { "Authorization": "Bearer ss_pat_your_key_here" }
+ }
+ }
+}
+```
+
+Claude Code, from a terminal:
+
+```bash
+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](https://github.com/astral-sh/uv) — install it once, then from the SurfSense repository run:
```bash
cd surfsense_mcp
uv sync
```
-
-
-
-### Create an API key
-
-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.
-
-
-
-
-### Know your base URL
+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`
-
-
-
-## Connect your agent
-
Every client below launches the same command — `uv run --directory /surfsense_mcp python -m surfsense_mcp` — and passes `SURFSENSE_BASE_URL` and `SURFSENSE_API_KEY` as environment variables. Replace the placeholder paths and key with yours.
@@ -221,7 +228,7 @@ Run `/mcp` inside Gemini CLI to confirm the server and its tools.
-The server uses stdio transport: your client launches the process on demand and shuts it down with the session. There is no daemon to manage — only your SurfSense backend needs to be up.
+In this mode your client launches the process on demand and shuts it down with the session. There is no daemon to manage — only your SurfSense backend needs to be up. (The hosted server above needs none of this.)
## Test it
@@ -236,7 +243,7 @@ That calls `surfsense_list_workspaces` — the simplest end-to-end check of the
## Configuration reference
-All settings are environment variables passed by the client:
+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:
| Variable | Required | Default | Purpose |
|----------|----------|---------|---------|