Support method-level governance for MCP tool calls (JSON-RPC) in sandbox policy

[prakashmirji]

Problem Statement

Problem
The current sandbox policy supports network rules (allow/deny TCP connections to hosts/ports), filesystem rules, and process rules. However, when an agent communicates with MCP (Model Context Protocol) tool servers, the actual tool invocations are JSON-RPC calls over a single TCP connection. The policy cannot distinguish between different MCP methods on the same connection.

Current Behavior
Policy can only allow/deny at the network level:

network:
  - host: "10.200.0.1"
    port: 8001
    access: full  # All-or-nothing: either ALL methods are allowed, or NONE

Once a connection is allowed, the agent can call any method on that MCP server — there's no way to restrict which tools/methods are permitted.

Proposed Design

Desired Behavior
Extend the policy language to support method-level filtering for JSON-RPC/MCP traffic:

network:
  - host: "10.200.0.1"
    port: 8001
    access: full
    methods:
      allow:
        - "tools/call:search_web"      # Allow Tavily search
        - "tools/call:get_weather"     # Allow weather lookup
      deny:
        - "tools/call:send_email"      # Block email sending
        - "tools/call:execute_code"    # Block code execution

The supervisor would need to:

1. Detect JSON-RPC traffic on governed connections (Content-Type or protocol detection)
2. Parse the JSON-RPC method and params.name fields
3. Apply allow/deny rules before forwarding to the MCP server
4. Log/audit which methods were called (for governance compliance)

Alternatives Considered

Use Case
Enterprise governance requires fine-grained control over what an AI agent can do — not just which services it can connect to, but which specific operations it can perform. This is critical for:

• Compliance (agent can read but not write)
• Safety (agent can search but not send emails)
• Least-privilege (agent only gets the specific tools it needs)
• Audit trail (which methods were invoked, by which user, when)

Workaround
We built an external "MCP Governance Gateway" that sits between the agent and the MCP server, intercepts JSON-RPC calls, and enforces method-level policy. This works but adds latency, deployment complexity, and doesn't benefit from the supervisor's built-in audit/policy infrastructure.

Agent Investigation

No response

Checklist

• I've reviewed existing issues and the architecture docs
• This is a design proposal, not a "please build this" request

[rpelevin]

Method-level filtering is the right direction here. The important boundary I would make explicit is that raw TCP access and raw JSON-RPC method names are still too coarse unless the sandbox also understands the resolved MCP tool call.

For MCP traffic, I would evaluate policy against a normalized call envelope before dispatch:

• sandbox profile id;
• MCP server identity;
• JSON-RPC request id;
• method, usually tools/call;
• resolved tool name;
• canonical args digest;
• read/write/destructive classification;
• decision: allow, deny, require approval;
• decision id recorded in the sandbox log;
• expiry or policy version.

The proxy can still enforce at the JSON-RPC layer, but the policy key should be server + tool + args digest + policy version, not just host + port + method.

Acceptance tests I would want:

• the same MCP connection allows search_web but denies send_email;
• tools/list is allowed without implying that every listed tool is callable;
• changed args no longer match a prior approval;
• renamed or newly discovered tools fail closed until policy is refreshed;
• denied calls never reach the upstream MCP server;
• the sandbox log records the resolved tool name and decision id without storing secrets.

That keeps the network sandbox useful while avoiding an all-or-nothing MCP server grant.

[johntmyers]

related: #1531

For a first iteration, would JSON-RPC over HTTP be a good injection point?

[rpelevin]

Yes, JSON-RPC over HTTP seems like a good first injection point for v1, as long as the policy core is not designed as "HTTP-specific."

The clean split I would use:

• transport adapter: intercept JSON-RPC over HTTP before forwarding upstream;
• MCP normalizer: parse method, request id, and params.name / params.arguments for tools/call;
• policy evaluator: decide against the normalized MCP call envelope;
• dispatcher: forward only if the decision is allow.

For v1, I would keep the enforcement narrow:

1. allow tools/list and other metadata methods by default, but do not treat listing as authority to call every tool.
2. for tools/call, resolve the server identity, tool name, canonical args digest, policy version, and sandbox profile.
3. if decision is deny, return a structured JSON-RPC error or MCP tool error without forwarding upstream.
4. if decision is require_approval, return an approval-required response without forwarding upstream.
5. if decision is allow, forward the original request unchanged and log the decision id.

The main caution: HTTP should be the first adapter, not the policy boundary. Later stdio, websocket, or in-process MCP paths should feed the same normalized envelope into the same evaluator.

Tests I would add:

• tools/list succeeds but does not grant execution authority.
• tools/call:search_web forwards while tools/call:send_email is denied on the same server connection.
• denied and approval-required calls never reach the upstream MCP server.
• changed args produce a different digest and cannot reuse a prior approval.
• unknown or newly discovered tools fail closed until policy is refreshed.
• the sandbox log records transport, server id, tool name, decision id, and args digest without storing raw secrets.

So: yes for JSON-RPC over HTTP as the first interception layer, but I would make the durable abstraction "normalized MCP tool-call envelope before dispatch."

[johntmyers]

Something like this:

version: 1

