Files
StarPunk/docs/decisions/ADR-075-mcp-server.md
T
PhilandClaude Opus 5.5 84411a16d9 feat: MCP server for AI clients (v2.15.0, ADR-075)
Add an MCP server at SITE_URL/mcp so AI assistants (claude.ai connectors,
Claude Code) can search, read and write notes.

- starpunk/mcp_server: official MCP SDK 2.3, stateless Streamable HTTP with
  JSON responses, served by uvicorn as a sidecar from the same image.
  Ten tools; writes go through the Micropub handlers.
- IndieAuth: RFC 8707 resource indicators bound to codes and tokens
  (migration 022), client ID metadata document + public client metadata,
  draft in scopes_supported, default MCP scopes, consent screen note.
- BACKGROUND_WORKERS_ENABLED flag so the sidecar runs no workers.
- Docs: ADR-075, architecture/mcp.md and updates; CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 16:36:58 -07:00

5.8 KiB

ADR-075: MCP server for AI clients

Status

Accepted (v2.15.0, 2026-11-11)

Context

The owner wants AI assistants (claude.ai custom connectors, Claude Code and other Model Context Protocol clients) to read, search and write notes. Micropub already covers writing, but MCP clients don't speak Micropub: they discover tools over MCP and get tokens through OAuth 2.1 with protected resource metadata (RFC 9728), resource indicators (RFC 8707), and either dynamic client registration or a Client ID Metadata Document (CIMD).

StarPunk already runs an OAuth/IndieAuth authorization server (ADR-064) with PKCE, public clients only, and clients identified by a client_id URL whose JSON document lists redirect_uris. That is what MCP calls CIMD. Claude uses CIMD when the server's metadata says client_id_metadata_document_supported: true and lists none in token_endpoint_auth_methods_supported.

StarPunk is Flask on gunicorn sync workers (WSGI). The official MCP Python SDK is ASGI.

Options considered:

  1. Local stdio bridge that calls /micropub with a stored token, like existing Micropub MCP servers. No server changes, but every client needs the bridge installed, claude.ai and mobile can't use it, and reading is limited to what Micropub queries expose.
  2. Hand-written MCP route in Flask, stateless JSON only. No new dependencies or processes, but StarPunk would own the protocol details (version negotiation, JSON-RPC, Origin checks, auth metadata) and track the spec itself.
  3. Official SDK in a sidecar process from the same image, behind the same reverse proxy, sharing the data volume.
  4. Dynamic client registration (RFC 7591) in the authorization server. Every connection would register a new client, and nothing needs it once CIMD works.

Decision

1. A sidecar running the official SDK (option 3)

starpunk/mcp_server/ builds an mcp.server.MCPServer (SDK 2.3) and serves it with uvicorn (uvicorn starpunk.mcp_server.app:app --port 8001), as a second container from the same image. The reverse proxy sends /mcp* and /.well-known/oauth-protected-resource* to it and everything else to gunicorn. The endpoint is SITE_URL/mcp.

The transport is stateless Streamable HTTP with plain JSON responses. No session lives in the process, so restarts and several workers are harmless.

The sidecar builds the Flask app with BACKGROUND_WORKERS_ENABLED=false, so only the main container runs the webmention, WebSub and syndication workers. Each tool runs in a worker thread inside a Flask request context for SITE_URL, and calls the same service functions as the web app. SQLite (WAL) handles the second process like another gunicorn worker.

2. StarPunk is the authorization server; the sidecar only checks tokens

  • The authorization server metadata adds client_id_metadata_document_supported: true and token_endpoint_auth_methods_supported: ["none"], and scopes_supported now includes draft.
  • An authorization request may carry resource (RFC 8707). The only resource StarPunk names is SITE_URL/mcp; anything else is invalid_target. The resource is stored on the code and the token (migration 022), shown on the consent screen, and must match if the token request repeats it.
  • An MCP request with no scope is offered create update delete media draft. The owner unticks what they don't want on the consent screen. (The SDK publishes the resource's scopes_supported from its required scopes, which StarPunk leaves empty so any token can connect.)
  • The sidecar's TokenVerifier looks tokens up with verify_access_token and reports their resource. With validate_token_resource, the SDK refuses tokens not issued for /mcp, so a Micropub app's token can't be replayed against MCP. MCP tokens still work at /micropub; both stay the owner's own clients, and the Connected Apps page marks MCP tokens.
  • DNS rebinding protection allows only the SITE_URL host and origin (plus localhost in DEV_MODE).

3. Tools: reading and writing notes, nothing else

Tool Scope
search_notes, list_notes, get_note, get_site_config any token; drafts need create, update, delete or draft
list_tags create, update, delete or draft (as Micropub q=category)
create_note create or draft (draft-only tokens always make drafts)
update_note update
delete_note, undelete_note delete
upload_media media or create

Writing tools build a Micropub JSON request and call handle_create, handle_update and handle_delete. Scope rules, validation, crossposting, webmentions and WebSub notifications are therefore identical to Micropub. create_note makes a draft unless told otherwise. Tool annotations mark reading tools read-only and update and delete as destructive.

Syndication management, webmention moderation and other admin functions are not exposed.

Consequences

  • AI clients connect with just the URL: claude.ai via Settings → Connectors, Claude Code via claude mcp add --transport http starpunk SITE_URL/mcp. The owner approves them on the usual consent screen, and they appear (and can be revoked) under Connected Apps.
  • New runtime dependencies: mcp (with Starlette, pydantic and anyio) and uvicorn. They are only imported by the sidecar.
  • Deployments run a second container and need two proxy routes. A site that doesn't run the sidecar just has no MCP; nothing else changes.
  • There are still no refresh tokens. MCP clients re-authorize after INDIEAUTH_TOKEN_LIFETIME_DAYS.
  • SDK upgrades need care: 3.0 is expected to change defaults (for example validate_token_resource, which StarPunk already sets).

Alternatives

Options 1, 2 and 4 above. A stdio bridge could still be added later for clients that can't do OAuth; it would use a token from this flow.