Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<img src="docs/assets/icon.svg" width="96" height="96" alt="cMCP"/>
</p>

# cMCP
# cMCP: Confidential MCP Runtime

### Enforce MCP tool policy where it cannot be tampered with

Expand All @@ -26,6 +26,8 @@

> **Developer Preview** - launching at Confidential Computing Summit, June 23 2026. May have breaking changes before v1.0.

Your agent calls Snowflake, Salesforce, a dozen APIs. What stops it from leaking a customer's data on one of those calls? If a regulator asks, could you prove it didn't?

---

## The problem
Expand All @@ -40,6 +42,10 @@ None of that proves the policy engine itself was not compromised. Software-only

The control plane that governs tool calls must run where it cannot be reached by the process it governs.

Hardware-attested policy enforcement for MCP tool calls. Every tool call is intercepted, evaluated against a Cedar policy bundle, and enforced by a policy engine running inside a Trusted Execution Environment (TEE). The policy bundle hash is measured into the hardware attestation report before any code runs.

Unlike tunnel-based connectivity solutions, the cMCP Runtime processes tool-call payloads inside the TEE. The connectivity provider sees ciphertext, not plaintext. The only thing that leaves the enclave is the signed TRACE claim.

---

## Quick Start
Expand Down Expand Up @@ -84,7 +90,7 @@ See [docs/quickstart.md](docs/quickstart.md) for the full walkthrough: Cedar pol
4. At the end of the session the gateway produces a TRACE Claim: a signed, hardware-attested artifact that records which tools ran, which policy decided each call, and the full audit chain. A verifier checks this without trusting the operator.

