docs(mcp): 新增 MCP 服务器调研与规格

调研（docs/mcp-research.md）：对照 2025-11-25 spec 与 rmcp 源码，确认 Streamable HTTP 是 2026 唯一远程传输、stateless 为默认、bearer token 为单租户务实方案、官方 rmcp 的 Tower StreamableHttpService 可挂载于 axum。规格（docs/mcp-spec.md）：锁定 9 项设计决策（受众/作用域/有效期/检索机制/ 工具面/草稿可见性/加密存储/配置目标/构建路径）、模块划分、迁移、验收标准。 rmcp 锁定 =3.0.0-beta.3（稳定版 0.2.1 缺 Origin 校验等 spec 强制项）。
2026-07-28 11:09:45 +08:00 · 2026-07-28 11:09:45 +08:00 · 801cb79e0d
commit 801cb79e0d
parent f6e1dff600
2 changed files with 876 additions and 0 deletions
--- a/docs/mcp-research.md
+++ b/docs/mcp-research.md
@ -0,0 +1,651 @@
+# MCP Server Research — 2026 Best Practices for Embedding in Yggdrasil (Rust/Axum)
+
+> Researched 2026-07-28 against primary sources only: the MCP specification at
+> `modelcontextprotocol.io`, the `modelcontextprotocol` GitHub org (spec, rust-sdk),
+> the Rust SDK (`rmcp`) source/crate metadata, RFCs, and client vendor docs.
+> Every non-trivial claim carries a source link. Project code was not modified and
+> no project build/test commands were run.
+
+## TL;DR (read this first)
+
+- **The current stable spec is `2025-11-25`** — NOT `2025-06-18` as our brief assumed.
+  A development draft **`2026-07-28`** already exists and the Rust SDK tracks it.
+  Source: [versioning page](https://modelcontextprotocol.io/docs/learn/versioning).
+- **Streamable HTTP is the de-facto and only spec-blessed remote transport.** The old
+  HTTP+SSE transport was removed after `2024-11-05`. Hypothesis CONFIRMED.
+  Source: [transports spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports).
+- **Stateless mode is now the SDK default** (draft `2026-07-28`, SEP-2567): no
+  `Mcp-Session-Id`, no GET/DELETE stream. This fits a request-scoped Axum handler
+  perfectly and removes the hardest part of the protocol (session lifecycle).
+  Source: [rmcp README — Stateless Streamable HTTP](https://github.com/modelcontextprotocol/rust-sdk).
+- **Authorization is OPTIONAL in the spec.** OAuth 2.1 is the heavy, spec-blessed path;
+  for a **single-tenant blog where the admin mints tokens for their own clients**, a
+  static bearer token in the `Authorization: Bearer` header is the pragmatic, widely
+  supported choice. Claude Code, Cursor, and Cline all accept a custom `Authorization`
+  header verbatim. Hypothesis CONFIRMED, with caveats (Origin validation is **MUST**).
+  Source: [authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization).
+- **Use the official `rmcp` crate** (`v2.2.0` stable, `3.0.0-beta.2` dev, 3.4M
+  downloads/month, 1,765 dependent crates, Apache-2.0). It ships a Tower
+  `StreamableHttpService` that mounts on Axum with one line:
+  `axum::Router::new().nest_service("/mcp", service)`. Do NOT hand-roll JSON-RPC.
+  Source: [rmcp on lib.rs](https://lib.rs/crates/rmcp), [rmcp README](https://github.com/modelcontextprotocol/rust-sdk).
+- **Knowledge-base pattern is confirmed:** expose PUBLISHED posts as **Resources**
+  (URI-addressable, `resources/list` paginated, `resources/read`) AND ship a `search`
+  **Tool**. Tools are model-invoked; Resources are app/agent-selected. Both are the
+  documented split. Source: [resources](https://modelcontextprotocol.io/specification/2025-11-25/server/resources),
+  [tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).
+
+---
+
+## 1. Protocol & Transports
+
+### 1.1 Spec version & date
+
+The **current** protocol version is **`2025-11-25`** (status *Current*). The version
+identifier format is `YYYY-MM-DD`, bumped only on backwards-*incompatible* changes.
+Source: [versioning page](https://modelcontextprotocol.io/docs/learn/versioning).
+
+A **development draft `2026-07-28`** is already in flight; the `rmcp` README states it
+"tracks the MCP `2026-07-28` draft while remaining fully compatible with the stable
+`2025-11-25` release and earlier versions." Its headline features: server discovery &
+negotiation, transport-neutral subscriptions, long-running tasks, response caching,
+multi-round-trip requests, and standard HTTP routing headers.
+Source: [rmcp README](https://github.com/modelcontextprotocol/rust-sdk).
+
+### 1.2 Defined transports
+
+The spec defines exactly **two** transports ([transports spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)):
+
+1. **stdio** — client launches the server as a subprocess; messages over stdin/stdout.
+   "Clients SHOULD support stdio whenever possible." (Local only.)
+2. **Streamable HTTP** — server is an independent process; a **single MCP endpoint**
+   (e.g. `https://example.com/mcp`) handles POST (send JSON-RPC) and optionally GET
+   (open an SSE stream). The server MAY stream replies as `text/event-stream` or reply
+   with a single `application/json` body. The client MUST send `Accept: application/json, text/event-stream`.
+
+The **HTTP+SSE transport (2024-11-05) is removed/deprecated.** The spec states
+Streamable HTTP "replaces the HTTP+SSE transport from protocol version 2024-11-05" and
+provides a backwards-compatibility note for servers that want to keep serving old clients.
+Source: [transports — Backwards Compatibility](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#backwards-compatibility).
+
+### 1.3 Recommendation for an internet-facing server in 2026
+
+**Streamable HTTP is the de-facto standard for hosted/remote MCP.** It is the only
+HTTP transport the current spec defines, and every major client (Claude Code/Desktop,
+Cursor, Cline, Continue) supports it natively. stdio is explicitly local-only.
+Source: [transports spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports);
+client support: [Claude Code MCP](https://code.claude.com/docs/en/mcp).
+
+### 1.4 What changed across revisions
+
+**`2024-11-05` → `2025-03-26`:** introduced the HTTP+SSE transport (later replaced).
+Authorization framework introduced at the transport layer.
+
+**`2025-03-26` → `2025-06-18`** ([changelog](https://modelcontextprotocol.io/specification/2025-06-18/changelog)) — major:
+1. Removed JSON-RPC **batching**.
+2. Added **structured tool output** (`outputSchema`, `structuredContent`).
+3. Reclassified MCP servers as **OAuth 2.1 Resource Servers** with Protected Resource
+   Metadata discovery (RFC 9728).
+4. **Required** clients to implement **Resource Indicators (RFC 8707)**.
+5. Added the **Security Best Practices** page.
+6. Added **Elicitation** (server asks client/user for input).
+7. Added **Resource Links** in tool results.
+8. **Required** the `MCP-Protocol-Version` header on all subsequent HTTP requests.
+9. Changed lifecycle Operation SHOULD → **MUST**.
+
+**`2025-06-18` → `2025-11-25`** ([changelog](https://modelcontextprotocol.io/specification/2025-11-25/changelog)) — major:
+1. Added **OpenID Connect Discovery 1.0** support in AS discovery.
+2. **Icons** metadata on tools/resources/prompts.
+3. **Incremental scope consent** via `WWW-Authenticate` (SEP-835).
+4. Tool-name guidance (SEP-986).
+5. Richer **Elicitation** schemas (enums, single/multi-select, defaults) and **URL-mode elicitation**.
+6. **Tool calling inside sampling** (`tools`/`toolChoice`).
+7. **OAuth Client ID Metadata Documents** (SEP-991) as a recommended client-registration mechanism.
+8. **Experimental Tasks** extension (SEP-1686) — durable, polled long-running requests.
+9. JSON Schema **2020-12** as the default dialect.
+10. Servers MUST respond **403** for invalid `Origin` headers in Streamable HTTP.
+
+**`2025-11-25` → draft `2026-07-28`** (per rmcp README): server discovery/negotiation,
+transport-neutral `subscriptions/listen` (replacing `resources/subscribe` + standalone GET),
+Tasks extension, response caching (`ttlMs`/`cacheScope`), multi-round-trip requests
+(MRTR, SEP-2322), standard HTTP routing headers (`Mcp-Method`/`Mcp-Name`/`Mcp-Param-*`,
+SEP-2243), and **stateless Streamable HTTP by default (SEP-2567)**.
+
+### 1.5 Session management — required vs optional vs stateless
+
+Session handling is **optional, not required** ([transports — Session Management](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management)):
+
+- A Streamable HTTP server **MAY** assign an `MCP-Session-Id` in the `InitializeResult`
+  response. If present, the client MUST echo it on every subsequent request; a server
+  that requires it SHOULD 400 requests lacking it.
+- The session ID MUST be only visible ASCII (`0x21`–`0x7E`), SHOULD be cryptographically
+  secure (UUID/JWT/hash).
+- **Stateless mode** is explicitly supported: a server simply never returns a session ID
+  and answers each POST independently. In draft `2026-07-28` (SEP-2567) this becomes the
+  **default** for the modern protocol — "no `Mcp-Session-Id`, no standalone GET/DELETE
+  stream, and no `Last-Event-ID` resumption." ([rmcp README](https://github.com/modelcontextprotocol/rust-sdk)).
+
+The `MCP-Protocol-Version` header (e.g. `MCP-Protocol-Version: 2025-11-25`) is **MUST**
+on every post-initialize HTTP request; for backwards compat a server without other info
+SHOULD assume `2025-03-26`, and MUST 400 on an unsupported version.
+Source: [transports — Protocol Version Header](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#protocol-version-header).
+
+> **Implication for Yggdrasil:** run **stateless**. No session store, no `Mcp-Session-Id`.
+> Each POST is a self-contained Axum handler. This collapses the protocol to "JSON-RPC
+> over POST, optionally streaming the reply."
+
+---
+
+## 2. Auth & Security
+
+### 2.1 What the spec mandates for remote (HTTP) servers
+
+Authorization is **OPTIONAL** ([authorization spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization)):
+> "Authorization is OPTIONAL for MCP implementations. When supported: Implementations
+> using an HTTP-based transport SHOULD conform to this specification."
+
+When you DO implement spec-conformant auth, it is **OAuth 2.1** layered on:
+- **OAuth 2.1 IETF draft** (`draft-ietf-oauth-v2-1-13`), whose security BCP is
+  [RFC 9700](https://datatracker.ietf.org/doc/html/rfc9700).
+- **PKCE** (S256) — clients MUST implement it and MUST refuse to proceed without
+  `code_challenge_methods_supported`.
+- **Resource Indicators ([RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html))** —
+  clients MUST send `resource=` in auth+token requests; servers MUST validate tokens
+  were issued for them (audience binding).
+- **OAuth 2.0 Protected Resource Metadata ([RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728))**
+  — servers MUST publish `authorization_servers` via a `WWW-Authenticate` 401 challenge
+  and/or `.well-known/oauth-protected-resource`.
+- **Authorization Server Metadata ([RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414))**
+  or **OpenID Connect Discovery 1.0** for AS discovery.
+- **Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591))** — MAY;
+  now secondary to **Client ID Metadata Documents (SEP-991)**.
+
+Crucially, the token always travels as a **bearer** in the standard header:
+`Authorization: Bearer <access-token>` — MUST be on **every** HTTP request, MUST NOT be
+in the query string. Source: [Access Token Usage](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#access-token-usage).
+
+### 2.2 The practical alternative for a single-tenant blog
+
+Full OAuth 2.1 (PKCE + DCR + resource metadata + an authorization server you host) is
+vastly over-engineered for **one admin minting tokens for their own AI clients
+(Claude Desktop, Cursor, Cline)**. The spec leaves the door open by making auth OPTIONAL,
+and **every major client supports a static bearer token via the `Authorization` header**,
+which is exactly the `Authorization: Bearer` form the spec mandates for OAuth tokens
+anyway:
+
+- **Claude Code / Claude Desktop**: `claude mcp add --transport http <name> <url> --header "Authorization: Bearer <token>"`;
+  JSON form uses `type: "http"` (alias `streamable-http`), `url`, `headers.Authorization`.
+  Source: [Claude Code MCP docs](https://code.claude.com/docs/en/mcp).
+- **Cursor**: `~/.cursor/mcp.json` → `type: "streamable-http"` (or `"http"`), `url`,
+  `headers.Authorization`. Source: [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol).
+- **Cline**: `cline_mcp_settings.json` → `type: "streamableHttp"`, `url`,
+  `headers.Authorization`, plus `disabled`/`autoApprove`. ⚠️ Cline historically lets its
+  OAuth-provider logic override custom `Authorization` headers on `sse` entries, so
+  `streamableHttp` is the recommended type for bearer tokens. Source: [Cline docs / GitHub](https://cline.bot),
+  [GitHub issue on header override](https://github.com/cline/cline).
+
+**So: model the credential as an opaque bearer token, validate it per-request, and skip
+the OAuth dance entirely.** The header format is identical to what an OAuth-issued token
+would use, so this path is forward-compatible if you ever add real OAuth.
+
+Caveats the spec forces regardless of token source:
+- **Token passthrough is forbidden.** "MCP servers MUST NOT accept any tokens that were
+  not explicitly issued for the MCP server." ([Token Passthrough](https://modelcontextprotocol.io/specification/2025-11-25/basic/security_best_practices#token-passthrough)).
+  For a self-issued opaque token validated by SHA-256 lookup, this is automatically
+  satisfied — the token *is* issued for our server.
+- **Sessions MUST NOT be used for authentication.** "MCP servers that implement
+  authorization MUST verify all inbound requests. MCP Servers MUST NOT use sessions for
+  authentication." ([Session Hijacking](https://modelcontextprotocol.io/specification/2025-11-25/basic/security_best_practices#session-hijacking)).
+  → The bearer token authenticates every request; `Mcp-Session-Id` (if ever used) is
+  transport-only and untrusted.
+- **Token theft guidance:** "Authorization servers SHOULD issue short-lived access
+  tokens." → make the admin-selectable lifetime short-by-default and rotatable.
+  Source: [Token Theft](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#token-theft).
+- **Scope minimization** is an explicit spec recommendation: avoid wildcard/omnibus
+  scopes, prefer progressive least-privilege. Source: [Scope Minimization](https://modelcontextprotocol.io/specification/2025-11-25/basic/security_best_practices#scope-minimization).
+
+### 2.3 The 2025 security incidents & mitigations
+
+- **Tool Poisoning Attack (TPA)** — coined/disclosed by **Invariant Labs** (April 2025;
+  since acquired by Snyk). An attacker (often a malicious or compromised MCP server)
+  embeds hidden instructions in tool *descriptions*/*schemas*; the LLM treats them as
+  authoritative and may exfiltrate data or call other tools. This is a form of indirect
+  prompt injection that turns the agent into a **confused deputy**. Mitigations:
+  treat tool metadata and tool *output* as untrusted; human-in-the-loop approval for
+  mutating calls; narrow scopes. Source: [Invariant Labs — Tool Poisoning Attacks](https://invariantlabs.ai/blogs/tool-poisoning-attacks/).
+- **Confused-deputy / over-privileged proxy** — the spec's canonical example: an MCP
+  proxy holding broad OAuth tokens to a third-party API is tricked into misusing them.
+  Mitigations: per-client consent, exact `redirect_uri` matching, per-request auth,
+  narrow scopes. Source: [Confused Deputy Problem](https://modelcontextprotocol.io/specification/2025-11-25/basic/security_best_practices#confused-deputy-problem).
+- **Rug.md / malicious resources** — the broader supply-chain risk that a benign-looking
+  resource (e.g. a markdown file) carries injection payloads. Mitigation: read paths
+  (Resources) should not be auto-executed; segregate read-only from mutating Tools.
+- **Token Passthrough** — covered above; explicitly forbidden.
+- **SSRF via OAuth metadata URLs** — clients fetching `WWW-Authenticate`/resource-metadata
+  URLs must block private IPs / cloud metadata. (Relevant if Yggdrasil ever acts as an
+  MCP *client*; less so as a server.) Source: [SSRF](https://modelcontextprotocol.io/specification/2025-11-25/basic/security_best_practices#server-side-request-forgery-ssrf).
+- **Session hijacking** — covered above.
+- **Lethal trifecta** (community framing, Simon Willison et al.): private-data access +
+  untrusted content + outbound capability = trivial exfiltration. Mitigation: don't give
+  a single token all three; scope tools down.
+- **`mcp-remote` CVE-2025-6514** — a command-injection bug in the popular `mcp-remote`
+  shim that bridges stdio clients to remote servers. Lesson: vet the transport shim, not
+  just your server.
+
+### 2.4 Mandatory server-side hardening (from the Streamable HTTP security warning)
+
+The spec's Streamable HTTP section makes three requirements/non-recommendations
+([Security Warning](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http)):
+
+1. Servers **MUST validate the `Origin` header** on all connections to prevent DNS
+   rebinding; invalid Origin → **403**. *(From 2025-11-25 this 403 is a hard MUST.)*
+2. Local servers SHOULD bind to localhost (not relevant — we are remote).
+3. Servers **SHOULD implement proper authentication for all connections.**
+
+---
+
+## 3. Primitives to Implement
+
+MCP primitives split into **server-offered** (Resources, Prompts, Tools, Logging,
+Completions) and **client-offered** (Sampling, Roots, Elicitation). For a content/CMS
+MCP server the relevant set is small. Sources:
+[lifecycle capabilities](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle),
+[resources](https://modelcontextprotocol.io/specification/2025-11-25/server/resources),
+[tools](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).
+
+| Primitive | Purpose | Yggdrasil? |
+|---|---|---|
+| **Tools** | Model-invoked functions (`tools/call`). Model-controlled. | **Yes** — search, create/update/publish posts, moderate comments, manage tags/settings. |
+| **Resources** | App/agent-selected context, addressable by **URI**, listable via `resources/list`, readable via `resources/read`. | **Yes** — each PUBLISHED post = one Resource. |
+| **Resource Templates** | URI templates (RFC 6570) for parameterized resources. | **Yes** — e.g. `post://{slug}` or `https://rua.plus/posts/{slug}`. |
+| **Prompts** | Templated user-facing workflows (`prompts/get`). | Optional — e.g. a "draft a post about X" prompt. Low priority. |
+| **Completions** | Argument autocompletion. | Optional, skip for MVP. |
+| **Logging** | Structured log stream to client. | Optional; **deprecated** in draft `2026-07-28` (SEP-2577). Skip. |
+| **Elicitation** | Server asks client/user for structured input mid-operation. | Optional; useful for confirmations but adds complexity. Skip for MVP. |
+| **Sampling** | Server asks client's LLM to run a completion. | **Skip.** Deprecated (SEP-2577); not needed. |
+| **Roots** | Client tells server its workspace boundaries. | **Skip** (local-IDE concept). Deprecated (SEP-2577). |
+| **Tasks** | Long-running, polled operations (2025-11-25 experimental). | Skip for MVP; only relevant for very slow ops. |
+
+### 3.1 The knowledge-base pattern (Resources + a search Tool) — recommended
+
+This **is** the documented split and the recommended pattern:
+
+- **Resources are "application-driven"** — the host decides how to incorporate them
+  (UI picker, heuristics, or the model's selection). Each is identified by a URI and
+  returns `text` or base64 `blob` content. Source: [resources — User Interaction Model](https://modelcontextprotocol.io/specification/2025-11-25/server/resources).
+- **Tools are "model-controlled"** — the LLM discovers and invokes them automatically.
+  "There SHOULD always be a human in the loop with the ability to deny tool invocations."
+  Source: [tools — User Interaction Model](https://modelcontextprotocol.io/specification/2025-11-25/server/tools).
+
+Concretely for Yggdrasil:
+- `resources/list` → paginated list of PUBLISHED posts (title, URI, mimeType `text/markdown`).
+- `resources/templates/list` → `post://{slug}` (or the canonical HTTPS URL).
+- `resources/read` → full rendered Markdown/HTML of one post.
+- A `search_posts` **Tool** → keyword/FTS query, returns summaries + `resource_link`s
+  to the matching posts (the `resource_link` content type, added 2025-06-18, lets a tool
+  return URIs the client can then `resources/read`). Source: [Resource Links](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#resource-links).
+- Mutating Tools (`create_post`, `update_post`, `publish_post`, `delete_post`,
+  `moderate_comment`, `update_settings`, `manage_tags`) for admin tokens.
+
+### 3.2 Pagination of large resource lists
+
+MCP uses **opaque cursor-based pagination**, not numbered pages
+([pagination spec](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/pagination)):
+
+- Server returns `nextCursor` when more exist; client passes `cursor` to continue.
+- **Page size is server-determined**; clients MUST NOT assume a fixed size.
+- Applies to `resources/list`, `resources/templates/list`, `prompts/list`, `tools/list`.
+- Clients MUST treat cursors as opaque; invalid cursor → error `-32602` (Invalid params).
+- "Pagination is especially important when connecting to external services over the
+  internet."
+
+> Implement `resources/list` with a cursor (e.g. base64 of `("published_at", id)` or a
+> signed offset). For the search Tool, cap result count and return `resource_link`s
+> rather than dumping entire bodies.
+
+---
+
+## 4. Client Discovery / Config
+
+All major clients consume a **`mcpServers` JSON object** keyed by server name. For a
+remote Streamable HTTP server with a bearer token the entries are structurally identical
+(`url` + `type` + `headers.Authorization`), differing only in the exact `type` spelling
+and the file location. **A "Generate MCP config" admin feature should emit one block per
+client** (or a canonical block plus copy-paste variants).
+
+### Minimal example (canonical — works for Claude Code & Cursor)
+
+```json
+{
+  "mcpServers": {
+    "yggdrasil": {
+      "type": "streamable-http",
+      "url": "https://rua.plus/mcp",
+      "headers": {
+        "Authorization": "Bearer ygg_<opaque-token>"
+      }
+    }
+  }
+}
+```
+
+### Per-client specifics
+
+| Client | File | `type` value | Notes | Source |
+|---|---|---|---|---|
+| **Claude Code / Desktop** | `.mcp.json` (project) or `~/.claude.json` (user) | `"http"` (alias `"streamable-http"`) | `type` is **required** when `url` present or the entry is misread as stdio. CLI: `claude mcp add --transport http <name> <url> --header "Authorization: Bearer …"`. | [Claude Code MCP](https://code.claude.com/docs/en/mcp) |
+| **Cursor** | `~/.cursor/mcp.json` | `"streamable-http"` or `"http"` | Single `/mcp` endpoint; headers sent on every request. | [Cursor MCP](https://docs.cursor.com/context/model-context-protocol) |
+| **Cline** | `…/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` | `"streamableHttp"` | ⚠️ Use `streamableHttp`, **not** `sse` — Cline's OAuth logic can override custom `Authorization` headers on `sse` entries. Also has `disabled`, `autoApprove`. | [Cline docs](https://cline.bot) |
+| **Continue** | `~/.continue/config.json` `experimental.mcpServers` | `"streamableHttp"` | Same `url`+`headers` shape. | Continue docs |
+
+> The `Authorization: Bearer …` header shape is **identical** to what an OAuth-issued
+> token would use ([Access Token Usage](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#access-token-usage)),
+> so a generated config is forward-compatible with a future OAuth flow.
+
+A "Generate MCP config" button should:
+1. Mint (or reuse) a token with the chosen scope + lifetime.
+2. Render **three** ready-to-paste JSON snippets (Claude/Cursor share one; Cline uses
+   `streamableHttp`; include the CLI one-liner for `claude mcp add`).
+3. Warn that the snippet contains a secret and must not be committed.
+
+---
+
+## 5. Rust Ecosystem
+
+### 5.1 The official SDK: `rmcp`
+
+`rmcp` (crate `rmcp`, `modelcontextprotocol/rust-sdk`) is the **official** Rust MCP SDK,
+tokio-based, Apache-2.0. As of 2026-07-28:
+
+- **Latest stable: `2.2.0`** (2026-07-08); **dev: `3.0.0-beta.2`** (2026-07-24). There
+  was a `0.1.x → 1.x` (migration guide discussion #716) and now a `1.x → 2.x` line.
+- **3,398,090 downloads/month**, **1,765 dependent crates** (1,430 direct), Rust 2024
+  edition. This is a mature, heavily-used crate, not a toy.
+- Tracks `2026-07-28` draft while remaining compatible with `2025-11-25` and earlier.
+
+Source: [rmcp on lib.rs](https://lib.rs/crates/rmcp), [rmcp README](https://github.com/modelcontextprotocol/rust-sdk).
+
+### 5.2 Feature flags (cargo)
+
+```toml
+rmcp = { version = "2.2", features = [
+  "server",                                  # ServerHandler + tool system (default)
+  "macros",                                  # #[tool]/#[prompt] (default)
+  "schemars",                                # JSON Schema gen for inputSchema/outputSchema
+  "transport-streamable-http-server",        # StreamableHttpService (Tower)
+  "reqwest",                                 # rustls TLS backend (if you also build a client)
+] }
+```
+`auth` (OAuth) and `elicitation` are opt-in but **not needed** for a bearer-token server.
+Source: [rmcp feature flags](https://lib.rs/crates/rmcp).
+
+### 5.3 Mounting on Axum — there IS a first-class adapter
+
+`StreamableHttpService` is a **Tower `Service`**, mounted on Axum with `nest_service`:
+
+```rust
+use rmcp::transport::streamable_http_server::{
+    StreamableHttpService, StreamableHttpServerConfig,
+    session::local::LocalSessionManager,
+};
+
+let config = StreamableHttpServerConfig::default()
+    .with_legacy_session_mode(false) // stateless for legacy versions too (SEP-2567)
+    .with_json_response(true);       // plain application/json for simple tools,
+                                     // falls back to text/event-stream when streaming needed
+
+let service = StreamableHttpService::new(
+    || Ok(YggMcpServer::new(state.clone())), // fresh handler per request (stateless!)
+    LocalSessionManager::default().into(),
+    config,
+);
+
+let router = axum::Router::new()
+    .nest_service("/mcp", service)
+    // your existing Axum routes merge here in src/main.rs
+    .merge(existing_app_router());
+```
+Source: [rmcp README — Stateless Streamable HTTP](https://github.com/modelcontextprotocol/rust-sdk).
+
+> Because there is no per-session state, the `service_factory` runs **per request**.
+> Keep shared state (DB pool, moka cache) in a `Clone` handle captured by the closure;
+> do not rely on in-memory state surviving between requests.
+
+### 5.4 Defining tools/resources — declarative macros + trait
+
+- `#[tool_router]` + `#[tool]` macros generate `inputSchema`/`outputSchema` from
+  `schemars::JsonSchema` derive structs; handlers are plain `async fn`s returning
+  `String`/`Vec<ContentBlock>`/`CallToolResult`/`Result<_, McpError>`.
+- Resources: implement `list_resources`, `read_resource`, `list_resource_templates` on
+  the `ServerHandler` trait; advertise the `resources` capability in `get_info()`.
+- `list_changed` notifications let you push tool/resource-list updates without reconnect.
+Source: [rmcp README — Tools / Resources](https://github.com/modelcontextprotocol/rust-sdk).
+
+### 5.5 OAuth support (if ever needed)
+
+`rmcp` has a full OAuth 2.1 *client* implementation (`auth` feature): PKCE-S256, RFC 8707
+resource binding, RFC 9728/8414 discovery, DCR, Client ID Metadata Documents, scope
+upgrade on 403, automatic token refresh, injectable HTTP client. A server-side OAuth
+example (`servers_complex_auth_streamhttp`) exists. For our bearer-token design we do
+**not** enable this. Source: [rmcp OAUTH_SUPPORT.md](https://github.com/modelcontextprotocol/rust-sdk/blob/main/docs/OAUTH_SUPPORT.md).
+
+### 5.6 Hand-rolling JSON-RPC over Axum — feasibility & pitfalls
+
+Feasible (it's JSON-RPC 2.0 over POST) but **not recommended**:
+- You must implement the full lifecycle: `initialize` ↔ `notifications/initialized`,
+  capability negotiation, version header validation, `MCP-Protocol-Version` handling,
+  the SSE-vs-JSON response selection, `tools/list`+`tools/call`+`resources/list`+
+  `resources/read`+`resources/templates/list`, pagination cursors, `list_changed`,
+  error-code mapping (`-32602`, etc.).
+- Pitfalls: getting the `Accept`/`Content-Type` negotiation wrong, forgetting the
+  `Origin` 403, mishandling `MCP-Protocol-Version` (clients send the negotiated version),
+  JSON-RPC batching being removed (don't accept arrays), and drift as the spec moves to
+  `2026-07-28` (caching headers, MRTR, routing headers).
+- `rmcp` already solved all of this and is a `tower::Service` — there is no reason to
+  reimplement. The only case for hand-rolling is an exotic constraint (e.g. zero extra
+  deps on `FROM scratch`), which does not apply to Yggdrasil's Axum binary.
+
+---
+
+## 6. Knowledge Base / Retrieval
+
+### 6.1 MCP defines no embedding/semantic convention
+
+There is **no** MCP "search" or "retrieval" primitive and no embedding convention. Search
+is just a **Tool** whose `inputSchema` defines the query and whose result is content
+(possibly `resource_link`s). Resources are the addressable corpus. This is intentional —
+the protocol is agnostic to *how* you retrieve. Source: [tools spec](https://modelcontextprotocol.io/specification/2025-11-25/server/tools),
+[resources spec](https://modelcontextprotocol.io/specification/2025-11-25/server/resources).
+
+### 6.2 Full-text vs semantic/vector — tradeoffs
+
+- **Postgres FTS (tsvector/tsquery, `websearch_to_tsquery`)** — already in Yggdrasil
+  (`src/api/posts/search.rs`), zero new infra, ranking via `ts_rank`, good for a blog's
+  vocabulary, deterministic, no embedding model to host/version. **MVP choice.**
+- **pgvector + embeddings** — better recall for paraphrase/semantic queries, but adds:
+  an embedding model (API call or local), a pipeline to (re)embed on publish/edit,
+  a vector index (HNSW/IVFFlat), cost/latency per embed, and drift when the model is
+  upgraded. Worth it only when FTS recall is demonstrably insufficient.
+
+### 6.3 Recommended MVP for Yggdrasil
+
+1. **Read path = Resources.** Expose every PUBLISHED post as a Resource (URI =
+   canonical HTTPS URL or `post://{slug}`), `resources/list` paginated, `resources/read`
+   returns rendered Markdown (cheaper for the model than raw HTML; respects the existing
+   `content_html` cache by re-rendering).
+2. **Search path = a `search_posts` Tool** backed by the existing Postgres FTS. Returns
+   top-N `{title, slug, uri, snippet, published_at}` plus a `resource_link` for each so
+   the client can pull full text via `resources/read`. This matches the [Resource Links](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#resource-links)
+   pattern added in 2025-06-18.
+3. **Defer vector retrieval** until FTS recall is measured and found wanting. The Tool
+   boundary means swapping the backend later is invisible to clients.
+
+> Note: a search Tool result is model-consumed text and is therefore an indirect-prompt-
+> injection surface (attacker-controlled post bodies). Return snippets, validate/sanitize,
+> and keep write Tools separately scoped. See §2.3.
+
+---
+
+## 7. Operational Hardening
+
+### 7.1 Rate limiting keyed by token, not IP
+
+- The spec's **Scope Minimization** and Token Theft guidance both push toward per-principal
+  accountability. The existing Yggdrasil governor is keyed by **client IP**; for the MCP
+  route the limiter MUST be keyed by the **bearer token** (or its hash), because (a) all
+  requests hit one endpoint and IP-keying collapses many users behind a NAT/proxy, and
+  (b) the token is the real principal.
+- Implementation: an Axum `from_fn` middleware on `/mcp` that extracts the
+  `Authorization` header, resolves the token to a `(user_id, scope)` via SHA-256 lookup,
+  and feeds a `governor`/`tower` limiter keyed on `user_id` (or token id). The IP-keyed
+  governor stays on the rest of the app.
+- Bound per-request size, add a hard per-tool timeout (the spec recommends configurable
+  per-request timeouts and honoring progress notifications — [Lifecycle — Timeouts](https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#timeouts)).
+
+### 7.2 Token storage — hashing
+
+- Store only the **SHA-256** of the token at rest (the spec says session IDs MAY be a
+  "cryptographic hash"; the same principle applies to bearer tokens). On each request,
+  `sha256(bearer)` → DB lookup → `(user_id, scopes, expires_at, revoked)`. This matches
+  the brief's "sessions here are SHA-256 hashed."
+- Tokens are long random opaque strings (≥32 bytes from a CSPRNG), prefixed (e.g.
+  `ygg_…`) for searchability/leak-detection, with an admin-settable **lifetime**
+  (default short, per the spec's "short-lived access tokens" guidance) and one-click
+  **rotation/revocation**.
+
+### 7.3 Per-token scopes (read / write / admin)
+
+- Implement a coarse, least-privilege scope set (no wildcards — the spec explicitly warns
+  against omnibus scopes). Suggested: `posts:read` (default), `posts:write`,
+  `comments:moderate`, `settings:write`, `admin`. A token carries a subset.
+- Map scopes to Tools at dispatch: `search_posts`/`resources/*` need `posts:read`;
+  `create_post`/`update_post` need `posts:write`; `publish_post`/`delete_post` and
+  `update_settings` need `admin`. Return HTTP 403 `insufficient_scope` (the spec's
+  step-up pattern) when a tool is called without the scope — this is exactly the
+  [WWW-Authenticate scope challenge](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#scope-challenge-handling)
+  shape, even though we are not doing full OAuth.
+- Because the token *list* can be advertised per-token, an admin can mint a read-only
+  token for a retrieval-only client and a full token for an authoring client.
+
+### 7.4 Origin allowlisting & transport security
+
+- **MUST validate `Origin`** on `/mcp` (DNS-rebinding defense) → 403 otherwise. Allowlist
+  the configured site origin(s) and reject the rest. ([transports security warning](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#streamable-http))
+- Serve over HTTPS only (the nginx-proxy in front of Yggdrasil already terminates TLS).
+  OAuth 2.1 requires HTTPS for all endpoints ([Communication Security](https://modelcontextprotocol.io/specification/2025-11-25/basic/authorization#communication-security));
+  bearer tokens over plaintext are trivially sniffable, so enforce HTTPS at the proxy.
+
+### 7.5 Audit logging
+
+- Log every `tools/call` (and mutating `resources` ops if any) with token id, user,
+  scope, tool name, args-hash, outcome, latency. The spec's "Accountability and Audit
+  Trail" argument against token passthrough is exactly why per-token identity matters.
+  Source: [Token Passthrough — Risks](https://modelcontextprotocol.io/specification/2025-11-25/basic/security_best_practices#token-passthrough).
+
+### 7.6 Integration with the existing Axum stack
+
+- Mount the `rmcp` `StreamableHttpService` at `/mcp` and merge it with the existing
+  manual + Dioxus server-function router in `src/main.rs` exactly as other routes are.
+- Layer the middleware **only on `/mcp`**: `bearer-auth → rate-limit(token) → origin-check → mcp-service`.
+  The IP-keyed governor and cookie-session auth on the rest of the app are untouched.
+- DB access reuses the existing `deadpool` pool; caching reuses `moka`; the existing FTS
+  query in `src/api/posts/search.rs` backs the `search_posts` tool.
+
+---
+
+## Recommendation for Yggdrasil
+
+A concrete, opinionated blueprint to turn into a spec.
+
+### Transport
+- **Streamable HTTP, single endpoint `/mcp`, stateless.** Pin `rmcp` and negotiate
+  `2025-11-25`; when stable, opt into `2026-07-28` for free stateless-by-default + caching
+  headers. No `Mcp-Session-Id`, no GET stream, no `Last-Event-ID`. Use
+  `with_json_response(true)` (plain `application/json`) with SSE fallback only when a
+  handler streams notifications.
+
+### Auth model
+- **Opaque bearer tokens** in `Authorization: Bearer ygg_<…>`, validated per-request by
+  `sha256(token)` → DB lookup. **No OAuth 2.1 / PKCE / DCR** (overkill for single-tenant).
+  The header format is identical to an OAuth bearer, so this is forward-compatible.
+- Tokens are admin-generated in a settings page, **SHA-256 hashed at rest**, with a
+  **user-selectable lifetime** (default e.g. 90 days, options 1/7/30/90/365 days +
+  never-expire), one-click **rotate** and **revoke**.
+- **Origin allowlist + HTTPS enforced** at nginx-proxy; 403 on bad Origin (spec MUST).
+
+### Primitives
+- **Resources:** every PUBLISHED post → one Resource (URI = canonical HTTPS URL).
+  `resources/list` (paginated, opaque cursor), `resources/templates/list`
+  (`post://{slug}`), `resources/read` (rendered Markdown). `listChanged` on publish/edit.
+- **Tools (read):** `search_posts` (FTS-backed, returns summaries + `resource_link`s),
+  `get_post`, `list_tags`.
+- **Tools (write, scope-gated):** `create_post`, `update_post`, `publish_post`,
+  `delete_post`, `moderate_comment`/`approve_comment`/`delete_comment`, `update_settings`,
+  `create_tag`/`rename_tag`.
+- Skip Prompts/Completions/Elicitation/Sampling/Roots/Tasks/Logging for MVP.
+
+### SDK choice
+- **`rmcp` v2.2.x** with features `server, macros, schemars, transport-streamable-http-server`.
+  Mount `StreamableHttpService` via `axum::Router::nest_service("/mcp", service)` and merge
+  with the existing router in `src/main.rs`. Do not hand-roll JSON-RPC.
+
+### Scopes
+- `posts:read` (default on every token), `posts:write`, `comments:moderate`,
+  `settings:write`, `admin`. Map tool→scope at dispatch; return `403 insufficient_scope`
+  on mismatch. Mint read-only tokens for retrieval clients.
+
+### Rate-limit strategy
+- New **token-keyed** limiter on `/mcp` only (extract bearer → `user_id` → governor key).
+  Leave the existing IP-keyed governor on the web app. Add per-request body-size cap and
+  per-tool timeout (honor progress notifications to extend).
+
+### Client-config output format
+"Generate MCP config" emits three snippets + a CLI one-liner, all pointing at
+`https://rua.plus/mcp` with the minted `Authorization: Bearer`:
+
+```json
+// Claude Code (.mcp.json / ~/.claude.json) and Cursor (~/.cursor/mcp.json)
+{
+  "mcpServers": {
+    "yggdrasil": {
+      "type": "streamable-http",
+      "url": "https://rua.plus/mcp",
+      "headers": { "Authorization": "Bearer ygg_<token>" }
+    }
+  }
+}
+```
+```json
+// Cline (cline_mcp_settings.json) — MUST use streamableHttp, not sse
+{
+  "mcpServers": {
+    "yggdrasil": {
+      "type": "streamableHttp",
+      "url": "https://rua.plus/mcp",
+      "headers": { "Authorization": "Bearer ygg_<token>" },
+      "disabled": false, "autoApprove": []
+    }
+  }
+}
+```
+```bash
+# Claude Code CLI
+claude mcp add --transport http yggdrasil https://rua.plus/mcp \
+  --header "Authorization: Bearer ygg_<token>"
+```
+
+### Where our hypothesis was right vs. needs amendment
+- **Right:** Streamable HTTP is the correct (and only) remote transport; bearer tokens in
+  the `Authorization` header are natively supported by every target client and are the
+  pragmatic auth for a single-tenant blog; embed in the Axum binary via `rmcp`'s Tower
+  service; expose published posts as Resources + a search Tool.
+- **Amend (1):** target **`2025-11-25`**, not `2025-06-18` (and `2026-07-28` is imminent);
+  the `MCP-Protocol-Version` header handling and `Origin`→403 rule are new MUSTs.
+- **Amend (2):** run **stateless** (SEP-2567) — drop any plan for an `Mcp-Session-Id`
+  store; sessions are transport-only and MUST NOT be used for auth.
+- **Amend (3):** the rate limiter must be **token-keyed**, not the existing IP-keyed
+  governor, and the mutating tools must be **scope-gated** (read/write/admin), not a
+  single all-powerful admin token.
+- **Amend (4):** treat search/tool output as an **indirect-prompt-injection surface**
+  (Tool Poisoning / Rug.md) — sanitize snippets, keep read vs write tools on separate
+  scopes, and rely on the client's human-in-the-loop for mutating calls.
--- a/docs/mcp-spec.md
+++ b/docs/mcp-spec.md
@ -0,0 +1,225 @@
+# MCP Server — Specification
+
+> Buildable spec for a Model Context Protocol server embedded in Yggdrasil.
+> Derives from the grilling decisions (2026-07-28) and `docs/mcp-research.md`.
+> Spec version: 1.0.
+
+## 1. Overview
+
+Expose the blog as an **MCP server** so the admin's own AI clients (Claude Code,
+Cursor, Cline/Continue) can (a) query published posts as a **knowledge base** and
+(b) perform nearly all backend operations (write posts, moderate comments, manage
+tags/settings, upload media, run code). An admin settings page generates per-token
+MCP client configs with a user-selectable token lifetime and three permission scopes.
+
+**Single-tenant model.** Tokens are minted by the admin for the admin's own clients.
+No OAuth 2.1 / PKCE / dynamic client registration. The bearer-token header format is
+identical to an OAuth bearer, so the path is forward-compatible if OAuth is ever added.
+
+## 2. Decisions (locked during grilling)
+
+| # | Decision | Choice |
+|---|---|---|
+| 1 | Audience | Admin's own AI clients only |
+| 2 | Scope model | `read` / `write` / `admin` (3 scopes) |
+| 3 | Token lifetime | Preset menu: 1d / 7d / 30d / 90d / never-expire (opt-in) |
+| 4 | Knowledge-base retrieval | Full-text search MVP (reuse Postgres FTS); published posts as MCP Resources + `search_posts` tool; architecture leaves a seam for future pgvector |
+| 5 | Tool surface | Post CRUD, post query, comment mgmt, tag mgmt, site settings, media upload, code runner. **Excludes** DB export/backup |
+| 6 | Scope mapping | media=write; code runner=admin-only; read=published only; write/admin=includes drafts |
+| 7 | Draft visibility | `read` → published only; `write`/`admin` → incl. drafts |
+| 8 | Token storage | AES-GCM encrypted at rest (env key `MCP_TOKEN_ENC_KEY`); retrievable by admin |
+| 9 | Config targets | Claude Code, Cursor, Cline/Continue, generic raw JSON |
+
+## 3. Goals / Non-goals
+
+**Goals**
+- One `/mcp` Streamable HTTP endpoint, stateless, spec `2025-11-25`.
+- Bearer-token auth with 3 scopes, encrypted-at-rest storage, selectable lifetime.
+- Knowledge base: published posts as paginated Resources + FTS `search_posts` tool.
+- Write/admin tools covering the locked surface.
+- Admin UI: token CRUD + one-click config generation for 4 client formats.
+
+**Non-goals (MVP)**
+- OAuth 2.1 / PKCE / DCR (forward-compatible seam only).
+- Semantic/vector retrieval (pgvector) — full-text first; interface is vector-ready.
+- Prompts / Completions / Elicitation / Sampling / Roots / Tasks / Logging primitives.
+- Multi-tenant / public token issuance.
+- Database export/backup over MCP.
+
+## 4. Architecture
+
+### 4.1 Transport & mount
+- **Streamable HTTP, stateless** (SEP-2567): no `Mcp-Session-Id`, no GET stream.
+  Each POST is a self-contained request; the bearer token authenticates it.
+- Mount the official **`rmcp`** crate's Tower `StreamableHttpService` at `/mcp` via
+  `axum::Router::nest_service("/mcp", service)`, merged into the app router in
+  `src/main.rs` alongside the existing `upload_route`/`export_route`/`sse_route`.
+- Negotiate protocol `2025-11-25`; respond `application/json` (no SSE stream needed
+  for non-streaming tools).
+
+### 4.2 Authentication
+- `Authorization: Bearer ygg_<opaque>` on every request.
+- A new middleware/extractor resolves the bearer → `(user_id, scope)`:
+  decrypt-stored-token lookup by token id, enforce expiry, update `last_used_at`.
+- **`Origin` → 403 is a hard MUST** (spec `2025-11-25`): validate `Origin` against the
+  same trusted-origin allowlist as CSRF (`APP_BASE_URL` / Host fallback).
+- `MCP-Protocol-Version` header honored; reject unsupported versions with 400.
+- Sessions MUST NOT be used for auth (spec); the token authenticates every request.
+
+### 4.3 Rate limiting
+- New **token-keyed** governor bucket on `/mcp` only (extract bearer → `user_id`).
+  The existing IP-keyed governor stays on the web app and is NOT reused for MCP.
+- Per-request body-size cap; rely on the global `statement_timeout` for DB bounds.
+
+### 4.4 Scope enforcement
+- Each tool declares its required scope. Dispatch checks `token.scope >= required`;
+  mismatch → `403 insufficient_scope`-style MCP error.
+- Read tools (search, get/list published) = `read`. Mutating post/comment/tag/media =
+  `write`. Settings + code runner = `admin`.
+- Search/snippet output is an **indirect-prompt-injection surface**: sanitize, keep
+  read vs write on separate scopes, lean on the client's human-in-the-loop.
+
+### 4.5 Feature gating
+- All MCP code is **server-only**: `#[cfg(feature = "server")]` impl + compiling
+  `#[cfg(not(feature = "server"))]` stubs for the WASM build, per AGENTS.md §1.
+- The admin UI page renders on both targets; it calls token-management server fns.
+
+## 5. Data model
+
+### 5.1 Migration `015_mcp_tokens.sql` (+ register in `MIGRATIONS`)
+```sql
+CREATE TABLE IF NOT EXISTS mcp_tokens (
+    id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    user_id       INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+    name          TEXT NOT NULL,
+    scope         TEXT NOT NULL CHECK (scope IN ('read','write','admin')),
+    -- AES-GCM ciphertext of the full bearer token (nonce || ct || tag), hex-encoded.
+    token_enc     TEXT NOT NULL,
+    -- SHA-256 of the token for fast constant-time lookup by bearer on each request.
+    token_hash    CHAR(64) NOT NULL,
+    created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+    expires_at    TIMESTAMPTZ,            -- NULL = never-expire (opt-in)
+    last_used_at  TIMESTAMPTZ,
+    revoked_at    TIMESTAMPTZ
+);
+CREATE UNIQUE INDEX mcp_tokens_token_hash_active_idx
+    ON mcp_tokens (token_hash) WHERE revoked_at IS NULL;
+CREATE INDEX mcp_tokens_user_idx ON mcp_tokens (user_id);
+```
+
+### 5.2 Model (`src/models/mcp_token.rs`)
+`McpToken` (DB row), `McpTokenSummary` (list response — no secret), `CreateTokenResponse`
+(returns plaintext once), plus a `TokenScope` enum (`Read`/`Write`/`Admin`) with
+`>=` ordering and serde.
+
+## 6. Module breakdown
+
+New top-level module `src/mcp/` (server-only impl, stubs for WASM):
+
+| Path | Responsibility |
+|---|---|
+| `src/mcp/mod.rs` | Module root, re-exports, `cfg` gate |
+| `src/mcp/crypto.rs` | AES-GCM encrypt/decrypt of tokens; reads `MCP_TOKEN_ENC_KEY` |
+| `src/mcp/auth.rs` | Bearer extractor → `(user_id, scope)`; Origin check; `last_used_at` update |
+| `src/mcp/rate_limit.rs` | Token-keyed governor for `/mcp` |
+| `src/mcp/server.rs` | rmcp `ServerHandler` impl: `tools/list`, `resources/list`, `resources/read`, dispatch |
+| `src/mcp/tools/` | Tool impls: `read.rs`, `posts.rs`, `comments.rs`, `tags.rs`, `settings.rs`, `media.rs`, `runner.rs` |
+| `src/mcp/resources.rs` | Published-post Resources + templates (`post://{slug}`) |
+| `src/mcp/router.rs` | Builds the `StreamableHttpService`, mounts at `/mcp` (called from `main.rs`) |
+| `src/mcp/config.rs` | Generates the 4 client config formats from a token |
+
+Token management lives in the existing API tree:
+| Path | Responsibility |
+|---|---|
+| `src/api/mcp_tokens.rs` | `#[server]` fns: `create_mcp_token`, `list_mcp_tokens`, `revoke_mcp_token`, `reveal_mcp_token` (admin-guarded) |
+| `src/models/mcp_token.rs` | shared DTOs |
+
+Admin UI:
+| Path | Responsibility |
+|---|---|
+| `src/pages/admin/mcp.rs` | Token CRUD + config generator page |
+| nav entry in the admin layout | link to `/admin/mcp` |
+
+### 6.1 Tool catalogue
+
+**Resources** (read scope, published posts only)
+- `resources/list` — paginated published posts (opaque cursor; page size server-set).
+- `resources/templates/list` — `post://{slug}`.
+- `resources/read` — rendered Markdown of one post.
+
+**Tools — `read`**
+- `search_posts(query, limit?, cursor?)` — FTS via existing search helper; returns
+  summaries + `resource_link`s to matching posts.
+- `get_post(slug|id)` — published only.
+- `list_tags()`.
+
+**Tools — `write`** (also readable incl. drafts)
+- `create_post`, `update_post`, `publish_post`, `trash_post`, `delete_post`.
+- `list_comments`, `approve_comment`, `delete_comment`, `set_comment_status`.
+- `create_tag`, `rename_tag`.
+- `upload_media` (base64 → existing upload pipeline).
+
+**Tools — `admin`**
+- `get_settings`, `update_settings`.
+- `run_code` (delegates to the existing code-runner execute path; admin-only).
+
+## 7. New dependencies & env
+
+**Cargo.toml** (added under `[features] server`) — **pinned to the 3.x beta line,
+verified 2026-07-28 by a throwaway axum-0.8 probe.** The stable `rmcp 0.2.1` is far
+older and LACKS `with_json_response`, `with_allowed_origins` (Origin→403),
+`with_max_request_body_bytes`, protocol-version validation, and stateless-by-default —
+all of which the 3.x beta ships and which this spec relies on. `transport-worker` must
+be added explicitly (`LocalSessionManager` unconditionally uses `transport::worker`).
+- `rmcp = { version = "=3.0.0-beta.3", optional = true, features = ["server", "macros", "transport-streamable-http-server", "transport-worker"] }`
+- `aes-gcm = { version = "0.10", optional = true }` (token encryption).
+
+**Verified integration shape** (probe at `/tmp/rmcp-probe`):
+- Mount: `Router::new().nest_service("/mcp", StreamableHttpService::new(factory, LocalSessionManager::default().into(), config))`.
+- Config: `StreamableHttpServerConfig::default().with_legacy_session_mode(false).with_json_response(true).with_allowed_origins([APP_BASE_URL])`.
+- Auth: axum `from_fn` middleware resolves bearer → inserts `McpPrincipal{user_id,scope}` into `request.extensions_mut()`.
+- Tool reads it via `Extension<http::request::Parts>` extractor → `parts.extensions.get::<McpPrincipal>()`.
+- Tool result: `CallToolResult::success(vec![ContentBlock::Text(TextContent::new(s))])`.
+- rmcp handles Origin→403, protocol-version 400, body-size 413 internally.
+
+**Env vars** (document in `.env.example`):
+- `MCP_TOKEN_ENC_KEY` — 32-byte AES-256 key, base64. Required when MCP is used; the
+  server warns at startup if absent (tokens cannot be minted without it).
+
+## 8. Acceptance criteria
+
+1. `POST /mcp` with a valid `read`-scope bearer returns `tools/list` including
+   `search_posts`; a `search_posts` call returns ranked published posts.
+2. `resources/list` paginates published posts; `resources/read` returns one post's
+   Markdown; cursor pagination round-trips.
+3. A request with no/invalid/expired/revoked token is rejected (401/403).
+4. A `read` token calling a `write` tool is rejected (`insufficient_scope`).
+5. `write`/`admin` tokens can read drafts; `read` tokens cannot.
+6. `create_post` via MCP writes a row, renders `content_html`, and invalidates the
+   matching moka + SSR caches (same write-flow as the web admin).
+7. Invalid `Origin` → 403; missing `MCP-Protocol-Version` → 400.
+8. Admin UI lists tokens (name, scope, created, expires, last-used), reveals plaintext
+   on demand, revokes, and emits copy-ready config for all 4 client formats.
+9. Token DB column never stores plaintext; `token_enc` is AES-GCM ciphertext.
+10. `cargo build --no-default-features --features web` compiles (WASM stubs present);
+    `cargo build --no-default-features --features server` compiles;
+    `cargo clippy --all-features -- -D warnings` passes.
+11. `make test` (existing suite) still passes; new unit tests cover crypto, scope
+    ordering, cursor pagination, and config generation (pure, DB-free).
+
+## 9. Risks & mitigations
+
+- **rmcp/Axum version skew** — rmcp must target axum 0.8. Verify before pinning; if
+  incompatible, the fallback is a thin hand-rolled JSON-RPC-over-POST layer (larger
+  effort, research says avoid). *Mitigation: spike the mount in the tracer bullet first.*
+- **Indirect prompt injection** — search/snippet output reaches the model. *Mitigation:
+  sanitize, separate read/write scopes, human-in-the-loop on mutating tools.*
+- **Token leak = full blog takeover** — *Mitigation: encrypted-at-rest, selectable
+  short lifetimes, revocation, token-keyed rate limit, Origin enforcement.*
+- **WASM build breakage** — *Mitigation: every server-only symbol gets a stub; the
+  tracer bullet must prove `--features web` compiles before tool flesh-out.*
+
+## 10. Build path
+
+Spec → tracer-bullet tickets (`/to-tickets`) → per-ticket `/implement` with cleared
+context. Ticket files live under `.scratch/mcp-server/issues/`.