MCP Track B Phase B0-B2: design inbound MCP architecture, auth, PRM, and governance

[Bionic711]

Summary

Implement the inbound SimpleChat MCP foundation from #1013: architecture decision, dedicated auth guard, Protected Resource Metadata (PRM), governance, roles, client allowlists, and explicit tool policy.

Scope

• Choose first production hosting model for inbound MCP.
• Prefer a first-class SimpleChat component/service layer initially, with optional later sidecar/container deployment.
• Keep MCP tool business logic behind reusable authorization-aware service functions.
• Start with streamable HTTP.
• Add a dedicated inbound MCP auth guard without broadening accesstoken_required.
• Validate token issuer, tenant, expiration, and audience.
• Require a dedicated inbound MCP role/scope or deliberately reused ExternalApi role.
• Add approved caller app ID allowlist.
• Separate app-only and delegated user access.
• Reject app-only tokens for user-data tools unless a future admin-only operation is explicitly designed.
• Add .well-known/oauth-protected-resource metadata.
• Add governance settings for global enablement, per-client enablement, per-tool allowlists, per-scope allowlists, and optional rate limits.
• Build an explicit inbound MCP tool registry with required identity type, workspace scope, feature flags, governance keys, rate-limit category, and audit event type.

Acceptance Criteria

• Inbound MCP has a documented architecture choice and deployment boundary.
• Auth failures are distinct from governance denials.
• Token validation includes issuer, audience, expiration, tenant, role/scope, and caller app ID checks.
• App-only tokens cannot access personal user data tools.
• PRM metadata is available and does not expose secrets, internal endpoints, or raw settings.
• Governance denies by default when client, tool, or scope is not configured.
• Tests cover missing token, malformed token, expired token, invalid issuer, invalid audience, missing role/scope, disallowed app ID, app-only rejection for user data, delegated token acceptance, disabled global setting, disabled client, disabled tool, and disabled scope.

Notes

Parent: #1013
Prototype/reference PR: #722 should inform intent only; do not copy its implementation directly.
Planning doc: docs/explanation/features/MCP_PLUGIN_ROBUSTNESS_PLAN.md
Priority: P1
Size: XL

[Bionic711]

MCP planning checkpoint update:

• Track B Phase B0/B1 planning is complete and documented in docs\explanation\features\INBOUND_MCP_SERVER_ARCHITECTURE.md.
• The master plan now carries the inbound architecture/auth foundation forward in docs\explanation\features\MCP_PLUGIN_ROBUSTNESS_PLAN.md.
• Added explicit future requirements for fine-grained inbound tool/resource exposure governance:
  • per tool/resource family/operation,
  • per caller user/group segment,
  • per specific group or wildcard group target,
  • explicit deny wins, missing policy denies,
  • governance does not bypass existing workspace authorization.
• Added source allowlisting requirements for inbound MCP clients:
  • allow * for identity-only deployments,
  • treat token/client identity as primary,
  • treat origin/user-agent/custom headers as supplemental unless injected or signed by trusted infrastructure.
• Next executable Track B slice remains a disabled inbound MCP shell with PRM, health, auth guard, and governance skeletons before exposing any tools.

[Bionic711]

Implementation checkpoint: disabled inbound MCP shell is now in place.

What changed:

• Added disabled-by-default inbound MCP config in application/single_app/config.py and bumped the app version to 0.250.063.
• Added a dedicated inbound MCP bearer-token guard in functions_mcp_server_auth.py with client allowlist, tenant checks, required role/scope checks, and source allowlist scaffolding.
• Added deny-by-default governance and no-enabled-tools registry skeletons in functions_mcp_server_governance.py and functions_mcp_server_registry.py.
• Added route_inbound_mcp.py with:
  • public PRM metadata route,
  • authenticated /api/mcp/health shell route,
  • authenticated /api/mcp shell endpoint that returns no tools.
• Registered the inbound_mcp Blueprint with a dedicated auth policy and updated route policy tests.
• Updated the inbound MCP architecture/master plan docs and release notes for v0.250.063.

Validation:

• python -m py_compile ... for changed Python files and route tests passed.
• python functional_tests/test_inbound_mcp_server_shell.py passed.
• python functional_tests/route_tests/test_route_blueprint_policy_inventory.py passed.
• python functional_tests/route_tests/test_route_unauthenticated_policy_contract.py passed.
• python functional_tests/route_tests/test_route_policy_test_coverage.py passed.
• git diff --check passed.

Important behavior:

• No inbound MCP tools are exposed yet.
• ENABLE_INBOUND_MCP_SERVER=false remains the default.
• The shell establishes route/auth/governance/registry foundations before any read tools are added.

Next candidate slice:

• Track B Phase B2/B3: durable inbound MCP governance evaluation plus the first read-only personal tool behind delegated identity, client/source allowlisting, SimpleChat governance allow, existing object authorization, audit logging, and negative tests for disabled group/public/all scopes.