network_policies:
  github_mcp_jsonrpc:
    name: github_mcp_jsonrpc
    endpoints:
      - host: mcp-github.internal.example.com
        port: 443
        path: /mcp
        protocol: json-rpc
        enforcement: enforce

        json_rpc:
          max_body_bytes: 65536
          on_parse_error: deny
          batch_policy: deny_if_any_denied

        rules:
          - allow:
              rpc_method: initialize

          - allow:
              rpc_method: tools/list

          - allow:
              rpc_method: tools/call
              params:
                name:
                  any:
                    - get_*
                    - list_*
                    - search_*

          - allow:
              rpc_method: tools/call
              params:
                name: create_issue
                arguments.repository: NVIDIA/OpenShell

        deny_rules:
          - rpc_method: tools/call
            params:
              name:
                any:
                  - delete_*
                  - push_*
                  - create_pull_request
                  - execute_code

    binaries:
      - path: /usr/local/bin/claude
      - path: /usr/bin/node

For a first iteration, some thoughts:

• no supervisor *.local listener
• focus on a json-rpc protocol vs mcp as first class. still a lot of changes coming with MCP. based on the recent community call we agreed that we will wait for first-class mcp support based on pending changes
• logs should record endpoint, rpc method, args digest, policy version

[rpelevin]

Yes, this is the shape I would expect for a first iteration. I especially like keeping the first policy surface as protocol: json-rpc rather than making MCP itself the first-class policy object too early.

A few boundaries I would pin in the YAML / tests:

• protocol: json-rpc is the parser/enforcement profile; the decision record should still capture endpoint, RPC method, parsed target fields, args digest, policy version, and decision outcome.
• for tools/call, params.name matching is a good v1 start, but compute the args digest before decision/logging even if v1 only matches selected argument fields.
• batch_policy: deny_if_any_denied is a good default; test that no allowed item from a mixed batch is forwarded before every item has been parsed and decided.
• on_parse_error: deny should return a structured JSON-RPC error and log parser_failure, not fall back to the network allow rule.
• rule precedence should be deterministic. I would either make explicit deny win or define most-specific-rule wins, but avoid order-dependent surprises.
• logs should include endpoint, RPC method, resolved tool name when available, args digest, policy version, decision id/outcome, and avoid raw args by default.

The useful v1 test set seems small:

1. initialize and tools/list pass.
2. allowed tools/call forwards unchanged.
3. denied tools/call never reaches upstream.
4. malformed JSON-RPC fails closed with a structured error.
5. mixed batch with one denied call forwards none, or at least follows the documented batch policy exactly.
6. changed args produce a different digest in the log.
7. allow/deny conflict resolves deterministically.

That keeps the first iteration independent of MCP churn while preserving the later path: first parse JSON-RPC reliably, then let MCP-specific adapters feed richer normalized envelopes into the same evaluator.

[johntmyers]

rule precedence should be deterministic. I would either make explicit deny win or define most-specific-rule wins, but avoid order-dependent surprises.

This behavior already exists in our L7 parsers: explicit deny, explicit allow, implicit deny. So we would keep that. We already have rest and graphql parsers, this is just a new parser type, not changing rule evaluation behavior.

[rpelevin]

That makes sense. If REST, GraphQL, and JSON-RPC all share the same evaluator semantics, then the v1 JSON-RPC work can stay nicely bounded: parser in, normalized attributes out, existing rule evaluation unchanged.

I would probably make the acceptance tests parser-contract focused:

1. JSON-RPC parser returns the same decision enum shape as REST/GraphQL: explicit deny, explicit allow, implicit deny.
2. explicit deny for tools/call wins over an allow wildcard.
3. no matching rule becomes implicit deny, with a logged decision id/outcome.
4. parse failure maps to deny plus parser_failure, without falling through to network allow.
5. allowed JSON-RPC call forwards the original request unchanged after decision.
6. denied or implicit-deny calls never reach upstream.
7. log shape stays consistent across parser types: endpoint, parser type, RPC method, resolved target fields when available, args digest, policy version, decision id/outcome.

Then JSON-RPC is just another L7 parser contract, and later MCP-specific support can enrich the normalized attributes without forking policy semantics.

[ddurst-nvidia]

I'm reacting to this issue so far as a whole, but I generally like the "JSON-RPC is just another L7 parser contract" approach @rpelevin, with not much in the way of MCP associated with it. Maybe there's syntactic sugar for MCP at some point, and that could be separate.

One aspect of this shape I'm not seeing, is the bi-directional nature of a JSON-RPC 2.0 connection. I don't know if the lack of "direction" in the policy shapes above (agent->mcp_server vs mcp_server->agent), is intentional or not, or meant to apply in both directions. As I see it above, tool calls would never be able to issue a result. I don't know which direction of the stream, the rules apply, or how a Task progress would be expressed.

With the MCP case, mcp_server->agent is used by MCP (elicitation, roots and sampling requests - all of which are reasonable to apply policy upon, since they allow the MCP server, to gather information from the agent, and potentially forward it to inference).

I would like to see a params approach similar to method (unfortunately with more complexity), if "JSON-RPC is just another L7 parser contract." If that spawns to a different issue, I think that's fine as well.

I would ultimately use the mcp conformance tests as part of the cycle here, since that's likely the 99% case for JSON-RPC, within OpenShell.