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>
4.1 KiB
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
- The client POSTs to
/mcpwithout a token and gets401withWWW-Authenticate: Bearer ... resource_metadata="SITE_URL/.well-known/oauth-protected-resource/mcp". - That document names
SITE_URL/mcpas the resource andSITE_URL/as the authorization server. The client reads/.well-known/oauth-authorization-server, which says it accepts client ID metadata documents and public clients. - The client sends the owner to
/auth/authorizewith itsclient_idURL, PKCE andresource=SITE_URL/mcp. StarPunk fetches the client's metadata document to checkredirect_uri(unless it has the same origin as theclient_id), and the owner logs in with OIDC and approves. With noscope, the default MCP scopes are offered. - The token endpoint exchanges the code. The token is bound to the resource.
- 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 theHostheader (DNS rebinding protection checks it againstSITE_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/mcpto authenticate. - Revoking: Admin → Connected Apps (MCP tokens are marked "(MCP)").