Skip to main content

MCP Adapter

The MCP adapter governs individual tool calls made by Model Context Protocol (MCP) clients. Each tools/call is authorized by the same policy decision point (PDP) as every other OpenProdkt request, before the tool runs. Governance applies to the operation itself, not only to whether a client can reach an MCP server.

The adapter has two entry points:

  • a local stdio wrapper, which runs between an MCP client and a stdio MCP server that the client launches
  • MCP over HTTP (Streamable HTTP), which the Transparent Proxy governs through Envoy for each MCP endpoint you configure

Both entry points apply the same tool-level rules. See MCP over HTTP through Envoy for the HTTP path.

Scope​

CapabilityStatus
Governance of tools/call on local stdio MCP serversShipped
Governance of tools/call on Streamable HTTP MCP endpoints through EnvoyShipped
ALLOW, DENY, and APPROVAL_REQUIRED per tool call, on both entry pointsShipped
Outcome reporting for allowed calls (stdio)Shipped
Outcome reporting for allowed calls (Envoy)Not shipped. Envoy records decisions and approvals only.
Governance of other MCP methodsNot governed. Only tools/call is decided. Other methods pass through.

Use the Envoy path only for MCP endpoints that you have configured in the route file with protocol: mcp. Do not rely on the adapter to govern an MCP endpoint that has no route.

How it works​

  1. The client starts openprodkt-mcp-pep in place of the MCP server. The wrapper launches the real server as a child process.
  2. For each tools/call, the wrapper reads the tool name, the arguments, and the configured metadata, then asks the PDP for a decision.
  3. If the decision is ALLOW, the call is forwarded to the server. After the server answers, the wrapper reports the outcome.
  4. If the decision is DENY or APPROVAL_REQUIRED, the server never sees the call. The wrapper returns a tool result that describes the decision.

Calls that do not match any policy are allowed and recorded with reason no_matching_policy. They are not blocked, unless the organization has opted in to strict mode, where they are denied with default_deny_no_match. An active kill switch denies every call in its scope with kill_switch_active, and the wrapper returns that reason like any other deny.

Only tools/call is governed. Other MCP methods are passed through.

Tool definition pinning​

If you pin the approved definition of an MCP tool, the wrapper for local stdio servers sends the digest of the definition it saw with each call to that tool. It learns the definition from the tools/list result your MCP client requests and from the server's version in the initialize result, never by asking the server itself during a call. It sends the digest only when it holds a current list that contains the called tool and the definition can be hashed; otherwise it sends nothing and the call is handled as before. A list-changed notification from the server discards what it knows until the client lists tools again. The description and input schema never leave the wrapper; only the digest, its canon value and the server version do. In strict mode a changed definition is denied with definition_changed, and the wrapper returns it like any other deny. The MCP over HTTP route through Envoy does not send a digest, so a pin has no effect there.

MCP over HTTP through Envoy​

The transparent proxy governs a Streamable HTTP MCP endpoint when its route is declared with protocol: mcp. See Route configuration. Each tools/call is decided by the same PDP and uses the same tool identity, decision results, and approval flow as the stdio wrapper. For the same tool call, both entry points return the same decision.

Requests to an MCP endpoint are handled as follows.

RequestResult
POST with a tools/call request that has an idThe PDP decides before the upstream runs.
POST with another JSON-RPC message, such as initialize or tools/listPassed to the upstream without a decision.
GET or DELETE with no bodyPassed to the upstream without a decision.
GET or DELETE with a bodyRefused with HTTP 400 and body_not_allowed. The upstream is not called.
Any other HTTP methodRefused with HTTP 405 and method_not_allowed. The upstream is not called.
No Authorization: Bearer header, for any methodRefused with HTTP 401 and unauthenticated. The upstream is not called.
tools/call with no idJSON-RPC error -32600.
tools/call with no Mcp-Session-Id header and no _meta.openprodkt.operation_idJSON-RPC error -32600. Set one of them.

The 400, 401, and 405 refusals are HTTP responses, not JSON-RPC results. A denied or pending tools/call is returned as a JSON-RPC tool result with HTTP 200 and isError: true, so that the MCP client can read it. The decision, reason, and next_action fields are the same as in Decision results.

