mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-07-10 22:32:16 +02:00
docs(mcp): document hosted /mcp remote endpoint
This commit is contained in:
CREDO23
parent
2b9daead58
commit
9aef0c27a2
7 changed files with 88 additions and 53 deletions
|
|
@ -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}" }
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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}" }
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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}" }
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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}" }
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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}" }
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
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
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### 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.
|
||||
|
||||
</Step>
|
||||
<Step>
|
||||
|
||||
### 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`
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Connect your agent
|
||||
|
||||
Every client below launches the same command — `uv run --directory <path-to>/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.
|
||||
|
||||
<Tabs items={['Claude Code', 'Codex', 'OpenCode', 'Cursor', 'Claude Desktop', 'VS Code', 'Windsurf', 'Gemini CLI']}>
|
||||
|
|
@ -221,7 +228,7 @@ Run `/mcp` inside Gemini CLI to confirm the server and its tools.
|
|||
</Tabs>
|
||||
|
||||
<Callout type="info" title="stdio transport — nothing to keep running">
|
||||
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.)
|
||||
</Callout>
|
||||
|
||||
## 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 |
|
||||
|----------|----------|---------|---------|
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue