MCP adapter - dynamo-mcp
Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.
Wrap any MCP tool server with one adapter call and every tool call is paid work: callers without a live allowance credential get a standard x402-shaped payment-required error with the price quoted in the challenge; callers with one get served and metered - per call, or per unit of actual work.
The adapter (@dynamo/mcp 1.2.0) is not published; use it from a clone.
Funding modes, stated plainly: the adapter is mode-agnostic. Control
Mode is Live; stablecoin escrow runs on a local chain and the credit card
rail in Stripe TEST mode. Real money is Release-gated.
Monetize a server in one edit
import { Paywall, engineMeterBackend, attachMonetizedTools } from "@dynamo/mcp";
const paywall = new Paywall({ backend: engineMeterBackend(engine), serviceNode: MY_PAYEE });
attachMonetizedTools(server, [
{
name: "summarize",
description: "Summarize a document",
inputSchema: { text: z.string() },
priceUnits: 300_000n, // flat price per call
handler: async ({ text }) => summarize(text),
},
{
name: "translate",
description: "Translate, metered per word",
inputSchema: { text: z.string() },
priceUnits: 5_000n,
estimateUnits: (args) => 5_000n * countWords(args.text), // FREE pre-check
unitsFromResult: (r) => 5_000n * r.wordsTranslated, // meter ACTUAL work
handler: async ({ text }) => translate(text),
},
], { paywall, serviceNode: MY_PAYEE });
engineMeterBackend(engine) meters through a stream engine running in your process. The caller passes its allowance credential in the tool argument dynamo_allowance, which the adapter adds to every tool's input schema.
The adapter's rules
- Credential verification is in-process and offline (JWS against the
pinned engine signer) - the tool-call path never blocks on a network hop. A cached stream state older than 30 seconds denies.
- Free pre-checks precede paid actions.
estimateUnitsruns before the
handler; insufficient headroom is refused before any work happens.
- Failed executions are never billed. A handler that throws costs the
caller nothing.
- Actual work is what is metered. With
unitsFromResult, the meter reads
the result - you charge for what was delivered, not what was promised. A result that yields no valid count (a negative number, or a throw) falls back to priceUnits; a derived count of 0 is a free result and sends no meter tick.
- Delivered calls survive a restart. With
journalDirset
(new Paywall({ ..., journalDir: "/var/lib/my-tool/meter" }), one paywall per directory), each delivered call's meter job is written and flushed to disk before the result is returned, and after a restart it is sent again under its original reference and billed exactly once; until the core answers, that stream's calls are refused (metering replay pending). A damaged journal refuses every call; a write the disk refuses withholds the result. Unset, meter jobs are held in memory only and a crash before the flush loses them.
- Denials are x402-shaped, so an MCP client that understands the
challenge can acquire an allowance and retry - the same schema every gateway plugin emits.
MCP 2026-07-28 (stateless)
StatelessMcpServer serves MCP revision 2026-07-28 (stateless Streamable HTTP). A paid tool declares its payee and price; the price is reserved before the handler runs and billed, signed, before the answer leaves. A failed call bills nothing, and a refused call's tool error carries the reason code, the payee and the price, never the engine's message. ClientAllowances gives each authenticated client its own child allowance per payee under one parent stream, capped at the per-client cap and never above the parent's headroom. That map is held in memory: after a restart a returning client gets a fresh child, so across restarts one client can spend more than one per-client cap, but never more than the parent stream allows. make test-mcp-2026 runs it.
See it run
cd "$DYNAMO_REPO"
pwd
make demo-mcp # an MCP tool server monetized end to end, all three modes
The demo runs a real MCP client and server (the MCP SDK's in-memory transport) in Control Mode, stablecoin escrow on a local chain and the credit card rail in Stripe TEST mode: an unpaid call gets the x402 error, the buyer opens a budget and an allowance, paid calls are metered per word and per call, an over-cap call is refused at the free pre-check and never billed, then the stream is revoked, the budget closes and a final reconciliation line is printed. It exits non-zero on a mismatch.