On this path:

  • Credentials. The client's Authorization header is used for the decision. The adapter removes it before the request reaches the MCP server.
  • Outage. If the control plane does not answer in time, the call is denied with a JSON-RPC result, reason: pdp_unavailable, and isError: true. The MCP server is not called. Envoy returns HTTP 503 only when the authorization adapter itself cannot be reached.
  • Streaming. Responses are not buffered. A server-sent event stream reaches the client as the upstream sends each event, because the decision is made before the upstream call.
  • Operation ID. The operation ID is returned in the result and recorded in the audit history. The adapter does not add it to the request that the MCP server receives.
  • Retries after approval. When an approval has already been used, the adapter returns the approval_consumed result without the operation status that the stdio wrapper attaches. Read the status from GET /v1/proxy/operations/{operation_id}.
  • Outcome reporting. The adapter cannot see the server's response, so it records decisions and approvals only. It does not report whether the tool succeeded or failed. Do not treat the absence of an outcome as a failure. Check the server's side effects before you retry an operation that may already have run. See stdio versus Envoy coverage.
  • Trace context. The adapter only reads an inbound traceparent. It does not create, inject or change any header or body sent to the MCP server. See Trace and execution correlation.

Requirements​

  • The mcp.enabled entitlement. MCP calls need it, on both the stdio wrapper and the Envoy path. proxy.enabled alone does not authorize MCP calls: the PDP returns 403 and every governed call is blocked. See Licensing & Distribution.
  • For the stdio wrapper: a service principal token, stored in a file (see Principal token), and network access from the wrapper to the control plane API.
  • For the Envoy path: the MCP endpoint's route in the route file, and the transparent proxy configured as described in Transparent Proxy. Clients send their own bearer token.
  • The stdio MCP server command that the wrapper will launch, for the stdio wrapper only.

Command line​

openprodkt-mcp-pep --config /etc/openprodkt/pep.json -- <server-command> [args...]
openprodkt-mcp-pep --version

Everything after -- is the server command. The wrapper passes stdio through to that command.

Exit codeMeaning
0Normal exit, or --version.
1Runtime error.
2Usage error, such as a missing --config or server command, or an invalid configuration.

Configuration​

The configuration file is strict JSON. Unknown fields are rejected at startup.

{
"organization": "acme",
"server": "refunds",
"application": "support-agent",
"environment": "production",
"pdp_url": "https://api.openprodkt.example.com",
"principal_token_file": "/etc/openprodkt/mcp-pep.token",
"pdp_timeout": "5s",
"child_env_allowlist": ["HOME", "PATH"],
"tools": {
"lookup_order": {
"arguments": { "order_id": "order.id" }
},
"send_refund": {
"asset_id": "ast_0123456789abcdef",
"arguments": {
"amount": "refund.amount",
"currency": "refund.currency"
}
}
}
}

Top-level fields​

FieldRequiredDescription
organizationYesYour OpenProdkt organization identifier.
serverYesA name for the MCP server. It is part of every tool's identity. Lowercase DNS label.
applicationYesThe application that owns the governed tools. Lowercase DNS label.
environmentYesThe environment, such as production. Lowercase DNS label.
pdp_urlYesAbsolute http or https URL of the control plane API.
principal_token_fileYesAbsolute path to the principal token file. See Principal token.
pdp_timeoutNoTimeout for each PDP call, as a Go duration such as 5s. Default 5s.
child_env_allowlistNoEnvironment variable names passed to the server process. Only these names are passed.
toolsNoPer-tool governance settings, keyed by MCP tool name.

OPK_PRINCIPAL_TOKEN cannot appear in child_env_allowlist. The principal token is never passed to the server process. Each name may appear only once.

Tool fields​

FieldDescription
asset_idOptional. The id of an asset you already registered in OpenProdkt (for example ast_...). It is not the asset key. When set, the wrapper sends this ID instead of deriving a key, so the tool stays bound to that asset even if the server or tool is renamed. If no asset has this ID, the call is denied. See Unregistered asset.
argumentsOptional. Maps an argument path in the tool's arguments to a metadata key that policies can read.

Argument paths are dot-separated keys, for example refund.amount. Arrays are not indexed. Two argument paths cannot map to the same metadata key; the wrapper rejects the configuration at startup.

A tool that is not listed in tools is still governed. It is evaluated with empty metadata, so policies can match only on the tool's identity.

Tool identity​

Each tool has a stable identity derived from the server name and the tool name. The tool label has the form mcp- followed by a lowercase base32 hash. The governed asset key has the form <application>.<label>.<environment>.

Renaming the server or the tool changes its identity, and existing policies no longer match it. To keep a tool's identity fixed across renames, set asset_id for that tool.

Tool names are matched exactly. They are not trimmed or normalized.

Required metadata mappings​

An asset's _fieldMetadata schema can mark fields required: true. Each required path must be present, non-null, and correctly typed before a tool call is authorized. The Console warns when an MCP tool has required fields.

