[Tracking] MCP connector: reach docs.plus from Claude and ChatGPT #230

Goal

A person inside Claude or ChatGPT connects to docs.plus. They sign in as themselves and work with their own documents and heading chats.

Status

Live since 2026-09-28 at https://prodback.docs.plus/api/mcp. The server is stateless and builds one MCP server per request. It runs on @modelcontextprotocol/server 2.0.0, pinned exactly.

Nine tools: find_documents, get_outline, read_document, create_document, append_to_document, replace_section, list_chat_rooms, read_chat_thread and post_chat_message.

Guide: docs/mcp/README.md. Reference: docs/mcp/reference.md and apps/hocuspocus.server/API.md §MCP connector.

Done

Next

1. Test the MCP connector in three AI apps, then finish its connect guide #357: test the connector in claude.ai, ChatGPT and Claude Code, then finish the guide.
2. Build work continues in [Tracking] Editor next steps: Slash hardening, heading links, and MCP reads #328. Connected-app rows there: Refuse a connected-app rewrite of a section that holds media #329, Store links from Markdown import and connected-app writes on the hyperlink mark #335, Mark MCP chat posts with a fixed connected-app metadata key #336, Tell self-hosters to set APP_URL, because email and connected-app links use it #337, Add links and Comment quotes to MCP reads #343, Show a "via connected app" label on chat posts from a connected app #344, Add a get_changes MCP tool for changes since Last left #345, Cap the get_outline and list_chat_rooms output #380 and Test parallel connected-app writes across two collab replicas #381. Gated rows: Keep unchanged blocks when a connected app replaces a section #347, Let a connected app anchor a chat post to a quoted sentence #351 and Let an owner preview a connected app's edit before it applies #352. Ruling: RFC: should a burst of connected-app writes wait instead of failing busy? #360.

#329 comes first. Today a rewrite of a section that holds a picture deletes the picture.

Held, needs a ruling

The evidence is the admin /mcp usage page, not argument.

Alongside, not blocking

Shipped rules

• A connected app writes and posts only in documents the caller owns. Maintainer ruling, 2026-09-23.
• Trust follows the exact redirect URI (apps/webapp/src/utils/appTrust.ts), never the client name.
• The connector asks for openid, email and profile only (0c2145dfc).
• A connected-app token is refused outside /api/mcp (e4113fd9d, 24a4f68c2).
• A chat post removes every @, so it sends no notification.
• A read stops at 100,000 characters (MAX_READ_CHARS) and says so.

Do not build

• A credential table with a scopes column. Supabase supports five fixed scopes, and OAuth scopes do not control table access.
• A separate MCP service that calls the REST API. That is token passthrough.
• An adapter package. createMcpHandler in @modelcontextprotocol/server already takes a web-standard Request.
• A stdio transport. The custom-connector dialogs accept a remote server URL only.
• Any tool that answers without a login.
• A proxy authorization provider for Claude Code. Build it only if the Test the MCP connector in three AI apps, then finish its connect guide #357 run fails and RFC: should the MCP connector reach Claude Code as well? #231 rules for it.

Known gap

The server cannot check RFC 8707 audience today. Supabase always sets aud to authenticated and does not put the resource into the token (supabase/auth#2610). So the server requires the client_id claim, which only the OAuth flow mints. Check again when supabase/auth#2610 ships.