mcp

Authenticate this local Sapiom developer MCP (sapiom-dev) by opening a browser login flow. Run this when a networked agent tool (link/deploy/run/inspect/signal) reports that authentication is required.

Validate an agent locally: typecheck, bundle and import index.ts, derive the manifest, and check the step graph. Needs no Sapiom account or service call to validate; author-written top-level side effects still run when the definition is imported. Returns the agent name, step count, the manifest (which contains the full step graph for visualization), and any warnings — graph warnings, plus one per project file (AGENTS.md, the sapiom-agent-authoring skill) whose platform-rules stamp differs from the copy the Sapiom API currently serves, from a best-effort anonymous read of that endpoint's headers (skipped when the project carries no stamp, silent when unreachable).

Materialize a Sapiom agent locally. Given a template id (from the gallery) it forks the template into a repo you own; given an existing fork id it re-clones that fork; given a deployed agent's definitionId it clones the engine's live build-repo source directly (no fork step, always current) and pre-links the checkout. Either way it mints a short-lived, repo-scoped clone credential, git-clones the repo into <dir>, and writes sapiom.json recording the provenance. After cloning: read the project's AGENTS.md, install its dependencies, then _check → _run_local. Before cloud work, authenticate and run _link → _deploy → _run → _inspect. A templateId/forkId clone is source only and has no dashboard agent until link/deploy; a definitionId clone is already linked because sapiom.json contains its definitionId. Pass exactly one of templateId, forkId, or definitionId. The clone credential is single-repo, read-only, and ~1h-lived — it is used for the clone and discarded (never stored in sapiom.json).

Validate a cron expression and preview its next occurrences, creating nothing. Use before sapiom_dev_agents_schedule to confirm a cron + timezone fire when you expect (cron syntax is easy to get subtly wrong).

Deploy the linked agent: bundle the current local source (including uncommitted source), push a synthesized build tree, trigger a metered cloud build, and wait for it to finish. The project must be linked (sapiom.json) and a git repo with at least one commit.

Emit one custom event for this tenant. It fans out by type to every active 'event' trigger the tenant armed and starts 0..N NEW runs; it never resumes a paused run (use sapiom_dev_agents_signal for that). Events start, signals resume. Returns { receiptId, outcome: 'matched' | 'unmatched', duplicate, fireIds }: 'unmatched' is a success, not an error — it means nothing subscribes to this type, so check it for a typo or arm a trigger with sapiom_dev_agents_schedule (kind 'event'). `fireIds` are trigger fires, not execution ids; read the receipt to get from a fire to the run it started. Pass id to make a retry safe.

Inspect a cloud execution (its steps and errors) by executionId, a build by buildRunId, or list recent executions when neither is given. On a failed step, pull its input here to reproduce the failure locally with run_local. When inspecting an execution, the result includes a `webappUrl` to open that run in the webapp. By default the execution is returned COMPACT: identity/status/timestamps + a per-step summary (name/order/attempt/status/error-message) with a `has` flag-set and a `sizes` hint (char counts of the omitted input/output/logs/events/sharedState bodies). Full step bodies are NOT included by default — they can be multiple MB. To pull a specific step's heavy fields, pass `step` (its name or order, from the compact list) with `include` (e.g. ['input','error']); optionally narrow to one `attempt`. Debug loop: inspect(executionId) → see step N failed → inspect(executionId, step:'<name>', include:['input','error']) → feed that input to run_local. Every field is capped to a char budget; an over-budget value is truncated with a marker pointing at `webappUrl`. Reads are a fresh point-in-time snapshot. To wait for a still-running execution to finish, set wait:true (the tool polls until it settles or the wait window elapses) — do NOT sleep-and-poll this tool yourself. If a wait returns waiting:true, just call inspect again with wait:true.

Resolve a hosted agent by name (or create it with create:true) and cache its id in the project's sapiom.json. Run this before deploy.

Start a real (cloud) execution of the linked agent. Use sapiom_dev_agents_inspect to follow it.

Execute an agent on the local machine, running the author's actual step code with every ctx.sapiom.* capability call resolved from stubs (no Sapiom account, capability request, or capability spend). Author code is ordinary local code: its own filesystem, process, environment, and network effects remain real. Returns { outcome, output, steps[], unusedStubs[], stubWarnings[] }. outcome is 'completed' | 'failed' | 'paused' | 'running'. A paused dispatch (e.g. models.coding.launch) is auto-resumed locally with its stub result, so the happy path runs end-to-end. Returns `unusedStubs` (supplied stub keys that matched no call — a typo or wrong path form) and `stubWarnings` (a stub key matched but its value was the wrong shape for the capability). Check both: a green run with a non-empty unusedStubs/stubWarnings usually means your stub didn't take effect. Stub shape: { version: 1, steps: { <stepName>: { <methodPath>: <response> } } }. The response is the value that call returns verbatim — e.g. `repositories.list` takes the array list() should return ([{ slug, cloneUrl }]), not a wrapped/sequence form. For a dispatched run, stub `models.coding.run` (or `models.coding.launch`) in the step that launches it; that value becomes both the run result and the payload the paused step resumes with — set status:'failed' there to exercise the failure branch.