```
Agent -> cMCP Gateway -> Cedar Policy Engine (TEE) -> Tool
Agent -> cMCP Runtime -> Cedar Policy Engine (TEE) -> Tool
|
GatewayClaim (TRACE Profile)
+-- trace.eat_profile
Expand All @@ -105,7 +111,7 @@ Agent -> cMCP Gateway -> Cedar Policy Engine (TEE) -> Tool
| `sev-snp` | AMD SEV-SNP (Azure DCasv5, AWS C6a Nitro) | High | AMD KDS |
| `tdx` | Intel TDX (Azure DCedsv5, GCP C3) | High | Intel PCS |
| `gpu-cc` _(v0.2)_ | NVIDIA H100/H200/Blackwell (CC mode) | High | NVIDIA Remote Attestation Service (NRAS) |
| `opaque` _(explicit opt-in)_ | Opaque Managed Runtime | High | Set `OPAQUE_ATTESTATION_URL`; not in auto-detect chain |
| `opaque` _(explicit opt-in)_ | OPAQUE Confidential Runtime | High | Set `OPAQUE_ATTESTATION_URL`; not in auto-detect chain (stub: detect() returns False, not yet implemented) |

Provider auto-detects: `SEV-SNP -> TDX -> TPM -> software`. `opaque` is explicit opt-in via `OPAQUE_ATTESTATION_URL` and is never selected automatically.

Expand Down
22 changes: 11 additions & 11 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# cMCP Spec
# cMCP Spec

cMCP Gateway is a hardware-attested MCP (Model Context Protocol) gateway. Every MCP tool call an agent makes passes through a TEE-isolated gateway that evaluates it against a Cedar policy bundle and produces a TRACE Claim: a signed, hardware-attested proof artifact a verifier can check without trusting the operator.
cMCP Runtime is a hardware-attested MCP (Model Context Protocol) runtime. Every MCP tool call an agent makes passes through a TEE-isolated gateway that evaluates it against a Cedar policy bundle and produces a TRACE Claim: a signed, hardware-attested proof artifact a verifier can check without trusting the operator.

Phase 1 attests the agent-to-tool boundary on the consumer side (the gateway). Phase 2 attests it on the provider side (the server). Together they close the proof gap that software-only gateways leave open: "prove that the policy you describe in documents is the policy that actually ran on your traffic."
Phase 1 attests the agent-to-tool boundary on the consumer side (the runtime). Phase 2 attests it on the provider side (the server). Together they close the proof gap that software-only runtimes leave open: "prove that the policy you describe in documents is the policy that actually ran on your traffic."

This repository contains the product specification. Implementation lives in a separate repo.

Expand All @@ -13,11 +13,11 @@ This repository contains the product specification. Implementation lives in a se
**Understanding the problem space:**
Read SPEC.md. It defines the four problems (P1 data leakage, P2 unsanctioned tools, P3 provable governance, P4 supply chain), the 13 threat shapes, and the coverage matrix showing what Phase 1 closes vs. what Phase 2 closes.

**Implementing the gateway (Phase 1):**
**Implementing the runtime (Phase 1):**
Read in this order:
1. SPEC.md — problem context and scope
2. docs/spec/component-model.md — what you are building and where trust boundaries are
3. docs/spec/transport.md — how the gateway intercepts MCP traffic
3. docs/spec/transport.md — how the runtime intercepts MCP traffic
4. docs/spec/attestation.md — how TEE attestation works and how to produce TRACE Claims
5. docs/spec/cedar-policy.md — the policy engine, bundle format, and enforcement modes
6. docs/spec/failure-modes.md — what happens when things go wrong
Expand All @@ -38,11 +38,11 @@ Issues in this repo track spec decisions, not implementation bugs. Each issue co
| docs/spec/attestation.md | TEE provider detection, audit chain, key management, catalog pinning | 1 | Draft v0.1 | #5, #6, #23, #33, #38 |
| docs/spec/cedar-policy.md | Policy bundle format, Cedar examples, enforcement modes, provenance | 1 | Draft v0.1 | #4, #7, #26, #39, #41 |
| docs/spec/tool-identity.md | Server identity binding, catalog schema, collision detection | 1 | Draft v0.1 | #40 |
| docs/spec/failure-modes.md | Gateway failure scenarios, decision table, log formats | 1 | Draft v0.1 | #22 |
| docs/spec/failure-modes.md | Runtime failure scenarios, decision table, log formats | 1 | Draft v0.1 | #22 |
| docs/spec/call-graph.md | Tag-propagation model, observability limits, cross-boundary policy | 1 | Draft v0.1 | #35 |
| docs/spec/session-policy.md | Session sensitivity state machine, egress policy, session reset | 1 | Draft v0.1 | #36 |
| docs/spec/response-inspection.md | 4-stage response inspection pipeline, injection patterns | 1 | Draft v0.1 | #37 |
| docs/spec/error-codes.md | Central error code registry for all gateway and verification errors | 1+2 | Draft v0.1 | — |
| docs/spec/error-codes.md | Central error code registry for all runtime and verification errors | 1+2 | Draft v0.1 | — |
| docs/spec/threat-model.md | Assets, adversaries, STRIDE analysis per component | 1 | Draft v0.1 | #18, #24 |
| docs/spec/verification-library.md | cmcp-verify Python library interface and per-provider verification steps | 1 | Draft v0.1 | #25 |
| docs/spec/mcp-spec-strategy.md | MCP spec monitoring and attestation extension contribution window | 1+2 | Draft v0.1 | #30 |
Expand Down Expand Up @@ -105,14 +105,14 @@ A conforming implementation passes all MUST-level tests. SHOULD-level tests indi

| Term | Definition |
|------|-----------|
| TRACE Claim | The signed, hardware-attested proof artifact produced by the gateway per session |
| TRACE Claim | The signed, hardware-attested proof artifact produced by the runtime per session |
| TEE | Trusted Execution Environment (TPM, SEV-SNP, TDX, or Opaque Managed) |
| SPIFFE SVID | Short-lived cryptographic identity issued by SPIRE after TEE attestation succeeds |
| Cedar | The policy language used for tool call authorization |
| Audit chain | The append-only hash-chained log of all gateway decisions, signed with a TEE-sealed key |
| Audit chain | The append-only hash-chained log of all runtime decisions, signed with a TEE-sealed key |
| Session sensitivity | The maximum sensitivity level seen in any tool response within the current session |
| Tag-propagation | The gateway's mechanism for tracking sensitivity across calls based on observable events |
| Catalog entry | The gateway's approved record for one tool: name, server identity, approved definition |
| Tag-propagation | The runtime's mechanism for tracking sensitivity across calls based on observable events |
| Catalog entry | The runtime's approved record for one tool: name, server identity, approved definition |
| Attestation report | The hardware-produced evidence that a specific binary ran in a specific TEE at a specific time |
| policy_bundle_hash | SHA-256 of the canonical Cedar policy bundle, measured into the TEE at startup |
| tool_catalog_hash | SHA-256 of the canonical tool catalog, measured into the TEE at startup |
Expand Down
10 changes: 5 additions & 5 deletions docs/SPEC.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# cMCP Gateway - Product Specification
# cMCP Runtime - Product Specification

Status: Draft | Target: CC Summit June 23, 2026
Primary opportunity: Enterprises cannot prove to regulators, auditors, or customers how their data was handled during AI processing.
Expand Down Expand Up @@ -79,9 +79,9 @@ The gateway and the server are now primary control surfaces -- the only enforcem

---

## 3. Solution: cMCP Gateway
## 3. Solution: cMCP Runtime

The cMCP Gateway intercepts every MCP tool call, evaluates it against a Cedar policy bundle, and enforces the result from inside a TEE. The policy bundle hash is measured into the hardware attestation report before any code runs. The audit chain is signed with a key that is hardware-sealed inside the enclave.
The cMCP Runtime intercepts every MCP tool call, evaluates it against a Cedar policy bundle, and enforces the result from inside a TEE. The policy bundle hash is measured into the hardware attestation report before any code runs. The audit chain is signed with a key that is hardware-sealed inside the enclave.

The output is a TRACE Claim: a signed, hardware-attested artifact the enterprise hands to an auditor, regulator, or customer instead of a written response. The verifier does not need to trust the operator.

Expand All @@ -93,7 +93,7 @@ The output is a TRACE Claim: a signed, hardware-attested artifact the enterprise
Agent
|
v
cMCP Gateway (TEE boundary) -- the sole MCP endpoint the agent host sees
cMCP Runtime (TEE boundary) -- the sole MCP endpoint the agent host sees
+-- MCP Protocol Interceptor
| receives every tool call before it reaches the tool
|
Expand Down Expand Up @@ -308,7 +308,7 @@ GTM note: For production-bound regulated buyers, the entry point is the proof ga

## 14. Success Metric

Three enterprise design partners signed on cMCP Gateway by July 15, 2026.
Three enterprise design partners signed on cMCP Runtime by July 15, 2026.

---

Expand Down
16 changes: 8 additions & 8 deletions docs/configuration.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Configuration Reference
# Configuration Reference

`cmcp-config.yaml` controls the gateway's attestation provider, policy enforcement behavior, network settings, and file paths. Environment variables override specific fields and control secrets that must not appear in config files.

Expand Down Expand Up @@ -27,7 +27,7 @@ attestation:
# warn_only: allow sessions to continue; marks TRACE Claims as stale.
staleness_policy: fail_closed

# Optional. If set, the gateway verifies the TEE measurement matches
# Optional. If set, the runtime verifies the TEE measurement matches
# this value at startup and refuses to start if it does not.
# Format: provider-specific (e.g., hex PCR values for TPM,
# AMD measurement register hex for SEV-SNP).
Expand All @@ -42,7 +42,7 @@ policy_bundle_path: policy/
# Must not contain '..' components.
catalog_path: catalog.json

# Address and port the gateway listens on.
# Address and port the runtime listens on.
listen_addr: "0.0.0.0:8443"

# Maximum size of a tool response payload in bytes. Responses larger than
Expand All @@ -52,7 +52,7 @@ max_response_size_bytes: 2097152

# Interval in seconds between automatic policy bundle reloads.
# 0 (default) disables automatic reload. Changing the policy bundle
# without restarting the gateway invalidates the attestation measurement.
# without restarting the runtime invalidates the attestation measurement.
# This field exists for advisory/silent deployments only; do not use in
# enforcing mode without a full enclave restart.
policy_reload_interval_seconds: 0
Expand All @@ -68,7 +68,7 @@ policy_reload_interval_seconds: 0
| `enforcement_mode` | string | `enforcing` | Policy enforcement mode. Valid values: `enforcing`, `advisory`, `silent`. |
| `validity_seconds` | integer | `86400` | Attestation report validity period in seconds. Must be a positive integer. At expiry, behavior is controlled by `staleness_policy`. |
| `staleness_policy` | string | `fail_closed` | Action when attestation validity expires. Valid values: `fail_closed` (terminate sessions), `warn_only` (allow sessions, mark claims as stale). |
| `expected_measurement` | string | none | Optional. Expected TEE measurement value. If set, the gateway verifies the hardware measurement matches this string at startup and exits with a non-zero status if it does not. |
| `expected_measurement` | string | none | Optional. Expected TEE measurement value. If set, the runtime verifies the hardware measurement matches this string at startup and exits with a non-zero status if it does not. |

### top-level fields

Expand All @@ -87,16 +87,16 @@ Environment variables control secrets and mode flags that must not appear in con
| Variable | Description | Overrides |
|----------|-------------|-----------|
| `CMCP_DEV_MODE=1` | Enables software-only attestation. No hardware TEE required. TRACE Claims will show `partially_verified` status. Required when `provider` is `software-only`. | `attestation.provider` (forces software-only) |
| `CMCP_BEARER_TOKEN` | Optional bearer token for gateway HTTP auth. If set, all requests to the gateway must include `Authorization: Bearer <token>`. If unset, no bearer auth is enforced. | none |
| `CMCP_BEARER_TOKEN` | Optional bearer token for runtime HTTP auth. If set, all requests to the runtime must include `Authorization: Bearer <token>`. If unset, no bearer auth is enforced. | none |
| `OPAQUE_ATTESTATION_URL` | Enables the Opaque Managed Runtime provider. Must be set to the Opaque attestation service URL. Required when `provider` is `opaque` or `auto` on Opaque infrastructure. | enables `opaque` provider detection |
| `CMCP_CATALOG_HASH` | SHA-256 hash of the approved `catalog.json`. Required in non-dev mode. The gateway fails closed at startup if this is unset and `CMCP_DEV_MODE` is not `1`. Format: `sha256:<hex>`. | none (additional startup check) |

## Enforcement modes

| Mode | Behavior | Use case |
|------|----------|----------|
| `enforcing` | Policy denies block the tool call. The gateway returns HTTP 403 and a structured error to the agent. The call is not forwarded to the upstream server. | Production. Default for new deployments. |
| `advisory` | Policy denies are logged in the audit chain but the call is forwarded. The TRACE Claim records the deny. No tool call is blocked. | Policy testing, migration from existing gateway. Safe for first run with an untuned policy. |
| `enforcing` | Policy denies block the tool call. The runtime returns HTTP 403 and a structured error to the agent. The call is not forwarded to the upstream server. | Production. Default for new deployments. |
| `advisory` | Policy denies are logged in the audit chain but the call is forwarded. The TRACE Claim records the deny. No tool call is blocked. | Policy testing, migration from existing runtime. Safe for first run with an untuned policy. |
| `silent` | Policy is evaluated but the result is not acted on and denies are not logged. Observability-only mode. | Measuring policy impact before rollout. Not suitable for any compliance scenario. |

## Minimal working config
Expand Down
14 changes: 7 additions & 7 deletions docs/quickstart.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# Quickstart — cMCP Gateway
# Quickstart — cMCP Runtime

From zero to first TRACE Claim in under 30 minutes. Uses `CMCP_DEV_MODE=1` so no hardware TEE is required.

---

## What you'll build

You'll run a cMCP Gateway that intercepts tool calls from a demo agent, enforces a Cedar policy bundle, and produces a signed TRACE Claim at the end of the session. The demo scenario uses a mock `salesforce.contacts` tool. The TRACE Claim records which tools were called, what data classes they touched, and that the policy bundle hash matches what was measured at startup.
You'll run a cMCP Runtime that intercepts tool calls from a demo agent, enforces a Cedar policy bundle, and produces a signed TRACE Claim at the end of the session. The demo scenario uses a mock `salesforce.contacts` tool. The TRACE Claim records which tools were called, what data classes they touched, and that the policy bundle hash matches what was measured at startup.

---

Expand Down Expand Up @@ -186,17 +186,17 @@ print('sha256:' + hashlib.sha256(s.encode()).hexdigest())
"
```

