apunkt/SurfSense
1
0
Fork 0
mirror of https://github.com/MODSetter/SurfSense.git synced 2026-07-10 22:32:16 +02:00
Code Issues Projects Releases Packages Wiki Activity

feat(web): add hosted and self-host MCP client configs

Browse source
This commit is contained in:
CREDO23 2026-07-07 18:06:04 +02:00
parent 6da1dd8f86
commit 6b204a2f8c
4 changed files with 350 additions and 154 deletions
Download patch file Download diff file Expand all files Collapse all files

21
surfsense_web/app/(home)/mcp-server/page.tsx
View file

@ -50,16 +50,13 @@ export const metadata: Metadata = {
}, },
}; };
/* Mirrors surfsense_mcp/README.md: the real Cursor config. */ /* The hosted Cursor config; mirrors lib/mcp/clients.ts. */
const CURSOR_CONFIG = `{ const CURSOR_CONFIG = `{
"mcpServers": { "mcpServers": {
"surfsense": { "surfsense": {
"command": "uv", "url": "https://mcp.surfsense.com/mcp",
"args": ["run", "--directory", ".../surfsense_mcp", "headers": {
"python", "-m", "surfsense_mcp"], "Authorization": "Bearer ss_pat_..."
"env": {
"SURFSENSE_BASE_URL": "https://api.surfsense.com",
"SURFSENSE_API_KEY": "ss_pat_..."
} }
} }
} }
@ -76,7 +73,7 @@ const STEPS = [
icon: TerminalSquare, icon: TerminalSquare,
title: "Add the server to your client", title: "Add the server to your client",
description: description:
"Drop the config into Cursor's mcp.json, run claude mcp add for Claude Code, or paste it into Claude Desktop. Point it at the cloud or your own self-hosted instance.", "Point your client at https://mcp.surfsense.com/mcp with your key in an Authorization header — the hosted config for Cursor, Claude Code, and others is one paste. Prefer stdio? Switch to Self-host and run it against your own backend.",
}, },
{ {
icon: Server, icon: Server,
@ -135,7 +132,7 @@ const FAQ: FaqItem[] = [
{ {
question: "Which MCP clients does it work with?", question: "Which MCP clients does it work with?",
answer: answer:
"Any MCP client that supports stdio servers. Claude Code, Codex, OpenCode, Cursor, Claude Desktop, VS Code, Windsurf, and Gemini CLI are documented with copy-paste configs on this page, and the same command works in custom agent harnesses built on the MCP SDK.", "Any MCP client that speaks remote (streamable HTTP) or stdio. Claude Code, Codex, OpenCode, Cursor, Claude Desktop, VS Code, Windsurf, and Gemini CLI all have copy-paste configs on this page — Hosted for the one-paste https://mcp.surfsense.com/mcp endpoint, or Self-host for stdio against your own backend.",
}, },
{ {
question: "How is usage billed?", question: "How is usage billed?",
@ -278,9 +275,9 @@ export default function McpServerPage() {
Step-by-step setup for every agent Step-by-step setup for every agent
</h2> </h2>
<p className="mt-3 max-w-2xl text-muted-foreground leading-relaxed"> <p className="mt-3 max-w-2xl text-muted-foreground leading-relaxed">
Pick your client, follow its two steps, and paste the config. Replace the placeholder Pick your client, choose <strong>Hosted</strong> or <strong>Self-host</strong>, and
path with your surfsense_mcp checkout and the key with one from API Playground → API paste the config. Replace the key with one from API Playground → API Keys — or grab a
Keys — or grab a pre-filled config from the playground itself. pre-filled config from the playground itself.
</p> </p>
</Reveal> </Reveal>
<Reveal> <Reveal>

2
surfsense_web/components/connectors-marketing/api-mcp-tabs.tsx
View file

@ -206,7 +206,7 @@ function buildMcp({ mcpTool }: ApiSample): string {
const config = { const config = {
mcpServers: { mcpServers: {
surfsense: { surfsense: {
url: "https://mcp.surfsense.com", url: "https://mcp.surfsense.com/mcp",
headers: { Authorization: "Bearer ${SURFSENSE_API_KEY}" }, headers: { Authorization: "Bearer ${SURFSENSE_API_KEY}" },
}, },
}, },

102
surfsense_web/components/mcp/agent-setup-tabs.tsx
View file

@ -9,6 +9,8 @@ import {
DEFAULT_SERVER_DIR, DEFAULT_SERVER_DIR,
MCP_CLIENTS, MCP_CLIENTS,
type McpSnippetOptions, type McpSnippetOptions,
type McpTransport,
REMOTE_URL,
} from "@/lib/mcp/clients"; } from "@/lib/mcp/clients";
function CopyButton({ text }: { text: string }) { function CopyButton({ text }: { text: string }) {
@ -38,48 +40,82 @@ function CopyButton({ text }: { text: string }) {
); );
} }
const TRANSPORTS: { id: McpTransport; label: string; hint: string }[] = [
{ id: "remote", label: "Hosted", hint: "mcp.surfsense.com — nothing to install" },
{ id: "stdio", label: "Self-host", hint: "run the server against your own backend" },
];
/** /**
* Per-agent MCP setup instructions as tabs: pick a client, follow its steps, * Per-agent MCP setup instructions as tabs: pick a client, then Hosted or
* copy its exact config. Used on the /mcp-server marketing page and in the * Self-host, and copy its exact config. Used on the /mcp-server marketing page
* API playground; `options` fills in real values where the caller has them. * and in the API playground; `options` fills in real values where the caller
* has them.
*/ */
export function AgentSetupTabs({ options }: { options?: Partial<McpSnippetOptions> }) { export function AgentSetupTabs({ options }: { options?: Partial<McpSnippetOptions> }) {
const [transport, setTransport] = useState<McpTransport>("remote");
const resolved: McpSnippetOptions = { const resolved: McpSnippetOptions = {
baseUrl: options?.baseUrl || "https://api.surfsense.com", remoteUrl: options?.remoteUrl || REMOTE_URL,
apiKey: options?.apiKey || API_KEY_PLACEHOLDER, apiKey: options?.apiKey || API_KEY_PLACEHOLDER,
baseUrl: options?.baseUrl || "https://api.surfsense.com",
serverDir: options?.serverDir || DEFAULT_SERVER_DIR, serverDir: options?.serverDir || DEFAULT_SERVER_DIR,
}; };
const active = TRANSPORTS.find((t) => t.id === transport) ?? TRANSPORTS[0];
return ( return (
<Tabs defaultValue={MCP_CLIENTS[0].id} className="w-full"> <div className="space-y-4">
<TabsList className="flex h-auto flex-wrap justify-start gap-1"> <div className="flex flex-wrap items-center gap-3">
{MCP_CLIENTS.map((client) => ( <div className="inline-flex rounded-lg border bg-muted/40 p-0.5">
<TabsTrigger key={client.id} value={client.id}> {TRANSPORTS.map((t) => (
{client.label} <Button
</TabsTrigger> key={t.id}
))} variant={t.id === transport ? "secondary" : "ghost"}
</TabsList> size="sm"
{MCP_CLIENTS.map((client) => { className="h-7 px-3 text-xs"
const config = client.buildConfig(resolved); onClick={() => setTransport(t.id)}
return ( aria-pressed={t.id === transport}
<TabsContent key={client.id} value={client.id} className="space-y-3"> >
<ol className="list-decimal space-y-1 pl-5 text-sm leading-relaxed text-muted-foreground"> {t.label}
{client.steps.map((step) => ( </Button>
<li key={step}>{step}</li> ))}
))} </div>
</ol> <span className="text-xs text-muted-foreground">{active.hint}</span>
<div> </div>
<p className="mb-1.5 font-mono text-xs text-muted-foreground">{client.configFile}</p>
<div className="relative"> <Tabs defaultValue={MCP_CLIENTS[0].id} className="w-full">
<CopyButton text={config} /> <TabsList className="flex h-auto flex-wrap justify-start gap-1">
<pre className="overflow-x-auto rounded-lg border bg-muted/50 p-4 font-mono text-xs leading-relaxed"> {MCP_CLIENTS.map((client) => (
<code>{config}</code> <TabsTrigger key={client.id} value={client.id}>
</pre> {client.label}
</TabsTrigger>
))}
</TabsList>
{MCP_CLIENTS.map((client) => {
const snippet = client[transport];
const config = snippet.build(resolved);
return (
<TabsContent key={client.id} value={client.id} className="space-y-3">
<ol className="list-decimal space-y-1 pl-5 text-sm leading-relaxed text-muted-foreground">
{snippet.steps.map((step) => (
<li key={step}>{step}</li>
))}
</ol>
<div>
<p className="mb-1.5 font-mono text-xs text-muted-foreground">
{snippet.configFile}
</p>
<div className="relative">
<CopyButton text={config} />
<pre className="overflow-x-auto rounded-lg border bg-muted/50 p-4 font-mono text-xs leading-relaxed">
<code>{config}</code>
</pre>
</div>
</div> </div>
</div> </TabsContent>
</TabsContent> );
); })}
})} </Tabs>
</Tabs> </div>
); );
} }

379
surfsense_web/lib/mcp/clients.ts
View file

@ -1,42 +1,75 @@
/** /**
* MCP client setup catalog: one entry per popular agent, with the exact * MCP client setup catalog: one entry per popular agent, each with a hosted
* config file, steps, and snippet needed to connect the SurfSense MCP server. * (remote) snippet and a self-host (stdio) snippet, plus the exact config file
* Shared by the marketing /mcp-server page and the API playground so the * and steps. Shared by the marketing /mcp-server page and the API playground so
* instructions can never drift apart. * the instructions can never drift apart.
*
* Remote snippets point at the hosted server and pass the key as a Bearer token;
* every client's exact remote field is verified against its own docs (Windsurf
* uses `serverUrl`, Gemini CLI `httpUrl`, VS Code needs `type: "http"`, OpenCode
* `type: "remote"` + `oauth: false`, Codex needs the rmcp flag, and Claude
* Desktop has no config-file remote support so it uses the `mcp-remote` bridge).
*/ */
export type McpTransport = "remote" | "stdio";
export interface McpSnippetOptions { export interface McpSnippetOptions {
/** SurfSense backend URL the server should call. */ /** Hosted MCP endpoint (Bearer-authenticated). */
baseUrl: string; remoteUrl: string;
/** API key value or placeholder to show in the snippet. */ /** API key value or placeholder to show in the snippet. */
apiKey: string; apiKey: string;
/** Absolute path to the surfsense_mcp directory. */ /** SurfSense backend URL a self-hosted server should call. */
baseUrl: string;
/** Absolute path to the surfsense_mcp directory (self-host). */
serverDir: string; serverDir: string;
} }
export interface McpSnippet {
/** Where the snippet goes: a file path or "Terminal". */
configFile: string;
language: "json" | "toml" | "bash";
steps: string[];
build: (options: McpSnippetOptions) => string;
}
export interface McpClient { export interface McpClient {
id: string; id: string;
label: string; label: string;
/** Where the snippet goes: a file path or "Terminal". */ remote: McpSnippet;
configFile: string; stdio: McpSnippet;
language: "json" | "toml" | "bash";
steps: string[];
buildConfig: (options: McpSnippetOptions) => string;
} }
export const REMOTE_URL = "https://mcp.surfsense.com/mcp";
export const DEFAULT_SERVER_DIR = "/path/to/SurfSense/surfsense_mcp"; export const DEFAULT_SERVER_DIR = "/path/to/SurfSense/surfsense_mcp";
export const API_KEY_PLACEHOLDER = "ss_pat_your_key_here"; export const API_KEY_PLACEHOLDER = "ss_pat_your_key_here";
function serverArgs(serverDir: string): string[] {
return ["run", "--directory", serverDir, "python", "-m", "surfsense_mcp"];
}
function json(value: unknown): string { function json(value: unknown): string {
return JSON.stringify(value, null, 2); return JSON.stringify(value, null, 2);
} }
/** The `mcpServers` JSON shape shared by Cursor, Claude Desktop, Windsurf, and Gemini CLI. */ function bearer(apiKey: string): string {
function standardJson({ baseUrl, apiKey, serverDir }: McpSnippetOptions): string { return `Bearer ${apiKey}`;
}
function serverArgs(serverDir: string): string[] {
return ["run", "--directory", serverDir, "python", "-m", "surfsense_mcp"];
}
/** The `mcpServers` remote shape shared by Cursor, Windsurf, and Gemini CLI. */
function remoteMcpServers(urlField: "url" | "serverUrl" | "httpUrl") {
return ({ remoteUrl, apiKey }: McpSnippetOptions): string =>
json({
mcpServers: {
surfsense: {
[urlField]: remoteUrl,
headers: { Authorization: bearer(apiKey) },
},
},
});
}
/** The `mcpServers` stdio shape shared by Cursor, Claude Desktop, Windsurf, Gemini CLI. */
function stdioMcpServers({ baseUrl, apiKey, serverDir }: McpSnippetOptions): string {
return json({ return json({
mcpServers: { mcpServers: {
surfsense: { surfsense: {
@ -52,125 +85,255 @@ export const MCP_CLIENTS: McpClient[] = [
{ {
id: "claude-code", id: "claude-code",
label: "Claude Code", label: "Claude Code",
configFile: "Terminal", remote: {
language: "bash", configFile: "Terminal",
steps: [ language: "bash",
"Run this command in a terminal (any directory).", steps: [
"Start Claude Code and run /mcp — surfsense should be listed as connected.", "Run this command in a terminal (any directory).",
], "Start Claude Code and run /mcp — surfsense should be listed as connected.",
buildConfig: ({ baseUrl, apiKey, serverDir }) => ],
[ build: ({ remoteUrl, apiKey }) =>
"claude mcp add surfsense \\", [
` -e SURFSENSE_BASE_URL=${baseUrl} \\`, `claude mcp add --transport http surfsense ${remoteUrl} \\`,
` -e SURFSENSE_API_KEY=${apiKey} \\`, ` --header "Authorization: ${bearer(apiKey)}"`,
` -- uv run --directory ${serverDir} python -m surfsense_mcp`, ].join("\n"),
].join("\n"), },
stdio: {
configFile: "Terminal",
language: "bash",
steps: [
"Run this command in a terminal (any directory).",
"Start Claude Code and run /mcp — surfsense should be listed as connected.",
],
build: ({ baseUrl, apiKey, serverDir }) =>
[
"claude mcp add surfsense \\",
` -e SURFSENSE_BASE_URL=${baseUrl} \\`,
` -e SURFSENSE_API_KEY=${apiKey} \\`,
` -- uv run --directory ${serverDir} python -m surfsense_mcp`,
].join("\n"),
},
}, },
{ {
id: "codex", id: "codex",
label: "Codex", label: "Codex",
configFile: "~/.codex/config.toml", remote: {
language: "toml", configFile: "~/.codex/config.toml",
steps: [ language: "toml",
"Add this to ~/.codex/config.toml (or run `codex mcp add surfsense -- uv run --directory <dir> python -m surfsense_mcp`).", steps: [
"Restart Codex; `codex mcp list` should show surfsense.", "Add this to ~/.codex/config.toml. The rmcp flag must sit above every [mcp_servers.*] table.",
], "Restart Codex; `codex mcp list` should show surfsense.",
buildConfig: ({ baseUrl, apiKey, serverDir }) => ],
[ build: ({ remoteUrl, apiKey }) =>
"[mcp_servers.surfsense]", [
'command = "uv"', "experimental_use_rmcp_client = true",
`args = ${JSON.stringify(serverArgs(serverDir))}`, "",
"", "[mcp_servers.surfsense]",
"[mcp_servers.surfsense.env]", `url = "${remoteUrl}"`,
`SURFSENSE_BASE_URL = "${baseUrl}"`, "",
`SURFSENSE_API_KEY = "${apiKey}"`, "[mcp_servers.surfsense.http_headers]",
].join("\n"), `Authorization = "${bearer(apiKey)}"`,
].join("\n"),
},
stdio: {
configFile: "~/.codex/config.toml",
language: "toml",
steps: [
"Add this to ~/.codex/config.toml (or run `codex mcp add surfsense -- uv run --directory <dir> python -m surfsense_mcp`).",
"Restart Codex; `codex mcp list` should show surfsense.",
],
build: ({ baseUrl, apiKey, serverDir }) =>
[
"[mcp_servers.surfsense]",
'command = "uv"',
`args = ${JSON.stringify(serverArgs(serverDir))}`,
"",
"[mcp_servers.surfsense.env]",
`SURFSENSE_BASE_URL = "${baseUrl}"`,
`SURFSENSE_API_KEY = "${apiKey}"`,
].join("\n"),
},
}, },
{ {
id: "opencode", id: "opencode",
label: "OpenCode", label: "OpenCode",
configFile: "opencode.json", remote: {
language: "json", configFile: "opencode.json",
steps: [ language: "json",
"Add this to opencode.json in your project root (or ~/.config/opencode/opencode.json for all projects).", steps: [
"Note OpenCode's format: the key is `mcp`, the command is one array, and env vars go under `environment`.", "Add this to opencode.json in your project root (or ~/.config/opencode/opencode.json for all projects).",
], "`oauth: false` tells OpenCode to use the Bearer key instead of starting an OAuth flow.",
buildConfig: ({ baseUrl, apiKey, serverDir }) => ],
json({ build: ({ remoteUrl, apiKey }) =>
$schema: "https://opencode.ai/config.json", json({
mcp: { $schema: "https://opencode.ai/config.json",
surfsense: { mcp: {
type: "local", surfsense: {
command: ["uv", ...serverArgs(serverDir)], type: "remote",
enabled: true, url: remoteUrl,
environment: { SURFSENSE_BASE_URL: baseUrl, SURFSENSE_API_KEY: apiKey }, enabled: true,
oauth: false,
headers: { Authorization: bearer(apiKey) },
},
}, },
}, }),
}), },
stdio: {
configFile: "opencode.json",
language: "json",
steps: [
"Add this to opencode.json in your project root (or ~/.config/opencode/opencode.json for all projects).",
"Note OpenCode's format: the key is `mcp`, the command is one array, and env vars go under `environment`.",
],
build: ({ baseUrl, apiKey, serverDir }) =>
json({
$schema: "https://opencode.ai/config.json",
mcp: {
surfsense: {
type: "local",
command: ["uv", ...serverArgs(serverDir)],
enabled: true,
environment: { SURFSENSE_BASE_URL: baseUrl, SURFSENSE_API_KEY: apiKey },
},
},
}),
},
}, },
{ {
id: "cursor", id: "cursor",
label: "Cursor", label: "Cursor",
configFile: "~/.cursor/mcp.json", remote: {
language: "json", configFile: "~/.cursor/mcp.json",
steps: [ language: "json",
"Add this to ~/.cursor/mcp.json (global, keeps the key out of your repo) or a project's .cursor/mcp.json.", steps: [
"Refresh the server in Cursor Settings → MCP; its 18 tools should appear.", "Add this to ~/.cursor/mcp.json (global, keeps the key out of your repo) or a project's .cursor/mcp.json.",
], "Refresh the server in Cursor Settings → MCP; its 18 tools should appear.",
buildConfig: standardJson, ],
build: remoteMcpServers("url"),
},
stdio: {
configFile: "~/.cursor/mcp.json",
language: "json",
steps: [
"Add this to ~/.cursor/mcp.json (global, keeps the key out of your repo) or a project's .cursor/mcp.json.",
"Refresh the server in Cursor Settings → MCP; its 18 tools should appear.",
],
build: stdioMcpServers,
},
}, },
{ {
id: "claude-desktop", id: "claude-desktop",
label: "Claude Desktop", label: "Claude Desktop",
configFile: "claude_desktop_config.json", remote: {
language: "json", configFile: "claude_desktop_config.json",
steps: [ language: "json",
"Open Settings → Developer → Edit Config to reach claude_desktop_config.json and add this.", steps: [
"Restart Claude Desktop; surfsense appears under the tools icon.", "Claude Desktop can't take a remote URL directly, so this uses the mcp-remote bridge (needs Node 18+).",
], "Open Settings → Developer → Edit Config, add this, and restart Claude Desktop.",
buildConfig: standardJson, ],
build: ({ remoteUrl, apiKey }) =>
json({
mcpServers: {
surfsense: {
command: "npx",
args: ["-y", "mcp-remote", remoteUrl, "--header", `Authorization: ${bearer(apiKey)}`],
},
},
}),
},
stdio: {
configFile: "claude_desktop_config.json",
language: "json",
steps: [
"Open Settings → Developer → Edit Config to reach claude_desktop_config.json and add this.",
"Restart Claude Desktop; surfsense appears under the tools icon.",
],
build: stdioMcpServers,
},
}, },
{ {
id: "vscode", id: "vscode",
label: "VS Code", label: "VS Code",
configFile: ".vscode/mcp.json", remote: {
language: "json", configFile: ".vscode/mcp.json",
steps: [ language: "json",
"Add this to .vscode/mcp.json in your workspace (or run the MCP: Add Server command).", steps: [
"Open Copilot Chat in agent mode and click the tools icon to confirm surfsense is loaded.", "Add this to .vscode/mcp.json in your workspace (or run the MCP: Add Server command).",
], "VS Code requires an explicit `type` field — `http` for the hosted server.",
buildConfig: ({ baseUrl, apiKey, serverDir }) => ],
json({ build: ({ remoteUrl, apiKey }) =>
servers: { json({
surfsense: { servers: {
type: "stdio", surfsense: {
command: "uv", type: "http",
args: serverArgs(serverDir), url: remoteUrl,
env: { SURFSENSE_BASE_URL: baseUrl, SURFSENSE_API_KEY: apiKey }, headers: { Authorization: bearer(apiKey) },
},
}, },
}, }),
}), },
stdio: {
configFile: ".vscode/mcp.json",
language: "json",
steps: [
"Add this to .vscode/mcp.json in your workspace (or run the MCP: Add Server command).",
"Open Copilot Chat in agent mode and click the tools icon to confirm surfsense is loaded.",
],
build: ({ baseUrl, apiKey, serverDir }) =>
json({
servers: {
surfsense: {
type: "stdio",
command: "uv",
args: serverArgs(serverDir),
env: { SURFSENSE_BASE_URL: baseUrl, SURFSENSE_API_KEY: apiKey },
},
},
}),
},
}, },
{ {
id: "windsurf", id: "windsurf",
label: "Windsurf", label: "Windsurf",
configFile: "~/.codeium/windsurf/mcp_config.json", remote: {
language: "json", configFile: "~/.codeium/windsurf/mcp_config.json",
steps: [ language: "json",
"Add this to ~/.codeium/windsurf/mcp_config.json (or Windsurf Settings → Cascade → MCP Servers).", steps: [
"Press the refresh button in the MCP panel to pick up the server.", "Add this to ~/.codeium/windsurf/mcp_config.json (or Windsurf Settings → Cascade → MCP Servers).",
], "Windsurf uses `serverUrl` (not `url`) for remote servers; press refresh in the MCP panel.",
buildConfig: standardJson, ],
build: remoteMcpServers("serverUrl"),
},
stdio: {
configFile: "~/.codeium/windsurf/mcp_config.json",
language: "json",
steps: [
"Add this to ~/.codeium/windsurf/mcp_config.json (or Windsurf Settings → Cascade → MCP Servers).",
"Press the refresh button in the MCP panel to pick up the server.",
],
build: stdioMcpServers,
},
}, },
{ {
id: "gemini-cli", id: "gemini-cli",
label: "Gemini CLI", label: "Gemini CLI",
configFile: "~/.gemini/settings.json", remote: {
language: "json", configFile: "~/.gemini/settings.json",
steps: [ language: "json",
"Add this to ~/.gemini/settings.json (or .gemini/settings.json in a project).", steps: [
"Run /mcp inside Gemini CLI to confirm the surfsense server and its tools.", "Add this to ~/.gemini/settings.json (or .gemini/settings.json in a project).",
], "Gemini CLI uses `httpUrl` for streamable-HTTP servers; run /mcp to confirm surfsense.",
buildConfig: standardJson, ],
build: remoteMcpServers("httpUrl"),
},
stdio: {
configFile: "~/.gemini/settings.json",
language: "json",
steps: [
"Add this to ~/.gemini/settings.json (or .gemini/settings.json in a project).",
"Run /mcp inside Gemini CLI to confirm the surfsense server and its tools.",
],
build: stdioMcpServers,
},
}, },
]; ];