Sapiom Cloud MCP

Use Sapiom Cloud MCP when you want a standalone cloud operation without creating or opening an agent project: search the web, capture a screenshot, call a model, run compute, store data, or use another capability advertised by the current server.

If you are building or deploying from a local project, connect Sapiom Project MCP instead.

Connect and authenticate

The cloud connection requires a Sapiom credential before its tools can run. Create an API key in Sapiom settings, then keep it in your shell rather than a project file:

export SAPIOM_API_KEY="your_api_key_here"

1. Register Sapiom Cloud MCP

   Claude Code

   claude mcp add --scope user --transport http sapiom-cloud https://api.sapiom.ai/v1/mcp --header "x-api-key: $SAPIOM_API_KEY"

   --scope user makes the connection available across Claude Code projects. Your shell expands the key before Claude Code stores the configuration, so do not commit that configuration or paste key-bearing diagnostics into an issue or chat.

   Codex

   codex mcp add sapiom-cloud --url https://api.sapiom.ai/v1/mcp --bearer-token-env-var SAPIOM_API_KEY

   Codex stores the environment-variable name rather than the key value. Make SAPIOM_API_KEY available in the environment that launches Codex. The CLI, IDE extension, and Codex desktop app share MCP configuration on the same host.

2. Verify the connection

   Claude Code

   claude mcp list

   Look for sapiom-cloud, the URL https://api.sapiom.ai/v1/mcp, and a connected status. Some Claude Code versions can render configured header values in detailed diagnostics, so do not share raw output.

   Codex

   codex mcp get sapiom-cloud

   Look for an enabled streamable-HTTP connection. In the Codex terminal UI, /mcp shows active servers and authentication state.

3. Make a first call

   Ask your client:

   Check my Sapiom Cloud connection, then find the best available tool to search the web for today’s Sapiom news.

   The client checks the connection and discovers the current capability instead of relying on a fixed catalog copied from documentation.

Discover current capabilities

Ask for the outcome in ordinary language: “search the web,” “turn this text into speech,” “capture a screenshot,” or “run this code in a sandbox.” Your coding agent can search the current Cloud MCP catalog, inspect the selected input contract, and show you what it plans to call.

The server’s tool catalog is authoritative and can change independently of this page. It can include cloud agent lifecycle, resource-lifecycle, and governance operations as well as one-off capabilities. A name prefix does not prove that an operation is read-only; review the selected operation and your client’s approval prompt before allowing it.

Connection aliases are not tool namespaces

The sapiom-cloud alias labels this configured connection. It does not rename the tools the server advertises, and some clients merge every MCP connection into one flat tool list. Do not use sapiom_* as a cloud-only allowlist: it also matches Project MCP’s sapiom_dev_* tools. Allow exact operations when the distinction is a security boundary.

The hosted browser family provides page fetch, screenshots, session lifecycle, and a CDP URL. It does not expose raw navigation, click, or form-fill tools. Connect a CDP-compatible library such as Playwright to the returned URL when you need to drive a session, and always terminate the session when finished.

Troubleshooting

Unauthorized or 401

Confirm the API key is current and available in the shell that runs your client. For Claude Code, remove and re-add the connection after changing the key because its stored header contains the expanded value. For Codex, restart it after updating SAPIOM_API_KEY.

Project tools appeared instead

Check the configured connection name and transport. sapiom-project should start local @sapiom/mcp through npx; sapiom-cloud should point to https://api.sapiom.ai/v1/mcp.

A copied tool name is missing

Reconnect the client and use tool_discover. Do not substitute an alias from an old page, assume a fixed tool count, or call a write operation absent from the current tools/list response.

Building an agent instead?

Follow Build your first agent. Sapiom Project MCP and Agent Studio can work from a local checkout, test with stubs, and carry the project through deployment.

Next steps

Browse capability guides Understand each product area and its supported surfaces.

Call from code Use the versioned @sapiom/tools package from your own process.

Build an agent Use Agent Studio or Sapiom Project MCP for multi-step, deployable work.