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>
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:
- Local stdio bridge that calls
/micropubwith 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. - 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.
- Official SDK in a sidecar process from the same image, behind the same reverse proxy, sharing the data volume.
- 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: trueandtoken_endpoint_auth_methods_supported: ["none"], andscopes_supportednow includesdraft. - An authorization request may carry
resource(RFC 8707). The only resource StarPunk names isSITE_URL/mcp; anything else isinvalid_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
scopeis offeredcreate update delete media draft. The owner unticks what they don't want on the consent screen. (The SDK publishes the resource'sscopes_supportedfrom its required scopes, which StarPunk leaves empty so any token can connect.) - The sidecar's
TokenVerifierlooks tokens up withverify_access_tokenand reports their resource. Withvalidate_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_URLhost and origin (plus localhost inDEV_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) anduvicorn. 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.