---
title: "MCP Integration"
canonical: "https://helm.docs.mindburn.org/integrations/mcp"
source: "helm-ai-enterprise/docs/public/product/integrations/mcp.md"
edit: "https://github.com/Mindburn-Labs/helm-ai-enterprise/edit/main/docs/public/product/integrations/mcp.md"
section: "reference"
access: "public"
sensitivity: "public"
last_reviewed: "2026-05-04"
checksum_sha256: "sha256:a9e5db503dbdfe510da36fbeef5f1402ca42b1402fc3f5d84c5706acf22293fc"
build_timestamp: "2026-05-24T13:40:27.882Z"
---
# Integration: Model Context Protocol

## Audience

## 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.

## Troubleshooting

| Symptom | First check |
| --- | --- |
| A link or route is missing from the docs website | Check `docs/public-docs.manifest.json`, `llms.txt`, search, and the per-page Markdown export before changing navigation. |
| A claim is not backed by code or tests | Remove the claim or add the missing code, example, schema, or validation command before publishing. |

HELM can sit in front of MCP-capable tools so agent clients discover tools normally while execution still passes through policy, schema, budget, and receipt controls.

## Discovery

```bash
curl -s http://localhost:8080/mcp/v1/capabilities | jq '.tools[].name'
```

Expected output is a list of governed tools exposed by the active bundle. If the list includes private tools you did not intend to expose, stop and fix the bundle before executing anything.

## Governed Tool Call

```bash
curl -s -X POST http://localhost:8080/mcp/v1/execute \
  -H 'Content-Type: application/json' \
  -d '{"method":"file_read","params":{"path":"/tmp/test.txt"}}' | jq .
```

Expected allowed shape:

```json
{
  "result": "...",
  "receipt_id": "rec_...",
  "reason_code": "ALLOW"
}
```

## Denied Tool Call

```bash
curl -s -X POST http://localhost:8080/mcp/v1/execute \
  -H 'Content-Type: application/json' \
  -d '{"method":"unknown_tool","params":{}}' | jq .
```

Expected denied shape:

```json
{
  "error": {
    "message": "Tool not found: unknown_tool",
    "reason_code": "DENY_TOOL_NOT_FOUND"
  }
}
```

## What HELM Adds

- schema validation for MCP inputs and outputs;
- policy decisions before execution;
- budget and effect-level checks;
- signed receipts and proof graph links;
- replayable evidence for audits;
- explicit deny or escalation semantics instead of silent framework fallback.

## Private MCP Tunnels

Claude Managed Agents private MCP tunnels are supported only when the tunnel
hostname routes to the HELM MCP Gateway. The gateway remains the policy point:
schema pinning, OAuth resource and scope checks, quarantine/rugpull controls,
tool visibility filtering, args hashing, receipt emission, and
`ExecutionBoundaryRecord` binding.

Direct tunnel targets to internal MCP servers are treated as bypass attempts and
must fail closed. Preview evidence for a tunneled call should include the tunnel
domain hash, upstream MCP server ID, OAuth resource, required scopes, protocol
version, CA or certificate reference hash, allowed upstream hostname or CIDR
hash, and the receipt ID for the allowed or denied tool call.

## Failure Modes

| Symptom | Cause | Fix |
| --- | --- | --- |
| capability list is empty | no bundle or MCP gateway not loaded | check runtime logs and active policy bundle |
| unknown tool is allowed | request bypassed HELM or policy is too broad | route through HELM MCP endpoint and tighten bundle |
| no receipt on allowed call | call is discovery-only or not governed | execute through `/mcp/v1/execute` and inspect runtime receipt logs |
| agent sees private tools | manifest exposes too much | reduce tool manifest and rerun discovery |
| managed-agent tunnel bypasses HELM | tunnel points at a raw MCP server | route the tunnel hostname to HELM MCP Gateway and pin the upstream profile |

## Source Truth

This page must stay aligned with the OSS MCP integration and OWASP MCP threat mapping. If MCP protocol details change, update the gateway, examples, and schema references together.

## Diagram

```mermaid
flowchart TD
    subgraph Ingestion["1. Ingestion & Context Plane"]
        source["Integration: Model Context Protocol"]
        s0["Discovery"]
        s1["Governed Tool Call"]
        s2["Denied Tool Call"]
        s3["What HELM Adds"]
        output["Reader outcome"]
    end

    %% Operational Flow Edges
    source --> s0
    s0 --> s1
    s1 --> s2
    s2 --> s3
    s3 --> output

    %% Premium Styling Rules
```


## Operational Readiness

Use this page as the public operating layer for **MCP Integration**. The source of truth is `helm-ai-enterprise/docs/public/product/integrations/mcp.md`; if this page and the implementation disagree, update the source-backed doc and rerun the validation command before publishing.

Before relying on this surface, confirm three things: the source path above still exists, the referenced commands or contracts are still present in the owning repo, and the docs-platform export surfaces still show this page in search, Markdown, `llms-full.txt`, and MCP without exposing protected routes.

Validation command: `corepack pnpm run docs:coverage && corepack pnpm run docs:truth`. For website parity, also run `npm run exports:boundary` and `npm run thin-pages:check` from `docs-platform`.

### Expected Output

A reader should leave with a concrete next action, the source file or contract to inspect, the command that proves the claim, and a clear boundary for what is public versus protected. For reference pages, the expected output is a correctly scoped request, schema, command, or diagnostic path. For operations pages, the expected output is a reproducible readiness or failure signal that can be attached to an evaluation or support thread.

### Failure Modes

If the validation command fails, do not patch this page in isolation. First identify whether the drift is in code, generated contracts, source-owner docs, or the docs manifest. If the public page needs a protected deep link, describe the protected document by name instead of exposing its route. Commercial operator details, tenant data, key ceremonies, and deployment-sensitive internals stay in protected customer or staff docs; this public page only exposes the safe developer contract.