Scaffold a new Sapiom agent project into <dir>. Produces a TypeScript project with a starter agent in index.ts and its dependencies installed (best-effort; if the install was skipped offline, run `npm install` in <dir>). After scaffolding, the author writes step definitions and uses sapiom_dev_agents_run_local to test them.

Create a trigger for a deployed agent — one of four kinds. 'schedule_cron' (+ cron, optional timezone) runs it on a recurring schedule; 'schedule_once' (+ at) runs it once at a future time; 'event' (+ eventType) runs it every time this tenant emits that event type via POST /v1/workflows/events; 'webhook' runs it every time an external system POSTs to a public hook URL — the result returns that URL plus a shown-once signing secret and the HMAC-SHA256 scheme the sender must use. Use 'webhook' when an external system should start the agent ("run when X POSTs to us") instead of hand-building an HTTP server; third-party senders with their own signature scheme (Slack, Meta, Stripe, GitHub) cannot produce our HMAC, so route those through an App Link /hook/* receiver or a translator. Returns the trigger with its next fire time where it has one. Tip: validate a cron with sapiom_dev_agents_cron_preview first.

Cancel a trigger of any kind by id. Stops all future fires: a recurring schedule won't re-arm, a pending one-off won't run, an event trigger stops matching, a webhook stops accepting POSTs (401 from then on). Irreversible — recreate to re-arm (a recreated webhook gets a new URL + secret). For a webhook whose secret leaked but whose URL should keep working, rotate with sapiom_dev_agents_schedule_secret instead.

Inspect triggers of any kind (cron, one-off, event, webhook). With scheduleId: returns one trigger's config, next fire time (schedules), eventType (event), publicId / secretVersion / graceUntil / revokedAt (webhook — never the secret, which is shown only at create/rotate), and recent fire history (each with the run's executionId, and the inbound receiptId for event/webhook fires) — use this to debug a misbehaving trigger, then inspect a failed run's executionId with sapiom_dev_agents_inspect. With definition (slug) and no scheduleId: lists that agent's triggers.

Webhook-trigger secret lifecycle. 'rotate' = planned hygiene: mints a new secret (returned ONCE, with the hook URL beside it so the sender can be reconfigured in one step) while the previous secret keeps verifying for a 24h grace. 'complete_rotation' = the sender has moved; end the grace now so the old secret stops verifying immediately. 'revoke' = compromise: the hook rejects every request from now on and any open grace dies with it — irreversible, create a new webhook trigger to hand the sender a fresh URL + secret. Only valid on kind 'webhook'.

Resume a paused cloud execution by delivering a named signal (matched by name + correlationId, NOT by executionId — so one call resumes every run waiting on that pair). Signals resume; they never start a run — to start one, emit an event with sapiom_dev_agents_emit_event. Read `message` in the result whenever it is present: `matched` counts the runs that actually resumed, so it under-reports a partial fanout and a 0 does not prove nothing was waiting.

Delete a published App Link. The https://apps.sapiom.ai/{org}/{slug} URL stops resolving (anyone holding it gets a 404), any webhook receiver at its /hook path stops answering, and the slug is freed for reuse. Address the link by slug or appLinkId. This is destructive: ask the user before calling it, then pass confirm: true. Needs the org.write permission; when the credential lacks it the error names the permission — tell the user, do not retry.

List your organization's App Links (durable https://apps.sapiom.ai/{org}/{slug} apps published with sapiom_dev_app_publish): slug, URL, visibility, whether webhooks are on and the /hook URL when they are, daily spend cap, wake rate limit, wake status. Use it to find a link before sapiom_dev_app_settings or sapiom_dev_app_delete, or to answer "what have we published?". Read-only; needs org.read.

Publish this project's web app to a DURABLE Sapiom link: https://apps.sapiom.ai/{org}/{slug}. Use this — not sapiom_dev_sandbox_preview — whenever the user wants a link that is permanent, shareable, or safe to hand to a teammate: a sandbox preview URL expires with the sandbox's ttl, an App Link does not. Reads the same sapiom.json `type: "sandbox"` resource (source dir, start, port, optional build/env), uploads the source as a stored bundle, and activates it. Nothing runs until someone visits: the first visit after a publish cold-starts the app (tens of seconds behind a "Starting…" page), so this is wake-on-demand hosting, not always-on. Org-scoped by default (only logged-in members of your organization can open it); visibility "public" needs confirmPublic: true and a dailySpendCapUsd because your org pays for every wake. Publishing the same slug again replaces the app in place at the SAME URL — that is how you ship an update. The link is a wake-on-visit REDIRECTOR, not a reverse proxy: its root answers a 302 to whichever preview URL is currently serving the app and sub-paths are NOT proxied, so the app's own API lives at that preview URL, never under the link. Read it off the redirect (or from `url` in GET {link}/__status) and re-resolve it per use — it changes when a wake recreates the sandbox and, for an org-scoped app, carries a short-lived token that expires. Both routes run the link's OWN access check — for an org-scoped app that means a logged-in member's browser session, NOT an API key, so its API is browser-only. A public app's link and `/__status` need no session at all, so for machine callers publish the app as `public`, or receive traffic on `/hook/…`, which needs `webhooksEnabled` on the link (off by default, not settable here — REST only). Bundles are TEXT-ONLY (UTF-8 files; no images, fonts, or archives) and capped at 10 MiB; node_modules, .git, dotfiles, symlinks and the project's own sapiom.json are never uploaded — install dependencies at wake via `build`. Both limits are checked locally, so a bad bundle costs no upload. Returns { url, appLinkId, bundleSha256, manifest }.

Change how a published App Link is exposed: turn webhooks on or off (webhooksEnabled), change visibility, set or clear the daily spend cap, set the wake rate limit. Webhooks are OFF by default on every link; once on, third parties POST to https://apps.sapiom.ai/{org}/{slug}/hook/<path> — the /hook prefix is stripped and the body forwarded byte-exact, so Slack/Stripe/GitHub signature checks run inside the app. Address the link by slug or appLinkId and send only the fields to change. These settings need the org.write permission (sapiom_dev_app_publish's publish authority is not enough): when the credential lacks it the error names the permission and the fields — tell the user, do not retry. Setting visibility to public needs confirmPublic: true and a dailySpendCapUsd; ask the user first. Returns { url, webhookUrl, settings, changed }.

The agent map: which agents call, launch, schedule or trigger each other, grouped into systems, with every agent's steps. Computed from code each call; nothing about agents or edges is stored. Pass `root` (a project folder; default the working directory) and optionally a git `ref` to draw that version, or pass `agents` to map your own description without scanning. Systems are connected components over code-proven calls, events, signals and timers; shared vault keys, databases and connectors show as `shared` chips and never join agents. Every edge carries the code location that proves it; calls whose target the code does not make knowable are listed under `unresolved`. When signed in, platform triggers and deploy state come from the account, and Jev labels an agent's `role` and a launch or event edge's `label` where its probability `p` is at least 0.8 (`labels: "ok"`; signed out or Jev unreachable: `labels: "unavailable"`, the map otherwise unchanged). Set `platform: false` to skip both.

Validate the sandbox preview resources in the project's sapiom.json without deploying. Returns { ok, sandboxes, issues }; `issues` lists actionable validation problems to fix before previewing.

Create or update a sandbox preview resource in the project's sapiom.json. Fill the typed arguments instead of hand-writing JSON — the config is validated and written under resources.<name> (type: "sandbox"). Returns the stored config. Use sapiom_dev_sandbox_preview afterwards to deploy it.

Deploy a web-app preview from the current project to a Sapiom sandbox and get a live URL. Reads sapiom.json (a `type: "sandbox"` resource), provisions the sandbox if needed, uploads the local code, builds, starts, and exposes a public URL. Returns { name, url, status, logs }. A `failed` status carries build/start logs (not an error) so you can fix and retry. The URL is TEMPORARY — it expires with the sandbox's `ttl`. For a link that is permanent, shareable, or meant for a teammate, use sapiom_dev_app_publish instead.

Log out of Sapiom by removing cached credentials for the current environment.

Send the user's feedback about Sapiom — a bug, a rough edge, a feature request, or praise — to the Sapiom team. Reach for this when the user says something like "this is broken", "tell Sapiom", "file feedback", or "this should work differently": confirm the wording with them, then send their words as `message`. NEVER put file contents, code snippets, logs, stack traces, environment variables, API keys, or any other secret in `message` or `context` — both fields are plain prose only. Package version, platform, environment, and timestamp are attached automatically; do not restate them.

Check authentication status for this local Sapiom developer MCP (sapiom-dev). Returns whether you're authenticated and which organization.