If you change any field in `approved_definition`, rerun the command and update `definition_hash`. The gateway rejects catalog entries where the hash does not match.
If you change any field in `approved_definition`, rerun the command and update `definition_hash`. The runtime rejects catalog entries where the hash does not match.

---

## Start the gateway
## Start the runtime

```bash
CMCP_DEV_MODE=1 cmcp start --config cmcp-config.yaml
```

In dev mode the gateway uses a software-only TEE provider (no hardware required). The startup log prints:
In dev mode the runtime uses a software-only TEE provider (no hardware required). The startup log prints:

```
[cmcp] provider=software-only enforcement_mode=advisory
Expand Down Expand Up @@ -231,7 +231,7 @@ curl -X POST http://localhost:8443/mcp \
}'
```

The gateway intercepts the call, evaluates the Cedar policy (rule 1 matches because `workflow_id == "demo-agent"`), records an audit entry, and forwards to the upstream mock server.
The runtime intercepts the call, evaluates the Cedar policy (rule 1 matches because `workflow_id == "demo-agent"`), records an audit entry, and forwards to the upstream mock server.

---

Expand Down Expand Up @@ -312,7 +312,7 @@ The response is a signed `GatewayClaim`. It looks like:

## Verify

Use the `cmcp_verify` library to verify the claim without trusting the gateway operator. Replace the hash values with those printed at gateway startup:
Use the `cmcp_verify` library to verify the claim without trusting the runtime operator. Replace the hash values with those printed at gateway startup:

```python
# verify.py
Expand Down
Loading
Loading