feat(mcp): connect card, MCP docs, and an end-to-end roles/audit test over HTTP

MCP-8 #4972 "Connect card, docs, and end-to-end integration test".

- AI access page: a "Connect a client" card with the /mcp URL (from
  Settings → General → Public base URL, else the request host) and recipes
  for Claude Code, Claude Desktop (mcp-remote) and other Streamable HTTP
  clients, plus the reverse-proxy note. The token-created page shows the
  same recipes with the new token filled in, ready to paste.
- docs/core/mcp.md: connecting, the reverse-proxy requirements, the
  security model (token ceiling, default deny, check-mode default, secrets,
  audit), tools by role, response conventions, adding tools.
  docs/architecture.md describes the /mcp dispatch outside the blueprint
  pipeline; docs/reference/code-map.md gains an MCP section.
- tests/integration/test_mcp.py: over HTTP, a viewer token lists no write
  tools and is refused one by name; an operator token reads get_overview
  and its maintenance-window create/end land in the audit log as
  "<user> via MCP" with the token id. (Revoked → 401 was already covered.)

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

steward/ai_access/routes.py

@@ -14,6 +14,8 @@ from sqlalchemy import select
 from steward.auth.middleware import current_user_id, require_role
 from steward.core import api_tokens
 from steward.core.audit import log_audit
+from steward.core.settings import public_base_url
+from steward.mcp.server import MCP_PATH
 from steward.models.users import User, UserRole
 
 ai_access_bp = Blueprint("ai_access", __name__, url_prefix="/ai-access")
@@ -21,6 +23,11 @@ ai_access_bp = Blueprint("ai_access", __name__, url_prefix="/ai-access")
 _EXPIRY_CHOICES = [("", "Never"), ("30", "30 days"), ("90", "90 days"), ("365", "1 year")]
 
 
+def _mcp_url() -> str:
+    """The /mcp endpoint as a client outside this request reaches it."""
+    return public_base_url(request) + MCP_PATH
+
+
 async def _session_user(db) -> User:
     user_id = current_user_id()
     if not user_id:
@@ -42,6 +49,7 @@ async def _render_index(db, user: User, *, error: str | None = None, status: int
         grantable=api_tokens.grantable_roles(user.role),
         expiry_choices=_EXPIRY_CHOICES,
         error=error,
+        mcp_url=_mcp_url(),
     )
     return body, status
 
@@ -81,7 +89,8 @@ async def create():
     await log_audit(current_app, user.id, user.username, "api_token.create",
                     entity_type="api_token", entity_id=str(token.id),
                     detail={"name": token.name, "role": token.role.value})
-    return await render_template("ai_access/created.html", raw_token=raw, token=token)
+    return await render_template("ai_access/created.html", raw_token=raw, token=token,
+                                 mcp_url=_mcp_url())
 
 
 @ai_access_bp.post("/tokens/<int:token_id>/revoke")

steward/templates/ai_access/_connect.html

@@ -0,0 +1,56 @@
+{#- How to point an AI client at /mcp. `mcp_url` is the endpoint; `token` is the
+    raw token on the page that just created one, else a placeholder. -#}
+{% set tok = token or "stw_…your token…" %}
+{% set pre = "background:var(--bg);padding:0.75rem;border-radius:4px;overflow-x:auto;font-size:0.78rem;color:var(--text);margin:0.5rem 0 0;white-space:pre;" %}
+<div class="card" id="connect">
+  <div class="section-title" style="margin-bottom:0.5rem;">Connect a client</div>
+  <div style="font-size:0.85rem;color:var(--text-muted);line-height:1.55;margin-bottom:0.75rem;">
+    Steward's MCP endpoint. Clients send the token as
+    <code>Authorization: Bearer …</code> on every request.
+  </div>
+  <div style="display:flex;gap:0.5rem;align-items:center;margin-bottom:1rem;">
+    <input type="text" id="mcp-url" value="{{ mcp_url }}" readonly aria-label="MCP endpoint URL"
+           style="flex:1;font-family:ui-monospace,monospace;font-size:0.8rem;background:var(--bg);color:var(--text);">
+    <button type="button" class="btn btn-ghost btn-sm" style="white-space:nowrap;"
+            onclick="navigator.clipboard.writeText(document.getElementById('mcp-url').value).then(()=>this.textContent='Copied')">Copy</button>
+  </div>
+
+  <details open>
+    <summary style="cursor:pointer;font-weight:600;">Claude Code</summary>
+    <pre style="{{ pre }}">claude mcp add --transport http steward {{ mcp_url }} \
+  --header "Authorization: Bearer {{ tok }}"</pre>
+  </details>
+
+  <details style="margin-top:0.75rem;">
+    <summary style="cursor:pointer;font-weight:600;">Claude Desktop</summary>
+    <div style="font-size:0.8rem;color:var(--text-muted);margin-top:0.4rem;line-height:1.5;">
+      Add to <code>claude_desktop_config.json</code>. It bridges through
+      <code>mcp-remote</code>, which needs Node.js.
+    </div>
+    <pre style="{{ pre }}">{
+  "mcpServers": {
+    "steward": {
+      "command": "npx",
+      "args": ["mcp-remote", "{{ mcp_url }}",
+               "--header", "Authorization:${STEWARD_AUTH}"],
+      "env": { "STEWARD_AUTH": "Bearer {{ tok }}" }
+    }
+  }
+}</pre>
+  </details>
+
+  <details style="margin-top:0.75rem;">
+    <summary style="cursor:pointer;font-weight:600;">Open WebUI and other clients</summary>
+    <div style="font-size:0.8rem;color:var(--text-muted);margin-top:0.4rem;line-height:1.5;">
+      Add an MCP server using the <strong>Streamable HTTP</strong> transport, with the URL
+      above and bearer authentication set to the token. In Open WebUI this is an external
+      tool connection of type MCP; menu names vary between versions.
+    </div>
+  </details>
+
+  <div style="font-size:0.78rem;color:var(--text-muted);margin-top:1rem;line-height:1.5;">
+    Behind a reverse proxy, the URL above comes from <strong>Settings → General → Public
+    base URL</strong> when it is set. The proxy must pass the <code>Authorization</code>
+    header through and not buffer responses, since replies stream.
+  </div>
+</div>

steward/templates/ai_access/created.html

@@ -33,6 +33,8 @@
     If it leaks, revoke it from the AI access page.
   </p>
 
+  {% with token = raw_token %}{% include "ai_access/_connect.html" %}{% endwith %}
+
   <a href="/ai-access/" class="btn btn-ghost">Back to AI access</a>
 </div>
 {% endblock %}

steward/templates/ai_access/index.html

@@ -116,4 +116,9 @@
   </div>
 
 </div>
+
+<div style="max-width:720px;margin-top:1.5rem;">
+  {% set token = none %}
+  {% include "ai_access/_connect.html" %}
+</div>
 {% endblock %}