Turns TypeScript files into durable, stateful tools for AI agents with built-in human approvals, SQLite storage, and exactly-once execution.
Also known as actuate-run/actuate, @actuate/cli, @actuate/sdk
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- 3,675
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is actuate MCP?
actuate turns TypeScript files into durable, stateful tools for AI agents with built-in human approvals, SQLite storage, and exactly-once execution.
Summary generated from the project's README
About actuate MCP server
Developers can transform TypeScript files into durable, stateful tools for AI agents using Actuate. This system allows agents to execute complex workflows that require human intervention, long-running processes, or reliable data storage. By using the Actuate SDK, you can define tools with Zod schemas that validate inputs before any code executes. These tools can be connected to MCP clients like Claude Desktop, Cursor, or VS Code via HTTP transport using an agent token.
Actuate distinguishes itself through exactly-once execution using a journaling system called ctx.step.do, which prevents duplicate actions like double refunds during retries. It supports long-term hibernation through sleep and waitForApproval commands, allowing processes to pause for days without incurring costs. Each tool operates with its own dedicated SQLite database for persistent storage. While the runtime is open source and can be self-hosted on Cloudflare Workers, the hosted platform provides the MCP endpoint, an OpenAPI document, and a management dashboard.
What you can do with it
- 1Execute high-value financial transactionsAn agent can process refunds that require manager approval for amounts exceeding a specific threshold.
- 2Manage long-running asynchronous workflowsYou can create tools that pause execution for hours or days while waiting for a human to click an approval link.
- 3Maintain persistent state for agent toolsEach tool can manage its own local data using a built-in database with support for migrations and exports.
- 4Integrate third-party services securelyConnect your tools to messaging platforms or payment providers without exposing sensitive credentials to the LLM prompt.
Written from the project's README. Every use case is checked against a quote from it.
How to install actuate MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall actuate MCP in Claude Code
$ claude mcp add actuate -- npx -y @actuate/cliInstall actuate MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"actuate": {
"command": "npx",
"args": [
"-y",
"@actuate/cli"
]
}
}
}Install actuate MCP in VS Code
.vscode/mcp.json
{
"servers": {
"actuate": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@actuate/cli"
]
}
}
}Install actuate MCP in VS Code CLI
$ code --add-mcp '{"name":"actuate","type":"stdio","command":"npx","args":["-y","@actuate/cli"]}'Install actuate MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"actuate": {
"command": "npx",
"args": [
"-y",
"@actuate/cli"
]
}
}
}Install actuate MCP in Codex
$ codex mcp add actuate -- npx -y @actuate/cliInstall actuate MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.actuate] command = "npx" args = ["-y", "@actuate/cli"]
Install actuate MCP in Gemini CLI
$ gemini mcp add -s user actuate npx -- -y @actuate/cliInstall actuate MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"actuate": {
"command": "npx",
"args": [
"-y",
"@actuate/cli"
]
}
}
}Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubActuate turns one TypeScript file into a tool your AI agent can call: over MCP on the hosted platform, or over HTTP wherever it runs. The tool checks its input against a schema, runs each step exactly once, sleeps for days at no cost, waits for payments, replies or a person's approval, and keeps its own SQLite database. Your messaging, payment and LLM keys stay out of the prompt.
npm create actuate
Example
A refund tool an agent can't misuse: amounts are capped by the schema, anything above RM 100 waits for a manager, and a retried call never refunds twice.
import { defineActuator, z } from "@actuate/sdk";
export default defineActuator({
name: "refund_order",
description: "Refund an order. Above RM 100 a manager approves first. Each order is refunded once.",
input: z.object({ orderId: z.string(), billId: z.string(), amount: z.number().positive().max(500) }),
capabilities: ["payment", "messaging"],
async run(ctx, input) {
if (input.amount > 100) {
// The run pauses here (for hours if it must) until the manager taps a signed link.
const decision = await ctx.step.waitForApproval("manager", {
message: `Refund RM ${input.amount} for order ${input.orderId}?`,
notify: "@shop_manager",
timeout: "24 hours",
});
if (!decision?.approved) return { status: "DECLINED", note: decision?.note ?? "timed out" };
}
// A step runs once. If the agent retries, it gets this result back, not a second refund.
const refund = await ctx.step.do("refund", ({ idempotencyKey }) =>
ctx.payment.refund!({ billId: input.billId, amount: input.amount, idempotencyKey }),
);
return { status: "REFUNDED", refundId: refund.id };
},
});
Run it locally with npx actuate dev, deploy it with npx actuate deploy, then give it to your agent:
claude mcp add --transport http refund_order https://run.actuate.run/a/<actuator-id>/mcp \
--header "Authorization: Bearer <agent token>"
Any MCP client works: Claude Code, Claude Desktop, Cursor, VS Code, or your own agent through an MCP SDK. Each hosted actuator also has an HTTP endpoint and an OpenAPI document. See Connect your agent.
The MCP endpoint is part of the hosted platform, not the open-source runtime. A self-hosted actuator is called over the runtime HTTP API (POST /run), which your agent can use as an HTTP tool. Give the agent ACTUATE_RUN_TOKEN, which can only start and read runs, never ACTUATE_TOKEN: that one can approve.
What you get
- Exactly once.
ctx.step.dojournals each step. Replays and retried tool calls get the stored result back. - Free waits.
sleep,sleepUntilandwaitForEventhibernate the run. Nothing runs, and nothing is billed, until it wakes. - People in the loop.
waitForApprovalandwaitForInputsend a signed, single-use link, with Approve and Reject buttons in Telegram, Slack and Discord, and resume when someone answers. - Its own database. A SQLite database per actuator, with parameterised queries, migrations, and CSV and
.sqlexport. - Your accounts. Telegram, WhatsApp, Slack, Discord, email, or any URL through a custom webhook; Stripe, Chip, ToyyibPay and Billplz; Anthropic, OpenAI, Google or any OpenAI-compatible API. Credentials are yours and never reach the model.
- Schema-checked tools. Input is validated before anything runs. The hosted platform generates MCP tools and OpenAPI from your Zod schemas.
- Replay-safe by lint.
actuate checkflags network calls, provider calls, clocks and randomness outside a step before you deploy. - Tested before it ships.
actuate testruns your tests on the real engine with a clock you control, recording fakes and a rows meter, andactuate devandactuate check --platformapply the hosted platform's guards and deploy checks locally. - Open source. The SDK, runtime, CLI and provider adapters are Apache-2.0. Self-host on Cloudflare Workers, or use the hosted platform at actuate.run.
How it works
run is replayed from the top whenever the run resumes. Completed steps return their stored result instead of running again, so the code reads top to bottom while the run itself survives restarts, retries and days of waiting.
sequenceDiagram
participant Agent
participant Actuator as Actuator (Durable Object + SQLite)
participant Manager
Agent->>Actuator: tools/call refund_order {amount: 240}
Actuator->>Actuator: validate input against the schema
Actuator->>Manager: signed approval link
Actuator-->>Agent: WAITING (receipt with runId)
Note over Actuator: hibernates: no memory, no cost
Manager->>Actuator: Approve
Actuator->>Actuator: replay run(): completed steps return stored results
Actuator->>Actuator: step "refund" runs once
Agent->>Actuator: actuate_get_run(runId)
Actuator-->>Agent: REFUNDED
Each actuator is a Durable Object with its own SQLite database. Steps are journaled in _actuate_steps; sleeps and waits set an alarm or a waiting row and end the invocation. Because of replay, anything with a side effect (network, provider calls, writes, Date.now()) belongs inside ctx.step.do: provider calls outside a step throw at runtime, and actuate check catches the rest. Details: Steps and replay.
Packages
| Package | What it is |
|---|---|
@actuate/sdk |
defineActuator, ctx.step.*, ctx.db, provider types |
@actuate/runtime |
The step engine: journal, replay, sleeps, events, approvals and input links. Runs on workerd with SQLite |
@actuate/cli |
The actuate command (init, dev, test, check, deploy, run, logs, doctor, ...) and the test harness @actuate/cli/testing |
@actuate/providers |
Bring-your-own-credentials adapters for messaging, payments and LLMs |
create-actuate |
npm create actuate, with 11 templates |
Hosted or self-hosted
- Hosted, at actuate.run:
npx actuate deploy, a dashboard with runs, approvals and tables, MCP for your agents, and plans with hard monthly limits (no surprise bills). Free Sandbox plan. - Self-hosted: the open-source runtime runs an actuator as a Worker plus a SQLite-backed Durable Object, on Cloudflare or plain
workerd, with no Actuate account. It serves the runtime HTTP API; MCP and OpenAPI come with the hosted platform. See Self-hosting.
Contributing
Issues and pull requests are welcome. See CONTRIBUTING.md for setup and conventions; security reports go through SECURITY.md, not public issues.
pnpm install
pnpm check # build, typecheck and test: unit tests on node:sqlite, end to end on workerd via Miniflare
Requires Node.js 22 or later and pnpm 10.
License
actuate MCP questions
How do I add actuate MCP to Claude Code?
Run claude mcp add actuate -- npx -y @actuate/cli in your terminal. Add --scope user to make it available in every project.
How do I add actuate MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does actuate ensure a tool doesn't run twice?
It uses a journaling system where each step is recorded. Replays and retried tool calls receive the stored result instead of executing the logic again.
Does actuate charge for periods when a tool is waiting for approval?
No, the system hibernates during sleep or wait periods, meaning nothing runs and nothing is billed until the tool wakes up.
What kind of database does each actuator use?
Each actuator has its own dedicated SQLite database with support for migrations and data exports.