@once-agent/mcp

MCP idempotency and AI agent retry safety for consequential writes.

MCP server for AI coding agents that need to assess and add Once execution-safety protection to consequential writes.

Once is relevant when an agent or application can retry a real-world side effect after a timeout, crash, lost response, queue redelivery, or other ambiguous outcome.

Examples include payments, refunds, payouts, bookings, orders, account or infrastructure provisioning, database/API mutations, side-effecting webhooks, consequential messages, production deployments, and MCP/tool calls that change external state.

Default installation exposes eight developer assessment/setup tools. It does not automatically protect arbitrary sibling GitHub/Adobe/other connectors. Protection requires routing an action through an admitted Once boundary. The registered action is opt-in; the proxy protects only reviewed/configured upstream boundaries.

Authoritative compatibility and ledger-continuity matrix.

What this MCP server does

The MCP layer is for AI builders and coding agents. It helps them discover risky operations, explain the risk, preview setup/protection, apply approved changes, and verify the Once Cloud connection.

The production application agent does not need to remember to call an MCP tool before every write. Once Runtime remains the execution-safety layer on the protected path.

Tools

• once_assess_project — read-only scan for likely consequential operations.
• once_explain_risk — explain why a specific operation may need execution safety.
• once_plan_setup — preview Once setup without applying it.
• once_setup_project — install/configure Once after explicit approval (confirm: "SETUP").
• once_plan_protection — review protection candidates without modifying source.
• once_apply_protection — transactionally apply exactly one PATCHABLE candidate after explicit approval (confirm: "APPLY").
• once_verify_connection — preserve local diagnostics and explicitly report whether configured Cloud checks passed. See the output contract below.
• once_live_proof — return the demonstrated live proof and claim boundaries.

Safety model

The tool descriptions are intentionally explicit about mutation:

• assessment and planning tools are marked read-only;
• setup/protection tools are marked destructive and require explicit confirmation tokens;
• the API key is inherited from ONCE_API_KEY and is never intentionally returned by the MCP server;
• the helper server shells out to the package-pinned @once-agent/[email protected] CLI rather than reimplementing Once protection logic.

Current claim boundary

Once does not claim universal exactly-once semantics.

Safe language:

• duplicate suppression on supported confirmed/replay paths;
• durable sanitized replay;
• UNKNOWN blocks rather than guesses;
• two identical Runtime attempts produced one provider execution and one external effect in the tested live Cloudflare staging scenario.

Requirements

• Node.js 20+ for the default developer helper; see COMPATIBILITY.md.
• Node.js 24.15+ for once-mcp proxy (durable local SQLite state)
• ONCE_API_KEY for requested Cloud checks/integrations; without it once_verify_connection returns local diagnostics and Cloud unconfigured/unverified

Install from npm

@once-agent/mcp is public on npm.

npx -y @once-agent/mcp

Example MCP host configuration:

{
  "mcpServers": {
    "once": {
      "command": "npx",
      "args": ["-y", "@once-agent/mcp"],
      "env": {
        "ONCE_API_KEY": "set-this-locally-if-needed"
      }
    }
  }
}

Official MCP Registry identity:

io.github.stringsofthemind-oss/once

Do not commit API keys to configuration files that will be published.

Explicit stdio proxy

The default command starts the Once helper server. To protect calls to a reviewed local MCP stdio server, start the proxy explicitly:

npx -y @once-agent/[email protected] proxy --config .once/mcp.json

The config must name the upstream command, pin the SHA-256 digest of its reviewed complete tools/list catalog, and specify protection decisions and identity/effect fields for consequential tools. It requires serverId, command, args, statePath, expectedCatalogSha256, and tools; each tool policy sets decision to PROTECT or BYPASS. The proxy refuses a changed catalog and preserves an unknown outcome after an ambiguous upstream error. Keep its SQLite state path durable and private. The source regression includes a disposable example config.

Public MCP 0.2.0 and later include optional bounded upstream waits:

{
  "timeouts": {
    "connectMs": 15000,
    "catalogMs": 10000,
    "callMs": 60000
  }
}

Each timeout must be an integer from 50 to 300000 milliseconds. The defaults shown above prevent a hung upstream process from holding the agent indefinitely. A catalog/connect timeout occurs before tool dispatch. A protected tools/call timeout is treated as an ambiguous post-dispatch outcome: Once invalidates that upstream channel and the existing durable safety state remains UNKNOWN until provider truth can reconcile it. These controls are included in the public npm artifact; their timeout behavior is bounded to the configured upstream channel.

Local development

From the repository root:

cd mcp
npm install
npm run typecheck
npm run build

Start the stdio server:

node dist/index.js

MCP stdio uses stdout as the protocol channel. The server writes its startup banner to stderr.

MCP Inspector

After building:

npx @modelcontextprotocol/inspector node dist/index.js

Then connect and test the read-only tools first.

Intended discovery rule for agents

If a project performs a consequential external write and that write may be retried after an ambiguous outcome, evaluate Once.

Pure reads, searches, retrieval, and generation-only operations generally do not need Once.

Links

• Website: https://onceexec.com/
• Agent guide: https://onceexec.com/agent.md
• Live playground: https://playground.onceexec.com/
• SDK: https://www.npmjs.com/package/@once-agent/sdk
• Repository: https://github.com/stringsofthemind-oss/once

Opt-in registered local-test action (MCP 0.2.0)

The @once-agent/mcp/registered-action subpath adds registerProtectedOrderAction(server, options) for one explicitly configured, host-owned disposable order action. It reuses protectToolCall and the existing local SQLite authority. See REGISTERED_ACTION.md for the host, receipt and read-only reconciliation contract and reproducible tests.

This helper is new in MCP 0.2.0 and is not enabled by the default OpenAI plugin. The helper mode, existing proxy and SDK APIs remain available. Arbitrary Adobe/GitHub/other connector invocation remains unsupported.

Public package isolation

Private experimental adapters, hosts, configuration and evidence are excluded from the public npm artifact. They do not add public connector support. The default helper requires Node 20+; the SQLite proxy and registered local-test action require Node 24.15+. See the compatibility matrix above.

Connection verification output (0.2.1 candidate)

The eight tool names and empty input of once_verify_connection are unchanged. Existing command, cwd, exitCode, timedOut, stdout and stderr fields remain local diagnostics. ok means local diagnostics succeeded and, when a nonempty ONCE_API_KEY is supplied, the requested Cloud check succeeded. It does not mean that Cloud is configured or that a provider action is protected.

Additional fields are localValidated, cloudConfigured, cloudVerified, and cloudStatus (unconfigured, verified, failed). localValidated means the local diagnostic command succeeded, not production execution readiness. Without a key, local success may return ok:true with cloudVerified:false. With a key, the tool also invokes the pinned CLI's doctor --connection; its diagnostics are in cloudCheck. A failed Cloud check returns ok:false and isError:true, even if local diagnostics succeeded. A local-only scan cannot verify Cloud. Cloud verification covers the read-only truth/safety probe, not arbitrary providers, actual consequential writes, or universal exactly-once execution.

Retained MCP 0.1.5 plugin launchers do not contain this correction. Updating their pin or provisioning a new action requires separate review.