@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, and to put a web app behind a live sandbox URL or a durable App Link; 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

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

For a web app rather than an agent: sandbox_configure → sandbox_preview while iterating (a throwaway URL that dies with the sandbox) → app_publish once the link needs to be permanent or shared. app_publish reads the same sapiom.json sandbox resource, uploads the source as a stored text-only bundle (≤ 10 MiB), and returns a durable https://apps.sapiom.ai/{org}/{slug} URL that wakes the app on demand — republishing the same slug updates it in place. See the sapiom-sandbox-preview skill for the routing rules.

Once a link exists, app_list, app_settings and app_delete manage it without leaving the terminal. Webhooks are off by default: app_settings { slug, webhooksEnabled: true } turns them on, after which 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). These settings need the org.write permission — publish authority alone is not enough — and a refusal comes back as a message naming the permission and the fields, for the agent to relay rather than retry.

How capabilities fit in

Agents 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