ONCE

npx add-mcp 'https://once.aiagenthuddle.com/mcp'

What it does

Record supported provider actions under a stable operation key. Repeated requests reuse the operation; an uncertain outcome remains uncertain until evidence resolves it.

Public developer beta: documentation, signup and free usage are available. Use your product API key for requests; public examples do not require Vercel preview access. Paid subscriptions are available; free usage remains available.

Start here: one working example

1. Create an account, confirm your email, then create your ONCE project. Free access is enough; no subscription is needed for this example.
2. Save the API key while it is visible. Keep it in server-side configuration.
3. Use Node.js 22 or newer. Download the standalone example and create a private .env file alongside it.

You also need a Stripe sandbox secret key starting sk_test_ with permission to create PaymentIntents. A publishable key will not work. The example creates an unconfirmed test object; it does not charge a card. ONCE receives this credential for the request and does not store it in the ledger.

ONCE_API_KEY=replace_with_your_project_key
STRIPE_TEST_KEY=replace_with_your_Stripe_sandbox_secret_key
ONCE_OPERATION_KEY=quickstart-intent-001

Add .env to .gitignore. Never commit it, put it in a browser bundle or paste credentials into support messages. Keep the same ONCE_OPERATION_KEY for reruns of this example; changing it creates a new logical operation.

node --env-file=.env once-first-operation.mjs

What success looks like

The script records one unconfirmed Stripe test PaymentIntent, repeats the same logical request and checks that the operation ID stays the same. It then reads the ledger. A COMMITTED state records provider success; UNKNOWN or AMBIGUOUS means stop and inspect. It never calls retry.

Expected output includes PASS:. Read the accompanying state messages too: a successful replay alone does not prove a provider effect. The example makes real API requests and uses a small number of your request units.

Something failed? Check the setup table below before changing a key or repeating an uncertain action.

Your GitHub connection

Use a fine-grained token limited to your repository with Issues read/write. Supply Once-GitHub-Token and Once-GitHub-Repository: owner/repository in request headers. The repository stays pinned to the operation. Retrying or reconciling requires your credential; a new token may replace an expired one but cannot redirect the operation. Tokens are never stored in the ledger. Creating an issue is a real repository write.

The SDK accepts these credentials as its third constructor argument: {githubToken, githubRepository}. MCP transports send the same HTTP headers; credentials are never tool arguments. Read-only lookup needs only your ONCE key.

REST endpoints

Endpoint	Behaviour
POST /v1/operations	Create or retrieve a logical operation using Idempotency-Key.
GET /v1/operations/{id}	Read the durable state and retry safety.
POST /v1/operations/{id}/reconcile	Read provider evidence and update the operation.
POST /v1/operations/{id}/retry	Retry only when the recorded evidence permits it.

Failure behaviour and limits

• Reusing a key with different parameters returns a conflict without another provider action.
• UNKNOWN and AMBIGUOUS states never permit blind redispatch. A missing provider object alone does not prove non-commit.
• Supported adapters create unconfirmed Stripe test PaymentIntents in your sandbox and GitHub issues in a pinned repository using your request-scoped credential. They do not capture live payments or offer arbitrary HTTP access.
• Provider-native idempotency can be sufficient for a single integration. ONCE adds a durable operation record and explicit outcome/recovery states for the supported actions. It does not promise universal exactly-once effects.

Request bodies are limited to 16 KiB. Missing, revoked or cross-product keys are rejected. Rate limits return HTTP 429; service unavailability remains an error rather than a successful operation.

Runnable examples and integration checklist

Download once-first-operation.mjs · Read the public example source. No npm dependency or paid plan is required.

When this tool helps

Use ONCE when your application needs a durable record of supported provider actions and explicit recovery decisions after a timeout or crash. Provider-native idempotency may be enough for a single straightforward integration; ONCE adds a queryable operation ID, recorded state and evidence-based reconciliation. It does not make arbitrary actions exactly once.

Before putting it in a worker

• Persist your logical operation key before dispatch and reuse it with identical parameters.
• Save the returned operation ID so another process can inspect the same ledger record.
• Handle UNKNOWN and AMBIGUOUS as unresolved; reconcile with evidence before considering retry.
• Handle HTTP 429 and temporary failures with bounded backoff. Do not turn retries into an unbounded loop.

Setup problems

What you see	What to check
HTTP 401	Use this product's project API key in Authorization: Bearer. A Supabase key, Stripe key or the other product's key will not authenticate. Replaced keys stop working immediately.
HTTP 400	Check field names, types and required values against the example. Stripe credentials must be secret test keys; live credentials are not accepted.
HTTP 409	Different parameters with an existing logical key conflict. Restore the original parameters; never change keys just to bypass an uncertain outcome.
HTTP 429	Check monthly usage and rate limits. Wait before another attempt. ONCE reconciliation has a separate 100-request monthly reserve; a quota error never proves a safe retry.
Timeout or interrupted example	Preserve the logical key. Rerun with the same parameters to retrieve that operation; do not call retry blindly.

For support, send the product name, a redacted error/status, operation or lease ID and UTC timestamp to accounts@aiagenthuddle.com. Never send API keys, provider tokens, passwords or sign-in links.

Engineering notes

A timeout does not tell you whether an action happened: a concrete failure scenario and the limits of the recovery mechanism.

MCP and SDK access

Connect an MCP client

Choose a remote server using Streamable HTTP. Use the following connection details in a client that supports bearer headers:

Server URL	https://once.aiagenthuddle.com/mcp
Header	Authorization: Bearer YOUR_ONCE_API_KEY
Expected tools	once_create, once_get, once_retry, once_reconcile

Use your client's private credential configuration. A client that only supports OAuth cannot authenticate to this API-key endpoint. If discovery returns 401, check the header before invoking tools. Provider credentials must use the dedicated HTTP headers described above, never tool arguments. Start with discovery; creating an issue writes to your repository.

JavaScript · Node.js

Save the module as sdk.js in a project with "type": "module". The client uses the built-in fetch API.

import { OnceClient } from './sdk.js';

const once = new OnceClient(
  'https://once.aiagenthuddle.com',
  process.env.ONCE_API_KEY,
  { stripeTestKey: process.env.STRIPE_TEST_KEY }
);

const operation = await once.create(
  'order-123-intent', 'stripe', 'create_payment_intent',
  { amount: 100, currency: 'gbp' }
);
// Preserve the operation ID. Inspect before any retry.
console.log(operation);

Authenticated stateless MCP is available at /mcp. Tools: once_create, once_get, once_retry, once_reconcile. Official current and legacy clients have passed protected hosted checks. No resumable SSE sessions or unsupported MCP features are advertised.

The standalone JavaScript client is available directly. Download sdk.js into your server-side project. No npm package is published. Keep credentials outside browser bundles.