@sapiom/mcp

@sapiom/mcp

The local developer MCP server for Sapiom. It runs on your machine over stdio under the server name sapiom-dev. Today it gives a coding agent the tools to scaffold, test, deploy, and inspect Sapiom agents; the namespace leaves room for other developer tooling later.

Not the capability surface. This is not the remote "Sapiom" MCP (the hosted connector with sapiom_sandbox_*, scrape, search, … capability tools). sapiom-dev exposes no direct capability tools. Its local check and Local Run path uses stubbed capabilities without Sapiom capability spend; deploys, cloud builds, production runs, signals, and schedules operate Sapiom cloud state and may be metered. See the two Sapiom MCP servers for which to use when.

Install

No global install — run it on demand with npx:

{
  "mcpServers": {
    "sapiom-dev": {
      "command": "npx",
      "args": ["-y", "@sapiom/mcp"],
    },
  },
}

In Claude Code:

claude mcp add sapiom -- npx -y @sapiom/mcp

Configuration

The server targets the production environment by default. Override it with the SAPIOM_ENVIRONMENT environment variable:

{
  "mcpServers": {
    "sapiom-dev": {
      "command": "npx",
      "args": ["-y", "@sapiom/mcp"],
      "env": { "SAPIOM_ENVIRONMENT": "staging" },
    },
  },
}

• production (alias prod) → app.sapiom.ai / api.sapiom.ai — the default.
• staging (alias dev) → app.sapiom.dev / api.sapiom.dev.

Both resolve from built-in presets, so no config file is required. A custom target can be defined in ~/.sapiom/credentials.json (the server prints the expected shape if it encounters an unknown environment name).

Authentication

The first networked call (link, deploy, run, inspect, signal) needs a Sapiom API key. Run sapiom_authenticate and the server opens a browser login flow, then caches the resulting key per environment in ~/.sapiom/credentials.json. After that, tools work without re-authenticating. sapiom_status reports who you're authenticated as; sapiom_logout clears the cached credentials.

The local authoring tools (scaffold, check, run_local) need no Sapiom authentication. scaffold may query npm for current dependency versions; check imports the definition; and run_local executes the author's ordinary local code. Only ctx.sapiom.* calls are replaced by stubs, so direct network, filesystem, environment, and process effects in author code remain real.

Tools

Tool	Network	What it does
sapiom_authenticate	browser	Log in and cache an API key for the current environment
sapiom_status	—	Report authentication status
sapiom_logout	—	Clear cached credentials
sapiom_send_feedback	✓	Relay the user's product feedback to the Sapiom team
sapiom_dev_agents_scaffold	npm optional	Create a new agent project; may query npm for current dependency versions
sapiom_dev_agents_check	author code only	Typecheck, import, bundle, and validate the definition and step graph
sapiom_dev_agents_run_local	author code only	Run locally with ctx.sapiom.* calls stubbed (no Sapiom capability spend)
sapiom_dev_agents_link	✓	Resolve/create the hosted orchestration and cache its id
sapiom_dev_agents_clone	✓	Fork a gallery template (or re-clone a fork) into a local project
sapiom_dev_agents_deploy	✓	Bundle current local source, build in the cloud, and wait
sapiom_dev_agents_run	✓	Start a real cloud execution
sapiom_dev_agents_inspect	✓	Inspect an execution or build (optionally waiting for it)
sapiom_dev_agents_signal	✓	Resume a paused execution by delivering a signal
sapiom_dev_agents_schedule	✓	Create a recurring (cron) or one-off schedule for a deployed agent
sapiom_dev_agents_schedule_inspect	✓	Inspect one schedule (with fire history) or list an agent's schedules
sapiom_dev_agents_schedule_cancel	✓	Cancel a schedule (stops all future fires)
sapiom_dev_agents_cron_preview	✓	Validate a cron expression and preview its next occurrences

A typical loop: scaffold → write step code → run_local until green → link → deploy → run → inspect.

How capabilities fit in

Workflows authored here call Sapiom capabilities — sandboxes, repositories, coding agents, search, storage, content generation — through @sapiom/tools (ctx.sapiom.*). run_local resolves those calls from stubs; deploy and production run cross into authenticated cloud operations and can be metered. This MCP never grows a per-capability tool of its own — capabilities live in @sapiom/tools and the remote sapiom MCP. See the positioning doc for the full policy.

Sending feedback

sapiom_send_feedback relays a user's product feedback (a bug, a rough edge, a feature request) to the Sapiom team. The agent sends only what the user said; the server attaches package version, platform, arch, node version, environment and a timestamp itself, so the model never has to read those off the machine.

A host embedding this server can advertise its own version with SAPIOM_HARNESS_VERSION — it rides along as clientMeta.harnessVersion, which is what makes "which build is this user on" answerable during triage. The field is omitted entirely when the variable is unset, never filled with a placeholder. @sapiom/harness sets it automatically.

Usage analytics

The server emits anonymous usage analytics (one tool.call event per tool invocation: tool name, arguments, duration, ok/error class) via @sapiom/analytics-core to the hosted Sapiom collector by default. Opt out at any time with SAPIOM_TELEMETRY_DISABLED=1 or DO_NOT_TRACK=1 — either makes the emitter a complete no-op (nothing is sent, nothing is written to disk). SAPIOM_ANALYTICS_ENDPOINT overrides the destination. Telemetry is a synchronous in-memory enqueue that never throws, never blocks a tool call, and can never change a tool result.

License

MIT