Files
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

4.1 KiB

MCP server (v2.15.0)

How AI clients use StarPunk through the Model Context Protocol. The decision and alternatives are in ADR-075.

Shape

client ──HTTPS──> reverse proxy
                    /mcp*, /.well-known/oauth-protected-resource*  ──> starpunk-mcp:8001 (uvicorn, MCP SDK)
                    everything else (incl. /auth/*, /.well-known/oauth-authorization-server)
                                                                    ──> starpunk:8000 (gunicorn, Flask)
starpunk and starpunk-mcp: same image, same environment, same /data volume
Module Role
starpunk/mcp_server/app.py ASGI entry: uvicorn starpunk.mcp_server.app:app --host 0.0.0.0 --port 8001
starpunk/mcp_server/server.py create_mcp_server(app) and create_asgi_app(app=None): stateless Streamable HTTP, JSON responses, 16 MB request limit, DNS rebinding protection
starpunk/mcp_server/auth.py StarPunkTokenVerifier: StarPunk tokens to SDK AccessTokens
starpunk/mcp_server/tools.py The tools; each runs in a thread inside app.test_request_context(base_url=SITE_URL)

create_asgi_app() with no argument builds the Flask app from the environment with BACKGROUND_WORKERS_ENABLED=false. The sidecar container should also set that variable, for clarity.

Authorization flow

  1. The client POSTs to /mcp without a token and gets 401 with WWW-Authenticate: Bearer ... resource_metadata="SITE_URL/.well-known/oauth-protected-resource/mcp".
  2. That document names SITE_URL/mcp as the resource and SITE_URL/ as the authorization server. The client reads /.well-known/oauth-authorization-server, which says it accepts client ID metadata documents and public clients.
  3. The client sends the owner to /auth/authorize with its client_id URL, PKCE and resource=SITE_URL/mcp. StarPunk fetches the client's metadata document to check redirect_uri (unless it has the same origin as the client_id), and the owner logs in with OIDC and approves. With no scope, the default MCP scopes are offered.
  4. The token endpoint exchanges the code. The token is bound to the resource.
  5. Each MCP request carries the token. The verifier looks it up and the SDK refuses it unless its resource is SITE_URL/mcp.

Details of codes, tokens and scopes are in simplified-auth-architecture.md.

Tools

Tool Does Scope
search_notes(query, include_drafts, limit) FTS5 search, with snippets any; drafts need a posting scope
list_notes(include_drafts, limit, offset) Newest first, summaries any; drafts need a posting scope
get_note(url_or_slug) Microformats2 properties (as Micropub q=source) any; drafts need a posting scope
list_tags(filter) Tags in use, most used first posting scope
get_site_config() Micropub q=config, including syndicate-to targets any
create_note(content, title, tags, draft=True, photos, in_reply_to, like_of, repost_of, bookmark_of, syndicate_to, slug, published_at) Micropub create create or draft
update_note(url, content, title, tags, add_tags, remove_tags, draft, photos, in_reply_to) Micropub update update
delete_note(url), undelete_note(url) Soft delete and restore delete
upload_media(filename, data_base64) Save an image, return its URL media or create

"Posting scope" means create, update, delete or draft. Limits are capped at 100. Micropub errors come back as tool errors (isError) with the Micropub error description.

Operating it

  • Environment: the same as the main container, plus BACKGROUND_WORKERS_ENABLED=false.
  • Proxy: route /mcp* and /.well-known/oauth-protected-resource* to port 8001, keeping the Host header (DNS rebinding protection checks it against SITE_URL).
  • Connecting: claude.ai Settings → Connectors → Add custom connector with SITE_URL/mcp; Claude Code: claude mcp add --transport http starpunk SITE_URL/mcp, then /mcp to authenticate.
  • Revoking: Admin → Connected Apps (MCP tokens are marked "(MCP)").