feat(mcp): /mcp endpoint with bearer auth and role-gated tools

Second step of milestone 461. An MCP client (Claude Code, Claude Desktop
via mcp-remote, Open WebUI) connects to /mcp with a personal API token.

- mcp>=2.2 (SDK v2 MCPServer). Mounted by wrapping app.asgi_app, so /mcp
  never enters Quart's pipeline; stateless streamable HTTP so a redeploy
  never strands a client on a session id the new process didn't issue.
- Auth: Authorization: Bearer stw_… resolves to a Caller (user +
  effective role) in a ContextVar; 401 with WWW-Authenticate otherwise.
  The web pipeline's database gate runs first, so a DB restart answers
  503 instead of failing inside a tool.
- Registry, default-deny: register_tool(fn, role=, read_only=) is the only
  door; role and read_only are required. Tools above the caller's role,
  or from a disabled plugin, are neither listed nor callable. Undeclared
  arguments are refused (not silently dropped); a tool's ValueError
  reaches the agent as its reason; a DB failure mid-tool says so.
- Plugins contribute tools via an optional register_mcp_tools(register)
  export, all-or-nothing, replaced on hot-reload. Documented in
  docs/plugins/writing-a-plugin.md.
- First tool: whoami.
- Tests drive app.asgi_app directly (Quart's test client never reaches
  /mcp); the integration test mints a real token against Postgres and
  runs initialize → tools/list → whoami → revoke → 401.

Task #4966 "MCP-2 — /mcp transport".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/plugins/writing-a-plugin.md

@@ -323,6 +323,42 @@ Role hierarchy: `admin > operator > viewer`. Requiring `viewer` grants access to
 
 ---
 
+## Agent Tools (MCP)
+
+Steward serves an MCP endpoint at `/mcp` that AI clients reach with a personal API token created on the AI access page. A plugin adds tools to it by exporting an optional `register_mcp_tools(register)` from `__init__.py`:
+
+```python
+# plugins/myplugin/__init__.py
+def register_mcp_tools(register) -> None:
+    from .mcp_tools import list_targets, rescan_target
+    from steward.models.users import UserRole
+    register(list_targets, role=UserRole.viewer, read_only=True)
+    register(rescan_target, role=UserRole.operator, read_only=False)
+```
+
+```python
+# plugins/myplugin/mcp_tools.py
+from steward.mcp._context import current_caller, mcp_app
+
+
+async def list_targets(limit: int = 50) -> dict:
+    """What this tool is for, when to use it over its siblings, what each
+    argument's empty value means, and what comes back. This docstring is the
+    tool's description: it is all the agent knows about it."""
+    app = mcp_app()                 # Quart's current_app does not exist here
+    async with app.db_sessionmaker() as db:
+        ...
+    return {"targets": [...], "total": n, "truncated": n > limit}
+```
+
+- `role` and `read_only` are required. A tool is listed and callable only for callers whose role reaches `role`, and only while the plugin is enabled.
+- Tools run outside Quart's request pipeline: use `mcp_app()` and `current_caller()` from `steward.mcp._context`, never `current_app` or `session`.
+- Refuse by raising `ValueError("what was wrong, and what to do instead")`. The agent reads that text. Any other exception reaches it only as a generic failure.
+- Tool names are global across core and every plugin; a name already taken fails registration and the plugin contributes no tools (logged).
+- Hot-reloading the plugin replaces its tools.
+
+---
+
 ## Publishing to the Catalog
 
 The official plugin catalog is hosted at `https://git.fabledsword.com/bvandeusen/Steward-plugins`. Anyone can submit a plugin by opening a pull request — first-party and third-party plugins are treated identically by the catalog system.
@@ -413,6 +449,7 @@ Hot-reload works reliably for brand-new plugin installs. Updates to already-acti
 - [ ] Revision IDs prefixed with plugin name
 - [ ] `record_metric()` called inside `session.begin()`
 - [ ] Routes use `@require_role` decorator
+- [ ] MCP tools (if any) registered via `register_mcp_tools(register)` with a role and `read_only`
 - [ ] Templates namespaced under `templates/myplugin/`
 - [ ] Plugin enabled in app settings
 - [ ] `index.yaml` entry added with `download_url` and `checksum_sha256`