mcp-server

The MCP server — DeepResearch as a tool (POST /mcp)

What this is and why it exists

src/mcp.js exposes the whole deep-research pipeline as an MCP server. Its headline tool is deep_research — question in, cited/validated/ source-diverse answer out — callable by any MCP client (Claude, Cursor, an agent SDK). Alongside it the server re-exposes DistillSDK's four manifest tools (sdk_list_modules, sdk_show_module, sdk_plan, sdk_validate, via SDK_MCP_TOOLS) so an external agent can plan against the SDK without shelling into the execution sandbox. Five tools total; the pipeline one is the reason the server exists. This is the ONE place the pipeline points outward: the architecture roadmap (docs/ARCHITECTURE-ROADMAP.md §3) argues MCP belongs on the outbound edge (DeepResearch as a tool other agents compose with), NOT as internal plumbing — internal tool selection stays deterministic and in the Worker's hands (invariant 1). So this server adds a transport over the existing pipeline; it does not hand control flow to a model.

Transport is modern Streamable HTTP: JSON-RPC 2.0 over a single POST to /mcp. The protocol surface is tiny, so it's hand-rolled — no dependency (same minimal-deps stance as the rest of the repo). It implements exactly the methods a minimal server needs:

• initialize → initializeResult() (reports PROTOCOL_VERSION, SERVER_INFO, capabilities: { tools: {} })
• tools/list → toolsListResult(config) (ALL_MCP_TOOLS = DEEP_RESEARCH_TOOL
  • SDK_MCP_TOOLS, filtered by the account's exposure config)
• tools/call → handleToolCall() → runDeepResearch()
• notifications/initialized → no-op ack (a notification has no id, so it returns no response body)

Getting in: the two auth paths and the mcp. host

The route is wired in src/index.js twice, deliberately, and both sides ask the same isMcpEndpoint(url, method) predicate (src/mcp-config.js) so they can never disagree about what the endpoint is:

• Below the identity gate (routeApi) — a signed-in session or the break-glass Basic header, exactly as before.
• Above it — an MCP key (src/mcp-key.js), the bearer credential an external client carries because it has no cookie jar. src/mcp-api.js's resolveMcpKeyIdentity resolves it, and the router consults that function for this endpoint and nothing else. Its three outcomes matter: null (no key — fall through to the gate), {identity, config}, and {error} — a key that was PRESENTED and refused must come back as a 401 JSON-RPC error, never the sign-in HTML, or the client reports a transport failure and its user hunts the wrong problem.

An MCP key is never a login, and that is structural, not a promise: identify() reads a Basic header and the dr_session cookie, so an mck1. bearer cannot satisfy it in any position (test-pinned in src/mcp-key.test.js, alongside the cross-family forgery matrix). It is also deliberately not the Se/rver token — that family's closed upstream-only vocabulary exists to protect Se/cure, whereas a key acts for a Se/rver account inside the trust boundary. One key per account; minting rotates, revoking rewrites the stored jti the token must match. The token is returned once at mint and never stored (only jti + a six-character hint), so "I lost it" is answered by minting again, not by reading it back.

Production also serves the endpoint on mcp.deepresearch.se (a custom_domain route in wrangler.toml, provisioned through the Workers custom-domains API — PUT /accounts/<id>/workers/domains with {environment, hostname, service, zone_id}, which creates the DNS record and the certificate; the host answered within ~20 s).

Declare it in wrangler.toml or lose it. Observed 2026-07-26: the domain was created by API, an unrelated merge to main auto-deployed from a wrangler.toml that did not list it, and the deploy removed the domain — the host went unreachable until it was re-created. The API call and the config entry are not alternatives; a domain missing from routes does not survive the next deploy.

Same Worker, same code path. On that host the BARE ORIGIN answers too — clients disagree about whether the configured URL includes the path, and a wrong-URL 404 is the commonest way an MCP setup fails — and a GET serves the public setup page public/connect/ (allowlisted in src/assets.js). src/canonical.js leaves the host alone: it only rewrites http → https and strips www..

What is exposed: per-account configuration

src/mcp-config.js is a pure leaf owning WHAT the surface offers, edited in Settings → MCP server (public/js/account-mcp.js, one level below the gear icon's Settings, the same treatment as LLM sharing) through GET/PUT /api/mcp/config and POST/DELETE /api/mcp/key.

• MCP_TOOL_CATALOG mirrors the served tool list exactly — src/mcp-config.test.js fails the build when they drift, so a tool cannot ship on this surface without a switch to turn it off. Adding a tool means adding a catalog entry in the same change.
• The config is read at CALL time and lives on the ACCOUNT, not in the token: narrowing takes effect on the next call for every outstanding key, with nothing to re-issue. The config endpoints are behind the identity gate, so a key holder can see the effects and never change them.
• tools/list is filtered by it and tools/call ENFORCES it (a client that cached an older listing still cannot reach a switched-off tool — reported as unknown-tool, since from the caller's side it does not exist).
• resolveResearchArgs reconciles a deep_research call's arguments with the account's defaults and override policy before runDeepResearch sees them. Asymmetry worth keeping: a caller may always DECLINE web search, and can never switch it back on.

Defaults are "everything exposed, site defaults, no key" — byte-for-byte the behaviour that existed before the configuration did, so an account that never opens the screen sees no change.

The load-bearing file-layout rule

src/mcp.test.js must unit-test the protocol without loading the pipeline. So the module is split by import weight:

• Top of file — PURE, statically importable: parseJsonRpc, the envelope builders (jsonRpcResult, jsonRpcError, toolResult), initializeResult, toolsListResult, the RPC error-code constants, and DEEP_RESEARCH_TOOL (the tool schema). The only static imports are leaf modules: http.js (jsonResponse), model-routing.js (resolveJsonModel) and mcp-config.js (the exposure seam) — none of which pulls the pipeline graph in.
• Inside tools/call — DYNAMIC import(): the pipeline and its deps (pipeline.js, berget.js, budget.js, validation.js, providers.js, config.js, quota.js, billing.js) are imported inside runDeepResearch, so importing the module (as the test does) never drags in pipeline.js/berget.js/etc.

Keep this rule. New pure protocol logic goes at the top; anything that needs the pipeline stays behind the dynamic import. mcp.test.js asserts the module loads without the pipeline — breaking the split fails the suite.

How a tool call runs (runDeepResearch)

tools/call for deep_research mirrors src/chat.js's per-request setup without editing chat.js — it deliberately re-does the same steps so a change to the chat path doesn't silently change MCP:

1. Guard BERGET_API_TOKEN; build a single-turn [{role:"user", content:question}] conversation and validateMessages it.
2. Resolve the model against the catalog (fail-soft to default if the catalog is unreachable), honoring args.model then the admin default. resolveJsonModel(catalog, model, DEFAULT_MODEL) picks the fixed JSON planning model — the SAME split-routing decision chat.js uses (shared via model-routing.js, invariant 3).
3. Budget: clampBudget(args.time_budget_s ?? 120) then Math.min(…, config.max_time_budget_s) — chat.js's exact two-step clamp.
4. Quota gate — the same one /api/chat enforces. Admins (isSecretAdmin / role === "admin") are never blocked; every regular user is checked against their four-window budget BEFORE any spend. This is load-bearing: without it, /mcp would be an unmetered bypass of the quota /api/chat applies — each call runs the full pipeline for real Berget + Exa money.
5. Run runPipeline, collect the streamed answer into one string, append the Sources list (withSources).
6. Record usage (recordUsage) with the split-billing totals (summarizeSpend / exaCost from the shared billing.js) so MCP spend shows up in the usage bars and admin cost totals just like chat spend.

The tool's input schema (DEEP_RESEARCH_TOOL.inputSchema): required question; optional time_budget_s (default 120, clamped 15–600), model (Berget id; JSON phases stay on the reliable model regardless), web_search (default true; false = answer directly, no search provider contacted).

Adding or changing a tool

• Change the deep_research schema: edit DEEP_RESEARCH_TOOL at the top, read the new arg in runDeepResearch with a fail-soft default, and update the tools/list assertion in mcp.test.js. Keep descriptions written for an LLM caller (they're what the client model sees).
• Add ANOTHER tool: add its schema constant at the top, put it in ALL_MCP_TOOLS, add its MCP_TOOL_CATALOG entry in src/mcp-config.js in the same change (the mirror test fails otherwise — and an account needs a way to switch it off), and branch on parsed.params.name in handleToolCall — which already dispatches the sdk_* family by SDK_TOOL_NAMES membership before falling through to deep_research; anything matching neither is method-not-found. Any heavy work its handler needs stays behind a dynamic import. Ask whether

Content truncated.