Tools without a tools configuration mapping send empty business metadata. If their asset requires a field, every governed call will be blocked before execution. Configure argument mappings for all required paths before enabling the requirement. The same schema validation applies to the stdio and Envoy MCP paths, without a bypass for unmapped tools.

Schema edits also apply immediately to approval retries. Do not assume an existing approval remains usable after adding a requirement; changed operation context may need a new operation and approval.

Principal token​

The wrapper authenticates to the PDP with a service principal token. Store the token in a file:

  • The path must be absolute and must point to a regular file.
  • The file mode must be 0600. The wrapper refuses to start otherwise.
  • The token is read once at startup and is never passed to the server process.

Approvals​

When a policy requires approval, the wrapper returns a tool result with isError: true and the decision in _meta.openprodkt. The server does not run the tool.

Example: approval required​

Request from the client:

{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "send_refund",
"arguments": { "amount": 250, "currency": "USD" }
}
}

Response from the wrapper:

{
"jsonrpc": "2.0",
"id": 7,
"result": {
"content": [
{
"type": "text",
"text": "OpenProdkt requires approval for this tool call. Check /v1/proxy/operations/refund-2024-0042 for status and the redemption deadline. After approval, retry the same arguments with _meta.openprodkt.operation_id set to \"refund-2024-0042\" within the 120-second grant window and before the redemption deadline. The tool was not run."
}
],
"isError": true,
"_meta": {
"openprodkt": {
"v": 1,
"decision": "approval_required",
"operation_id": "refund-2024-0042",
"approval_expires_at": "2026-10-23T21:00:00Z",
"grant_ttl_seconds": 120,
"status_url": "/v1/proxy/operations/refund-2024-0042",
"next_action": "wait_for_approval"
}
}
}
}

To continue:

  1. The challenge and the status endpoint never include an approval ID, by design. Do not look for one in _meta or in the status response. Find it in two steps:

    • Poll status_url (step 2). The response includes decision_id for this operation, for example dec_....
    • Call GET /v1/approvals?search=<decision_id> with an API key or token that has approvals:read. Find the item whose decisionId equals that value; its id (apr_...) is the approval ID. Search matches substrings, so check decisionId in your code rather than taking the first item.

    If you subscribe to webhooks, the approval.pending event also carries approvalId and operation_id. Searching the approvals list by operation ID does not work, because list items do not include it. GET /v1/approvals/{id} returns operation_id, so you can confirm the match. The retry in step 3 needs only the operation ID, not the approval ID.

  2. Wait for an approver to approve it. Approvers are super admins, and users who own the asset. A user who owns the asset can approve, reject, and revoke only that asset's approvals. Other users with the user role cannot see or act on them. Poll status_url. The response includes approval_status for this operation: pending, approved, rejected, expired, or consumed.

  3. Retry the same tool call with the same arguments, and set the same operation ID in _meta.openprodkt.operation_id:

{
"jsonrpc": "2.0",
"id": 8,
"method": "tools/call",
"params": {
"name": "send_refund",
"arguments": { "amount": 250, "currency": "USD" },
"_meta": {
"openprodkt": { "operation_id": "refund-2024-0042" }
}
}
}

The retry must arrive within the grant window and before the redemption deadline. If either has passed, the wrapper returns a deny with reason: approval_grant_expired or reason: approval_expired. A new approval is required.

Operation identity​

Set _meta.openprodkt.operation_id yourself on every governed call that might need approval. It must be 1 to 128 characters from letters, digits, ., _, :, and -. The operation ID identifies the operation across retries.

If you do not set it, the wrapper derives one from the request. That derived ID is stable only within a single JSON-RPC request. A retry with a new request id gets a new ID, so the approval will not match.

Decision results​

Every governed result carries _meta.openprodkt with v: 1.

FieldDescription
decisionallow, deny, or approval_required.
reasonWhy the call was denied, such as approval_rejected, approval_revoked, approval_expired, approval_grant_expired, approval_consumed, execution_unknown, pdp_unavailable, or a policy reason.
decision_idThe PDP decision identifier, when available.
operation_idThe operation identifier used for retries and reconciliation.
approval_statusNot present on approval_required results. Read it from status_url.
approval_expires_atWhen the approval expires. Present on approval_required results.
grant_ttl_secondsLength of the grant window after approval.
status_urlPath to read the operation's status.
next_actionThe suggested next step. See below.

Next actions:

