Get Started

Sapiom gives your coding agent everything it needs to build agents — controlled, multi-step, deployable automations with instant access to paid capabilities (search, compute, browsers, AI models, file storage, and more), pay-per-use, with zero vendor onboarding.

Capability = Reasoning × Access. Your models have the reasoning. Sapiom is the access.

1. Connect Sapiom to your coding agent

Pick your environment:

/plugin marketplace add sapiom/sapiom-js
/plugin install sapiom

The plugin registers the sapiom-dev MCP server and ships the sapiom-agent-authoring skill, so your agent knows when and how to build Sapiom agents.

Or add just the MCP server:

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

Or add it to a settings file (~/.claude/settings.json, or project .claude/settings.json):

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

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

Or add it to ~/.codex/config.toml (a project-scoped .codex/config.toml also works; the CLI and IDE extension share this config):

[mcp_servers.sapiom]
command = "npx"
args = ["-y", "@sapiom/mcp"]

Or add it to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

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

Add to claude_desktop_config.json (Settings → Developer → Edit Config; on macOS the file lives at ~/Library/Application Support/Claude/claude_desktop_config.json):

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

Hosted clients can’t run npx or write local files, so the local authoring server isn’t available there. Use the Remote MCP instead — it exposes Sapiom’s capabilities as direct tools over HTTP, no local server needed.

Any MCP client that can launch a local (stdio) server works — point it at the same command in your client’s MCP configuration:

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

2. Authenticate

Run the sapiom_authenticate tool once — it opens a browser to approve access, then caches your key in ~/.sapiom/credentials.json for every subsequent call. Check status anytime with sapiom_status. No API key to paste.

3. Build your first agent

Tell your coding agent what you want to automate — or follow the quickstart yourself:

Build an Agent Scaffold → write steps → test free with stubs → deploy. Your first running agent in about five minutes.

Just need one tool call? Call any capability directly — a search, a scrape, one image — without building an agent.

Troubleshooting

”Unauthorized” when deploying or running

Run sapiom_authenticate to sign in (it caches your key in ~/.sapiom/credentials.json), then confirm with sapiom_status. The offline tools (check, run_local) work without signing in; deploy and run require it.

Tools not appearing

Restart your AI client after adding the server. Confirm the config runs npx -y @sapiom/mcp — the first run downloads the package, which can take a few seconds.

Timeout errors

Cloud steps (deploy, run, image/video generation) can take 15–30 seconds or more. Iterate offline with run_local (capabilities stubbed) before deploying.