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
| Capability | Status |
|---|---|
Governance of tools/call on local stdio MCP servers | Shipped |
Governance of tools/call on Streamable HTTP MCP endpoints through Envoy | Shipped |
ALLOW, DENY, and APPROVAL_REQUIRED per tool call, on both entry points | Shipped |
| 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 methods | Not 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
- The client starts
openprodkt-mcp-pepin place of the MCP server. The wrapper launches the real server as a child process. - For each
tools/call, the wrapper reads the tool name, the arguments, and the configured metadata, then asks the PDP for a decision. - If the decision is
ALLOW, the call is forwarded to the server. After the server answers, the wrapper reports the outcome. - If the decision is
DENYorAPPROVAL_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.
| Request | Result |
|---|---|
POST with a tools/call request that has an id | The PDP decides before the upstream runs. |
POST with another JSON-RPC message, such as initialize or tools/list | Passed to the upstream without a decision. |
GET or DELETE with no body | Passed to the upstream without a decision. |
GET or DELETE with a body | Refused with HTTP 400 and body_not_allowed. The upstream is not called. |
| Any other HTTP method | Refused with HTTP 405 and method_not_allowed. The upstream is not called. |
No Authorization: Bearer header, for any method | Refused with HTTP 401 and unauthenticated. The upstream is not called. |
tools/call with no id | JSON-RPC error -32600. |
tools/call with no Mcp-Session-Id header and no _meta.openprodkt.operation_id | JSON-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
Authorizationheader 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, andisError: true. The MCP server is not called. Envoy returns HTTP503only 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_consumedresult without the operation status that the stdio wrapper attaches. Read the status fromGET /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.enabledentitlement. MCP calls need it, on both the stdio wrapper and the Envoy path.proxy.enabledalone does not authorize MCP calls: the PDP returns403and 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 code | Meaning |
|---|---|
0 | Normal exit, or --version. |
1 | Runtime error. |
2 | Usage 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
| Field | Required | Description |
|---|---|---|
organization | Yes | Your OpenProdkt organization identifier. |
server | Yes | A name for the MCP server. It is part of every tool's identity. Lowercase DNS label. |
application | Yes | The application that owns the governed tools. Lowercase DNS label. |
environment | Yes | The environment, such as production. Lowercase DNS label. |
pdp_url | Yes | Absolute http or https URL of the control plane API. |
principal_token_file | Yes | Absolute path to the principal token file. See Principal token. |
pdp_timeout | No | Timeout for each PDP call, as a Go duration such as 5s. Default 5s. |
child_env_allowlist | No | Environment variable names passed to the server process. Only these names are passed. |
tools | No | Per-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
| Field | Description |
|---|---|
asset_id | Optional. 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. |
arguments | Optional. 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:
-
The challenge and the status endpoint never include an approval ID, by design. Do not look for one in
_metaor in the status response. Find it in two steps:- Poll
status_url(step 2). The response includesdecision_idfor this operation, for exampledec_.... - Call
GET /v1/approvals?search=<decision_id>with an API key or token that hasapprovals:read. Find the item whosedecisionIdequals that value; itsid(apr_...) is the approval ID. Search matches substrings, so checkdecisionIdin your code rather than taking the first item.
If you subscribe to webhooks, the
approval.pendingevent also carriesapprovalIdandoperation_id. Searching the approvals list by operation ID does not work, because list items do not include it.GET /v1/approvals/{id}returnsoperation_id, so you can confirm the match. The retry in step 3 needs only the operation ID, not the approval ID. - Poll
-
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
userrole cannot see or act on them. Pollstatus_url. The response includesapproval_statusfor this operation:pending,approved,rejected,expired, orconsumed. -
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.
| Field | Description |
|---|---|
decision | allow, deny, or approval_required. |
reason | Why 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_id | The PDP decision identifier, when available. |
operation_id | The operation identifier used for retries and reconciliation. |
approval_status | Not present on approval_required results. Read it from status_url. |
approval_expires_at | When the approval expires. Present on approval_required results. |
grant_ttl_seconds | Length of the grant window after approval. |
status_url | Path to read the operation's status. |
next_action | The suggested next step. See below. |
Next actions:
next_action | Meaning |
|---|---|
wait_for_approval | Wait for an approver, then retry with the same operation ID. |
request_new_approval | The approval window has passed. Start a new approval. |
reconcile_upstream | Check whether the tool ran before doing anything else. Do not replay it automatically. |
stop | The 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 withoutisError.failed: the server returned a JSON-RPC error or a tool result withisError: 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 wrapper | MCP over Envoy | |
|---|---|---|
| Outcome reported | Yes, for each allowed call, by the wrapper | No. Envoy outcome recording is not available. |
Decisions marked outcome_reporting: none | No | Yes |
| Audit without a report | If 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.
| Input | Result |
|---|---|
Valid traceparent in one carrier, or the same value in both | Normalized to the version 00 form and sent to the control plane |
| Invalid string value | Ignored; the wrapper creates a new root trace |
| Non-string value | JSON-RPC error -32602, not a tool result |
| Both carriers present with different values | JSON-RPC error -32602 (conflicting traceparent aliases) |
No traceparent | The 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_authzfilter must forwardtraceparentto the adapter. The reference configuration lists it inallowed_headers. See Envoy configuration. - MCP routes. The adapter also reads
params._meta.traceparentandparams._meta.openprodkt.traceparent. If a valid header and a valid_metavalue differ, the adapter returns a JSON-RPC-32602error (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.traceparentof governance results. - Approval binding.
traceparentis 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, andenvironmentmust 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
- Run
openprodkt-mcp-pep --versionand confirm the version. - Start the client against the wrapper, and list the tools. The client should show the same tools as the server.
- Call a tool that a policy allows. The result should come from the server, and no
_meta.openprodktdecision should be present. - Call a tool that a policy denies. The result should have
isError: trueanddecision: deny, and the server should not receive the call. - 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
- Approvals & Webhooks for the approval lifecycle.
- Policy Engine for writing policies that match tool identity and metadata.
- Transparent Proxy for governing HTTP and gRPC services.