next_actionMeaning
wait_for_approvalWait for an approver, then retry with the same operation ID.
request_new_approvalThe approval window has passed. Start a new approval.
reconcile_upstreamCheck whether the tool ran before doing anything else. Do not replay it automatically.
stopThe approval was rejected or revoked. Do not retry.

A deny because the PDP could not be reached has reason: pdp_unavailable. The tool did not run.

Malformed requests​

A request that the PDP rejects as invalid returns a JSON-RPC error with code -32602. It is not a tool result. Examples include an invalid operation ID.

Unregistered asset​

If asset_id names an unknown or inaccessible asset, the PDP returns HTTP 404 with {"error":"asset not found","code":"asset_not_found"}. Both the stdio wrapper and Envoy MCP path return an isError: true tool result with decision: deny, reason: asset_not_found, and the operation ID in _meta.openprodkt. The upstream tool is not called, and no decision quota is consumed. Missing and inaccessible assets produce the same error. Correct the configured asset_id and access before retrying; reload the route configuration or restart the wrapper after changing it.

Invalid evaluation context​

A valid tools/call whose mapped metadata violates the asset schema, numeric limits, or runtime policy value types returns an isError: true tool result with decision: deny, reason: invalid_context, and the operation ID in _meta.openprodkt. This applies to both stdio and Envoy MCP. The tool is not called, decision quota is not consumed, and an approval is not redeemed. Correct the metadata or mapping before retrying. Malformed tool requests still return JSON-RPC -32602; they are distinct from invalid evaluation context.

Mapped numeric metadata uses exact decimal policy comparison. The complete tool-arguments digest still preserves numeric text, so equivalent decimal spellings in arguments can have different full-payload digests.

Tool with no registered asset​

If a tool has no asset_id and no registered asset matches its derived key, the PDP returns allow with reason: asset_not_registered. The wrapper runs the tool. This is the default for unknown tools, and it means an unregistered tool is not governed. The call is not recorded as a decision, and the tool is queued for discovery so an administrator can register it. To govern a tool, register it and attach a policy. Until then, do not rely on the wrapper to block it.

Outcome reporting​

For each allowed call, the wrapper reports the outcome to the control plane (POST /v1/proxy/outcomes):

  • succeeded: the server returned a tool result without isError.
  • failed: the server returned a JSON-RPC error or a tool result with isError: true.
  • unknown: the wrapper could not read the server's response.

The wrapper makes up to 4 attempts in total, waiting 250 ms, 500 ms, and 1 s between them. Each attempt is bounded by pdp_timeout. A definitive client error other than 408 or 429 is not retried. The retry schedule is fixed. If every attempt fails, no outcome is recorded for the operation, and the audit trail shows only the decision. The result_hash is a SHA-256 of the response member. Outcome reports do not delay the response to the client.

Outcome reporting applies to the stdio wrapper only. The Envoy path does not report outcomes; see MCP over HTTP through Envoy.

stdio versus Envoy coverage​

stdio wrapperMCP over Envoy
Outcome reportedYes, for each allowed call, by the wrapperNo. Envoy outcome recording is not available.
Decisions marked outcome_reporting: noneNoYes
Audit without a reportIf every report attempt fails, only the decision is recorded. With outcome deadline monitoring on, an execution.outcome.missing event is stored after the deadline.The read-time operation.outcome.not_reported row when you filter by operation_id, and with monitoring on a stored execution.outcome.not_reportable event.

Neither event means the tool failed or did not run, and neither changes a decision, an approval or billing. See Coverage events. On the Envoy path, an application that wants an outcome can report it itself with POST /v1/proxy/outcomes, using the principal that received the allow.

Trace and execution correlation​

Availability. This section applies to wrapper and adapter builds that include trace and execution correlation, used with a control plane that supports it. Check the release notes of the version you run.

Correlation identifiers help you line up an MCP client's trace, the OpenProdkt decision and the upstream call. They never change a decision, never become policy input and are not part of approval binding. Formats and bounds are in the API Reference.

stdio wrapper​

Inbound trace. The wrapper reads params._meta.traceparent and params._meta.openprodkt.traceparent of a tools/call.

InputResult
Valid traceparent in one carrier, or the same value in bothNormalized to the version 00 form and sent to the control plane
Invalid string valueIgnored; the wrapper creates a new root trace
Non-string valueJSON-RPC error -32602, not a tool result
Both carriers present with different valuesJSON-RPC error -32602 (conflicting traceparent aliases)
No traceparentThe wrapper creates a new root trace with random IDs and flags 00

