MCP Integration

Audience

Integration developers and operators routing MCP tool calls through the HELM AI Kernel firewall/quarantine path.

Outcome

After this page you should know what this surface is for, which source files own the behavior, which public route or adjacent page to use next, and which validation command to run before changing the claim.

Source Truth

• Public route: helm-ai-kernel/integrations/mcp
• Source document: helm-ai-kernel/docs/INTEGRATIONS/mcp.md
• Public manifest: helm-ai-kernel/docs/public-docs.manifest.json
• Source inventory: helm-ai-kernel/docs/source-inventory.manifest.json
• Validation: make docs-coverage, make docs-truth, and npm run coverage:inventory from docs-platform

Do not expand this page with unsupported product, SDK, deployment, compliance, or integration claims unless the inventory manifest points to code, schemas, tests, examples, or an owner doc that proves the claim.

Troubleshooting

Diagram

This scheme maps the main sections of MCP Integration in reading order.

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["MCP Integration"]
        B["OAuth Resource and Scope Enforcement"]
        C["Build a Bundle"]
        D["Install a Local Client Configuration"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        A["Run the Server"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C
    C --> D

    %% Premium Styling Rules
    style A fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff

flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        Page["MCP Integration"]
        B["OAuth Resource and Scope Enforcement"]
        C["Build a Bundle"]
        D["Install a Local Client Configuration"]
    end

    subgraph Execution["3. Execution & Verdict Plane"]
        A["Run the Server"]
    end

    %% Operational Flow Edges
    Page --> A
    A --> B
    B --> C
    C --> D

    %% Premium Styling Rules
    style A fill:#3182ce,stroke:#2b6cb0,stroke-width:2px,color:#fff

HELM retains an MCP surface for governed tool access.

The local boundary quickstart remains the entry point:

helm-ai-kernel serve --policy ./release.high_risk.v3.toml

Run the Server

./bin/helm-ai-kernel mcp serve

OAuth Resource and Scope Enforcement

./bin/helm-ai-kernel mcp serve --auth oauth supports production JWKS validation and the dev-only HELM_OAUTH_BEARER_TOKEN fallback. Production mode validates issuer, audience, expiration, issued-at, configured global scopes, and the MCP resource indicator before forwarding the request to the gateway.

Configure production OAuth with:

Tool definitions may also declare required_scopes. These are surfaced to MCP clients as requiredScopes in tools/list and are enforced again at execution time for both /mcp/v1/execute and JSON-RPC tools/call. A missing per-tool scope returns MCP.OAUTH.INSUFFICIENT_SCOPE on the REST surface or a JSON-RPC application error on the streamable MCP surface.

The resource check follows RFC 8707: the MCP gateway treats the token audience plus resource / resources token members as accepted resource indicators and rejects tokens that are not minted for this MCP endpoint.

Build a Bundle

./bin/helm-ai-kernel mcp pack --client claude-desktop --out helm-ai-kernel.mcpb

Install a Local Client Configuration

./bin/helm-ai-kernel mcp install --client claude-code

Use ./bin/helm-ai-kernel mcp print-config --client <name> for text configuration snippets where supported by the CLI.

Quarantine and Schema Pins

Unknown MCP servers are quarantined by default. A call is dispatchable only after server discovery, metadata/schema inspection, risk classification, approval bound to a HELM receipt, and a matching pinned schema hash.

The maintained local demo covers this full path:

./scripts/launch/demo-mcp.sh

The demo asserts that unknown servers, unknown tools, and missing schema pins return DENY or ESCALATE; they never dispatch to the fixture server.

MCP activity that emits receipts can be inspected with:

helm-ai-kernel receipts tail --agent <agent-id>

MCP Integration Checklist

A complete MCP integration claim includes the transport, tool list, input schema, output schema, receipt behavior, denial behavior, and a validation command. The public example must show at least one allowed call and one policy-denied call, with the receipt or diagnostic ID a developer should capture. Keep model-provider setup separate from MCP governance: the server exposes a controlled tool boundary, while HELM owns policy evaluation, evidence capture, and verifier replay. If a tool is experimental, mark it as such and keep it out of conformance tables until it has schema and fixture coverage.