docs(mcp): document the stdio transport + MCP as an authz execution surface#3287
Merged
Merged
Conversation
…urface The serve-side MCP work (#3167) landed a second transport and a second identity-admission path, but two hand-written docs still described only the HTTP surface: - content/docs/ai/connect-mcp.mdx had no stdio section. Add one covering the opt-in OS_MCP_STDIO_ENABLED / OS_MCP_STDIO_API_KEY switches, the pinned single-principal identity model (resolved through the same verify chain, re-checked per call), and the fail-closed / no-`system`-bypass posture (ADR-0101), plus a troubleshooting row for the fail-closed boot. - content/docs/permissions/authorization.mdx did not enumerate MCP among the execution surfaces. Add a subsection describing both transports' fail-closed identity admission and the shared principal-bound path through gates 3-6 (ADR-0096 HTTP handleMcp/buildMcpBridge; ADR-0101 stdio plugin start), and list ADR-0096/0101 in the ADR index. Docs-only; @objectstack/docs is private (no changeset). doc-authoring guard clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_0115eg8dAaCfWaDYYAm3ma36
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
os-zhuang
marked this pull request as ready for review
July 19, 2026 14:14
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
The serve-side MCP work (#3167) landed a second transport (long-lived stdio, ADR-0101) and a second identity-admission path, but two hand-written docs still described only the HTTP surface. This closes those two gaps.
content/docs/ai/connect-mcp.mdx— add a stdio sectionThe page covered only OAuth/API-key over HTTP. Added a "Local stdio transport (opt-in)" section:
OS_MCP_STDIO_ENABLED/OS_MCP_STDIO_API_KEYboot switches (off by default, stricter than HTTP).OS_MCP_STDIO_API_KEY, resolved through the same verify + authz chain as HTTP/REST and re-checked on every call (revocation takes effect live), so RBAC/RLS/FLS/tenant apply exactly as they would to that identity.systembypass (ADR-0101).content/docs/permissions/authorization.mdx— enumerate MCP as an execution surfaceThe enforcement-chain narrative never listed MCP among the surfaces that reach object data. Added a "The MCP execution surface (ADR-0096 / ADR-0101)" subsection:
callDatawith the caller'sExecutionContext)./api/v1/mcp, ADR-0096): dispatcher resolves the same EC; nouserIdand notisSystem⇒ 401 (RFC 9728WWW-Authenticatewhen the OAuth track is live); OAuth token narrows tool families to granted scopes (403 on none). Enforcement:http-dispatcher.tshandleMcp+buildMcpBridge(context).systembypass. Enforcement:mcp/plugin.tsstart().enforcedconformance-matrix rows (mcp-http-identity,mcp-stdio-authority); added ADR-0096/0101 to the ADR index.Accuracy basis
Every claim traced to code:
packages/runtime/src/http-dispatcher.ts(handleMcp, 401/403 admission,buildMcpBridge),packages/mcp/src/plugin.ts(resolveStdioExecutionContext→resolveAuthzContext, fail-closedstart()), and themcp-http-identity/mcp-stdio-authorityrows inpackages/qa/dogfood/test/authz-conformance.matrix.ts. Env-var names matchcontent/docs/deployment/environment-variables.mdx.Testing
node scripts/check-doc-authoring.mjs→ clean (200 files)./adr/0096-…,/adr/0101-…) follow the 10 existing/adr/00xx-…precedents in the same file; both target files exist.Notes
@objectstack/docsis private → no changeset.🤖 Generated with Claude Code
https://claude.ai/code/session_0115eg8dAaCfWaDYYAm3ma36
Generated by Claude Code