Candidate identifiers. Before it asks for a decision, the wrapper allocates a candidate execution_id (a UUIDv7), sets attempt to 1 and uses the same value as upstream_request_id. These are candidates, not proof of dispatch: a denied or pending call also gets them, but the tool is never called and no outcome is reported. A later retry of the same operation allocates a new execution_id. The attempt value is local and advisory; the wrapper keeps no global counter.

What the MCP server receives. Only after an allow, the wrapper adds these members to params._meta.openprodkt of the forwarded request: operation_id, traceparent, execution_id, attempt and upstream_request_id. The traceparent is the wrapper's trace value (your valid inbound value or the new root), not the control plane's span. The tool arguments and other _meta members are not changed, but the wrapper overwrites any of these five members that the client set. Whether your server uses or forwards them is up to the server; OpenProdkt does not verify it.

What the client receives. A deny, an approval-required result and an execution_unknown result carry traceparent, execution_id and attempt in _meta.openprodkt. All of them except execution_unknown also carry upstream_request_id.

Outcome reports. The wrapper includes the same execution_id, attempt and upstream_request_id in the outcome it reports. Retries of one report keep the same identifiers and completion time.

Envoy​

On the Envoy path the adapter only reads an inbound traceparent HTTP header and passes a valid, normalized value to the control plane. This applies to HTTP, gRPC and MCP routes.

  • No injection. The adapter does not create a trace when none arrives, and does not inject or modify headers or the body sent upstream. It has no outcome reporter and adds no upstream correlation guarantee.
  • Invalid or repeated values. An invalid value, or a repeated or comma-joined header, is ignored and the control plane starts a new trace.
  • Header allow list. The Envoy ext_authz filter must forward traceparent to the adapter. The reference configuration lists it in allowed_headers. See Envoy configuration.
  • MCP routes. The adapter also reads params._meta.traceparent and params._meta.openprodkt.traceparent. If a valid header and a valid _meta value differ, the adapter returns a JSON-RPC -32602 error (conflicting traceparent carriers) and the upstream is not called. If only one is valid, it is used. A valid trace is returned in _meta.openprodkt.traceparent of governance results.
  • Approval binding. traceparent is removed from the HTTP header context sent with the decision, even if a route's header allow list names it. It is not part of approval binding, so a retry with a different value does not mismatch.

Not available​

OpenTelemetry export, injection of trace or correlation headers into upstream requests by Envoy, and Envoy outcome reporting are not available.

Limits​

  • Each newline-delimited message from the client or the child server is limited to 1 MiB. An oversize message gets a JSON-RPC invalid-request error.
  • The principal token file must have mode 0600, be a regular file (not a symlink), and be at most 64 KiB.
  • The wrapper waits 5 seconds for the child server to shut down.
  • server, application, and environment must be lowercase DNS labels of at most 63 characters.
  • On the Envoy path, MCP decisions use a fixed 5-second timeout and bodies over 1 MiB are rejected with 413 payload_too_large.

See Limits and Configuration for the full list.

Execution unknown​

If the server fails after the wrapper has forwarded an allowed call, the tool may already have run. The wrapper does not know whether it ran, so it does not report the call as failed. It returns:

{
"isError": true,
"_meta": {
"openprodkt": {
"v": 1,
"decision": "allow",
"reason": "execution_unknown",
"operation_id": "refund-2024-0042",
"status_url": "/v1/proxy/operations/refund-2024-0042",
"next_action": "reconcile_upstream"
}
}
}

Do not retry the call automatically. Read the operation's status:

curl -H "Authorization: Bearer $OPK_API_KEY" \
https://api.openprodkt.example.com/v1/proxy/operations/refund-2024-0042

The status endpoint requires the decision.run scope. For MCP operations it also requires the mcp.enabled entitlement. Check the upstream system for the effect of the call before you decide whether to run it again.

If a retry arrives after the first attempt was consumed, the wrapper attaches the current operation status to _meta.openprodkt.operation_status and sets next_action from that status.

Coverage​

Calls to tools with no matching policy are allowed and recorded with reason: no_matching_policy. Use this reason to find tools that policy does not yet cover. Add policies for the tools that must be governed.

Verify the setup​

  1. Run openprodkt-mcp-pep --version and confirm the version.
  2. Start the client against the wrapper, and list the tools. The client should show the same tools as the server.
  3. Call a tool that a policy allows. The result should come from the server, and no _meta.openprodkt decision should be present.
  4. Call a tool that a policy denies. The result should have isError: true and decision: deny, and the server should not receive the call.
  5. Call a tool that requires approval. The result should have decision: approval_required. Approve it, then retry with the operation ID to confirm the tool runs.

Next steps​