Skip to content

Add external MCP connectors to the chat sidebar, off by default - #129

Draft
jjgao wants to merge 4 commits into
patient-summaryfrom
chat-connectors
Draft

jjgao wants to merge 4 commits into
patient-summaryfrom
chat-connectors

Conversation

@jjgao

@jjgao jjgao commented Nov 3, 2026

Copy link
Copy Markdown
Member

Stacked on #127 (which is on #125, on #123). Merge in that order; GitHub retargets each in turn.

Summary

The sidebar can use external MCP servers ("connectors") the reader switches on from a plug menu. Defaults: OpenEvidence and cBioPortal MCP; a deployment sets its own with CHAT_CONNECTORS ([] offers none). Everything is off until the reader switches it on. Issue #128.

  • Approve every call. Connector tools are namespaced <id>__<tool> and wait for the reader. The card shows the server and the exact arguments, with Approve and Deny. There is no "always allow". Approval requests are signed (CHAT_APPROVAL_SECRET), so a browser cannot forge one. A denied call is not retried; the model is told so, and told never to put an identifier in a call.
  • The registry holds the addresses. A request names a connector by id, so it cannot point the route anywhere. A malformed CHAT_CONNECTORS is an error, not a quiet omission.
  • Credentials stay in the browser (localStorage) and are sent per request. The server stores, logs, caches and returns none.
  • A connector that fails never fails the chat. The route reports it in an x-chat-connectors header and leaves it out of that turn. The panel shows why.
  • Three kinds of sign-in, because the real servers needed them:
    • oauth (cBioPortal MCP): standard MCP OAuth with dynamic client registration and PKCE. The flow's state rides in a 10-minute httpOnly cookie, the token goes to the browser, and the server forgets it.
    • token (OpenEvidence): a pasted API token in a named header. Its tool list is open, but a call returns "send yours in the x-api-token header".
    • none.
  • The rule change is written down. docs/ARCHITECTURE.md and CLAUDE.md state the one exception to "the route holds no tool", and DATA-BOUNDARY.md says what a connector sends and that the app cannot check it.

Found along the way

  • mcp.cbioportal.org only takes confidential clients and requires both authorization_code and refresh_token in registration. Registration now follows what each server advertises. It accepted a localhost redirect.
  • OpenEvidence holds the server-push GET stream open and answers nothing else while it is, so listing its tools timed out. Connector use is one request and one answer per turn, so the client declines that stream (a 405). A test fails if a GET ever reaches the server.

Verification

  • tsc, eslint, knip and 42 new unit tests pass: the registry, the browser state, a stub MCP server for the tools, and a stub authorization server for the whole OAuth flow, including a confidential-client server.
  • In Chrome with the real model: off by default; the OAuth connector cannot be switched on until signed in; the approval card shows the server and exact arguments; Deny stopped the call and the model did not retry; Approve ran it; a deliberately fake token reached OpenEvidence's server (its reply changed from "no API key" to "Invalid token").
  • GET /api/chat/connectors/oauth/start?id=cbioportal against the real server registered a client and built the authorization URL with PKCE and state.

Not done, and needs a person

  • A successful OpenEvidence answer: it needs a real API token.
  • The full cBioPortal sign-in: it needs someone in the browser to approve at mcp.cbioportal.org (open the plug menu, click Connect).
  • An e2e test (the repo has no chat e2e yet).
  • Every Connect click registers a new client on the server, since nothing is stored on ours. A refresh token is not kept, so an expired sign-in means Connect again.
  • 6 view-snapshot tests fail, with and without this change (checked on the base commit).

🤖 Generated with Claude Code

@vercel

vercel Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
cbiolab-genie Ready Ready Preview Nov 19, 2026 11:20pm UTC
cbiolab-new Ready Ready Preview Nov 19, 2026 11:20pm UTC
cohort-lab Ready Ready Preview Nov 19, 2026 11:20pm UTC

Request Review

jjgao and others added 2 commits November 19, 2026 13:46
The sidebar can use external MCP servers ("connectors") the reader switches on in a plug menu:
OpenEvidence and cBioPortal MCP by default, or what CHAT_CONNECTORS names. Issue #128.

How it holds to the project's rules (docs/ARCHITECTURE.md now states the one exception to "the route
holds no tool"): a request names a connector by id and the address always comes from the deployment's
registry; every connector tool is namespaced <id>__<tool> and waits for the reader's approval, shown with
the server and the exact arguments (no "always allow"); approval requests are signed
(CHAT_APPROVAL_SECRET) so a browser cannot forge one; the model is told never to put an identifier in a
call. A reader's credentials live in their browser (localStorage) and are sent per request; the server
stores, logs and returns none. A connector that cannot be reached is reported in a header and left out of
the turn, never failing the chat.

Three kinds of sign-in, because the real servers needed them: "oauth" (standard MCP OAuth with dynamic
client registration and PKCE, finished on /api/chat/connectors/oauth/callback; the flow's state rides in
a ten-minute httpOnly cookie, the token goes to the browser and is forgotten), "token" (a pasted API
token in a named header: OpenEvidence's tools/list is open but its calls need x-api-token), and "none".
Registration follows what each server advertises: mcp.cbioportal.org only takes confidential clients and
both grants.

The MCP client declines the server-push GET stream: OpenEvidence held it open and answered nothing else,
so listing its tools timed out. Connector use is one request and one answer per turn, so none is needed.

Verified: tsc, eslint, knip and 42 new unit tests pass (registry, browser state, a stub MCP server for the
tools, a stub authorization server for the whole OAuth flow including a confidential-client server). In
Chrome with the real model: connectors are off by default; the OAuth one cannot be switched on until
signed in; the approval card shows the server and exact arguments; Deny stops the call and the model does
not retry; Approve runs it; a fake token reached OpenEvidence's server (its reply changed to "Invalid
token"). The OAuth start endpoint against mcp.cbioportal.org registered a client and built the
authorization URL. Not done: a successful OpenEvidence answer (needs a real token), the full cBioPortal
sign-in (needs the reader in the browser), and an e2e test. 6 view-snapshot tests fail with and without
this change.

Refs #128

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012XdQQNTxj4XzvBoLxynDRu
…or status

A connector stored as "on" that had no token (OpenEvidence was on from before it needed one) showed
as off in the Connectors panel but was still named in every chat request, so each message came back
"no API token: add yours". After the reader added the token, that last-message error stayed on screen,
including across closing and reopening the sidebar.

requestEntries now names only connectors that are on AND may be (the same rule the panel uses), and any
change to a connector's switch or token clears its remembered status.

Verified: tsc, eslint and the 18 connector-state tests pass. In Chrome, from a leftover "on" with no
token: a message names no connectors and shows no error; after pasting a token, closing and reopening,
and switching on, the request names the connector with its token, the server reports it reached with
1 tool, and the approval card appears.

Refs #128

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012XdQQNTxj4XzvBoLxynDRu
Check the parsed URL origin before accepting a return path so browser tab normalization cannot redirect outside the app. Preserve valid local paths, queries and fragments.

Regression coverage checks the sanitizer, flow cookie and success and failure callback pages. All 49 connector tests, targeted ESLint and TypeScript checks pass.
Collect every tools/list page before applying the connector allow-list and tool limit. Tools on later pages are now available and the limit covers the complete offered tool set.

Regression coverage uses a paginated MCP server and checks later-page execution, allow-list selection and the cross-page limit. All 49 connector tests, targeted ESLint and TypeScript checks pass.

This branch was successfully deployed

1 active deployment
Preview – cohort-lab — 631eae90 Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant