MCP Action integration

Witnora can expose the exact sandbox HTTP Action generated during onboarding as an MCP tool. This is a transport adapter over the same customer-owned Gateway; it is not a second policy, approval, execution, or evidence system.

The Agent can propose an Action and read its current state. It cannot approve its own Action, bypass the customer-owned Runtime, or submit a self-report as an independently verified result.

Before you start

In Hosted Onboarding, choose MCP Action, copy the displayed command, and run it in the Agent repository:

npx witnora@latest onboard --project <project-id> --action-transport mcp
npx witnora@latest gateway doctor

The CLI performs a real local MCP client/server handshake and accepts the test only when the server exposes the exact Action tool and scoped status reader, with no approve, execute, or verify tool. Hosted Onboarding reads that repository-authenticated result automatically and shows the MCP configuration only after it arrives. The test does not propose or execute an Action.

The command below requires the generated .witnora/gateway/http-action.json, the ignored action token, and the ignored local Gateway credential. If the binding is missing or no longer matches the active Harness, startup fails closed.

If setup reports that it is waiting for an Action path, define one exact sandbox Task/action Harness and rerun the same command. No transport is shown as connected until that local boundary exists.

Add Witnora to an MCP client

When the MCP client runs with the onboarded Agent repository as its working directory:

{
  "mcpServers": {
    "witnora": {
      "command": "npx",
      "args": ["-y", "witnora@latest", "mcp"]
    }
  }
}

If the MCP client uses another working directory, add --repo and the absolute path to the onboarded repository. No Hosted API key or action token belongs in the MCP client configuration; the local Witnora process reads the ignored files inside the customer boundary.

Tools the Agent receives

For an Action ID such as cancel-order, Witnora exposes:

• witnora_cancel-order — propose that exact sandbox Action;
• witnora_get_action — inspect approval, execution, Probe, and Receipt state for an Action returned by that exact tool in the current MCP session.

The Action tool accepts:

{
  "idempotencyKey": "cancel-order-42-v1",
  "resourceId": "order-42",
  "status": "CANCELLED"
}

The tool name is generated from the active Action binding. Witnora does not publish a generic arbitrary-write tool and does not publish approval, direct execution, or outcome-verification tools to the Agent.

After the MCP process restarts, retry the exact proposal first to restore that Action to the session before calling witnora_get_action. The idempotency contract returns the existing logical Action without another authorized write.

Complete the proof path

1. The Agent calls the generated Action tool.
2. Witnora returns the held Action, normally PENDING_APPROVAL.
3. A human approves or denies the exact Action in the Witnora workspace.
4. The existing customer Runtime executes an approved Action idempotently.
5. The existing separate Probe reads the target state.
6. The Agent calls witnora_get_action to inspect the current state; a proved result requires VERIFIED and a signed Receipt.

MCP does not change who owns credentials or where execution happens. The write credential remains behind the customer-owned Runtime, and the read-only Probe credential remains separate.

Retry contract

An exact retry must reuse the same idempotencyKey, resourceId, and status. It returns the same logical Action and must not create another authorized write. A changed body under the same key fails with an idempotency conflict.

MCP integration versus MCPBench

These are different jobs:

• MCP Action integration is a runtime transport for one controlled Action.
• MCPBench is an evaluation input that records deterministic tool-behavior evidence.

Using one does not imply the other, and neither proves complete mediation of every tool exposed by an Agent.

Beta boundary

• One exact generated sandbox HTTP Action is supported per onboarded Gateway.
• The MCP server runs locally over stdio and uses the public witnora package.
• No production Provider, new permission, navigation change, or evidence grade is introduced.
• Additional MCP tool schemas and hosted transports require separate review.

For a client that cannot use MCP, follow the HTTP Actions guide directly.