feat(policy): add MCP-aware JSON-RPC L7 governance

[ddurst-nvidia]

Summary

Builds on #1865 by keeping its shared JSON-RPC-family L7 enforcement foundation and adding an MCP-specific policy surface on top of it.

PR #1865 introduces generic JSON-RPC method/params enforcement. This variant preserves generic JSON-RPC as a first-class supported protocol for non-MCP services, while adding MCP-specific policy spelling, MCP validation via tower-mcp-types, and conformance-oriented e2e behavior.

Related Issue

Addresses #1793.

Builds on #1865.

Changes

Relationship to #1865

PR #1865 adds the shared JSON-RPC-family L7 enforcement layer. This branch builds on that layer with an MCP-specific policy surface and MCP message validation via tower-mcp-types, while preserving generic JSON-RPC as a first-class supported protocol for non-MCP services.

How This Addresses #1793

Issue #1793 asks for method-level governance for MCP tool calls because MCP traffic is carried as JSON-RPC over a single allowed connection, making network-only policy all-or-nothing.

This branch addresses that by allowing policy to distinguish MCP requests inside the connection:

• mcp_method filters MCP/JSON-RPC method names such as tools/call.
• tool filters MCP tool calls by params.name.
• Nested params matchers allow policy to constrain scalar MCP params such as arguments.scope.
• Allow and deny rules are evaluated before forwarding to the MCP server.
• MCP traffic remains in OpenShell's existing policy/audit path instead of requiring an external governance gateway.

Key Differences

• Adds protocol: mcp while preserving protocol: json-rpc.
• Adds MCP policy fields:
  • mcp.max_body_bytes
  • mcp_method
  • tool
  • nested params maps for MCP readability.
• Uses tower-mcp-types to validate known MCP request/notification shapes.
• Keeps generic JSON-RPC parsing intentionally protocol-neutral for non-MCP JSON-RPC servers.
• Keeps enforcement on the existing OPA path by compiling MCP aliases back to the current JSON-RPC-family rule model.

Rule / OPA Tightening

• mcp_method normalizes to the existing rpc_method field, so OPA has one method-matching path.
• tool normalizes to MCP params.name, but only when params.name was not explicitly set.
• Nested MCP params are flattened before OPA evaluation, preserving the existing scalar matcher behavior.
• Literal dotted request param keys are rejected to avoid ambiguous collisions with flattened nested paths.
• JSON-RPC/MCP params matching remains restricted to protocol: json-rpc or protocol: mcp.
• MCP request parsing validates known MCP method params before policy evaluation.
• Methodless MCP Streamable HTTP receive streams and client JSON-RPC responses are allowed only as a narrow 2025-11-25 conformance compatibility path after host, path, binary, endpoint protocol, and parse-shape checks. MCP 2026-07-28 (draft) removes the GET stream endpoint and client-sent JSON-RPC responses, so this allowance should be version-gated or removed when OpenShell enforces that transport version.

Type Enforcement Follow-up

This branch does not add typed MCP argument enforcement. The current L7 JSON-RPC-family policy input flattens scalar params into string values before OPA evaluation, so 1 and "1" or true and "true" are not distinguishable by policy today.

Typed argument enforcement would be better handled as a wider L7 policy input change, for example by preserving scalar JSON type metadata alongside the existing flattened matcher keys. That would let a future MCP argument policy express type: integer or type: boolean without weakening the existing JSON-RPC compatibility path.

Conformance Notes

The MCP conformance policy template now uses:

protocol: mcp
mcp:
  max_body_bytes: 131072
rules:
  allow:
    - mcp_method: "*"

Expected-failure carve-outs are limited to one known upstream conformance-client behavior:

client:
  - elicitation-sep1034-client-defaults
server: []

Note

elicitation-sep1034-client-defaults is allowed to fail because the pinned upstream TypeScript conformance client appears to advertise elicitation.applyDefaults, while @modelcontextprotocol/sdk 1.29.0 applies defaults only for elicitation.form.applyDefaults. The failure reproduces with the upstream conformance client directly, without OpenShell in the path. The carve-out should be removed when OPENSHELL_MCP_CONFORMANCE_REF is bumped to an upstream commit where the bundled client advertises the corrected capability shape.

Testing

• mise run pre-commit passes
• Unit tests added/updated
• E2E tests added/updated (if applicable)

Local validation run for this branch includes:

• mise run e2e:mcp for the MCP conformance suite.
  • The suite exits successfully with one expected upstream-client failure: elicitation-sep1034-client-defaults.
• cargo test -p openshell-supervisor-network mcp_tool_deny_rule_blocks_tools_call
• cargo clippy -p openshell-supervisor-network --all-targets -- -D warnings
• cargo test -p openshell-policy
• cargo test -p openshell-supervisor-network

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[ddurst-nvidia]

@krishicks - Mostly for your review.

[ddurst-nvidia]

I don't have permissions to add the test:e2e label, but it would be appreciated if someone could add it.

[johntmyers]

protocol is already mcp, so why do we need it to be mcp_method here vs just method?

[ddurst-nvidia]

Good catch. Easy enough to remove, leaving unresolved until I can.

[ddurst-nvidia]

Resolved. You'll need to talk to @krishicks regarding rpc_method from #1865, I'm only building on top of that work.

[johntmyers]

this would be a deviation from a separate deny_rules block that sits at the same level as rules, is there a particular reason for that?

[ddurst-nvidia]

Particular reasons are:

• Support method-level governance for MCP tool calls (JSON-RPC) in sandbox policy #1793 's proposed design section.
• feat(l7): add JSON-RPC policy enforcement #1865 (comment)

But I'll address it more completely in the other comment.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[ddurst-nvidia]

Cleaned up the conformance fixture workarounds to align with modelcontextprotocol/conformance#346.