feat(policy): add MCP L7 inspection and enforcement #1531

Problem Statement

OpenShell has a growing L7 policy surface for agent traffic. REST can be scoped by method/path/query, GraphQL has a dedicated body-aware inspection proposal/implementation path (#1022), and MCP is now showing up in related work as a tool-permission modeling concern (#1058) and as an agentgateway integration surface (#998). What is missing is the parent runtime capability: MCP traffic and tool calls need to be inspectable and enforceable as first-class L7 policy decisions.

Without MCP inspection and enforcement, a sandbox policy can reason about a process reaching an MCP server or an upstream API endpoint, but not about the security-relevant action the agent is taking through MCP. That leaves a gap between network reachability and actual tool capability. For example, a policy may intend read-only GitHub access while an MCP server exposes write-capable tools such as issue creation, PR creation, or repository mutation.

This should be treated as the parent/prerequisite for #1058. The prover can model MCP tool permissions more usefully once the runtime policy surface defines what MCP operations are observed, how they are identified, and how allow/deny decisions are represented.

Proposed Design

Add MCP as a supported L7 policy surface alongside REST and GraphQL. The runtime should be able to inspect MCP sessions, identify tool discovery and tool invocation events, and enforce policy at the level operators care about: server identity, tool name, operation class, target resource, and request arguments where safe to inspect.

The policy model should support at least:

• MCP server identity: local alias such as mcp.local, configured upstream, or server name from the sandbox settings/profile.
• Tool inventory discovery: capture and expose available tools from tools/list or equivalent discovery flows.
• Tool invocation enforcement: allow/deny based on tool name, operation class, and optional argument/resource constraints.
• Capability mapping: map known MCP tools to underlying API effects where possible, e.g. GitHub MCP create_pull_request maps to a write action on POST /repos/*/pulls.
• Auditable denials: emit structured OCSF events for MCP allow/deny decisions, with dual-emitted findings for policy violations or suspicious tool use.
• Agent-readable feedback: MCP denials should return a useful error body/message so agents can revise proposed actions instead of failing opaquely.

A possible policy sketch:

endpoints:
  - host: mcp.local
    port: 443
    protocol: mcp
    enforcement: enforce
    rules:
      - allow:
          server: github
          tools: ["get_*", "list_*", "search_*"]
      - allow:
          server: github
          tools: ["create_issue"]
          resources:
            repositories: ["NVIDIA/OpenShell"]
    deny_rules:
      - server: github
        tools: ["delete_*", "push_*", "create_pull_request"]

Implementation can arrive in phases:

1. Define the MCP L7 protocol surface in policy types and validation: protocol: mcp, tool allow/deny shapes, and agent-readable denial semantics.
2. Inspect MCP tool discovery and invocation traffic on the sandbox runtime path, initially for the transport OpenShell supports first.
3. Add OCSF events for MCP tool discovery, invocation allow, invocation deny, and malformed/unsupported MCP messages.
4. Add first-party capability mapping for GitHub MCP as the initial modeled server.
5. Wire the resulting runtime model into OPP so OPP: MCP tool permission modeling #1058 can reason over observed/configured MCP tool permissions.

Related work:

• OPP: MCP tool permission modeling #1058 - OPP: MCP tool permission modeling. This issue should depend on the runtime inspection/enforcement surface described here.
• GraphQL-aware L7 inspection: operation-type and field-level policy rules #1022 - GraphQL-aware L7 inspection. Establishes GraphQL as a body-aware L7 peer to REST.
• feat(policy): suggest L7 scoping for known REST hosts #1099 - Suggest L7 scoping for known REST hosts. REST-side policy hinting that this issue should complement, not replace.
• feat: embed agentgateway in openshell-sandbox for inference + MCP #998 - Embed agentgateway in openshell-sandbox for inference + MCP. Prior MCP runtime integration direction, now closed.
• feat(sandbox): L7 content inspection hooks — scriptable request/response filtering #1272 - L7 content inspection hooks. Complementary body/content inspection; MCP enforcement is about protocol/tool semantics.

Alternatives Considered

• Model MCP only in OPP (OPP: MCP tool permission modeling #1058). This helps analysis, but it does not give the runtime a place to observe and enforce MCP tool use. The prover would be reasoning over an incomplete or out-of-band model.
• Treat MCP as generic REST/HTTP. This can enforce coarse host/path constraints, but it misses the tool semantics that make MCP security-relevant.
• Rely on MCP server-side authorization only. Upstream authorization remains important, but OpenShell needs sandbox-local policy enforcement so agents receive least-privilege capabilities even when a credential or MCP server exposes more authority than intended.
• Wait for agentgateway to own all MCP policy semantics. Agentgateway may be the right integration path, but OpenShell still needs a stable policy model, OCSF semantics, and prover-visible representation for MCP decisions.

Agent Investigation

• Searched current issues for MCP, L7, GraphQL, REST + GraphQL + MCP, and L7 surface terminology.
• Found OPP: MCP tool permission modeling #1058 open for MCP tool permission modeling in OPP. It describes the exact tool-capability problem but sits at the prover/modeling layer.
• Found GraphQL-aware L7 inspection: operation-type and field-level policy rules #1022 closed for GraphQL-aware L7 inspection, establishing GraphQL as a body-aware peer to REST.
• Found feat(policy): suggest L7 scoping for known REST hosts #1099 open for suggesting L7 scoping for known REST hosts.
• Found feat: embed agentgateway in openshell-sandbox for inference + MCP #998 closed for embedding agentgateway in openshell-sandbox for inference + MCP, including a proposed mcp.local listener.
• Found feat(sandbox): L7 content inspection hooks — scriptable request/response filtering #1272 open for general L7 content inspection hooks, which is adjacent but focused on content scanning rather than MCP protocol/tool semantics.
• Did not find a single open umbrella issue for MCP as a first-class supported L7 inspection/enforcement surface.

Checklist

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