Connect and authenticate Sapiom MCP

Connect Sapiom MCP when you want Claude Code or Codex to create and operate an agent from a local checkout without opening Agent Studio.

You need Node.js 18 or newer, one supported coding agent, a Sapiom account, and network access for the first uncached npx download and browser sign-in. Sapiom authentication is required before you use MCP project tools, including scaffold, check, and Local Run.

1. Register Sapiom MCP

   Claude Code

   Run this from the project where you plan to use Claude Code:

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

   Claude Code registers a local-scope stdio connection by default. The -y flag accepts the npx package-install prompt; it does not authenticate you to Sapiom.

   Codex

   Run:

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

   Codex stores MCP configuration in its normal configuration file. The Codex CLI, IDE extension, and desktop app share that configuration on the same host.

2. Authenticate Sapiom MCP

   Ask your coding agent:

   Connect my Sapiom account and confirm the organization and tenant. Also report the configured Sapiom environment if it is exposed; do not infer one from the organization name.

   Sapiom MCP opens browser sign-in and stores the resulting credential in the current environment’s entry in ~/.sapiom/credentials.json. Complete this step before asking the coding agent to create, edit, check, or locally run an agent.

3. Ask for a project outcome

   Start your coding agent in an agent-project folder and describe the result you want. For example:

   Create the default Sapiom starter here, install its dependencies, check it, and run it locally with the input { "name": "Ada" }.

   The coding agent selects the appropriate project tools and constructs their inputs. Raw tool identifiers, generated input schemas, side effects, returns, and failure modes remain available in the Sapiom MCP tool reference when you need exact automation or troubleshooting details.

Authentication and execution location

Action	Sapiom account?	What happens
Scaffold or edit a project	Yes	Requires an authenticated MCP connection, then writes ordinary local files; scaffold may query npm for package versions.
Check	Yes	Requires an authenticated MCP connection, then type-checks, bundles, imports, and validates on your machine.
Local Run	Yes	Requires an authenticated MCP connection, then executes authored code locally with Sapiom capability calls stubbed.
Link, deploy, Prod Run, inspect, schedule, or signal	Yes	Uses the same authenticated connection and additionally reads or changes organization-owned cloud state.

Claude Code uses your Anthropic authentication, and Codex uses your OpenAI authentication. That coding-agent account is separate from the Sapiom account required to use Sapiom MCP.

The alias labels the connection; it does not rename tools

sapiom-project is the configuration name used by the copyable commands above. A tool name or approval prompt may not include that alias. If you maintain a tool allowlist, allow exact tools deliberately.

Troubleshooting

The coding-agent command is missing

Install the client you chose and confirm claude --version or codex --version succeeds in the same shell, then rerun the registration command.

The connection is disabled or disconnected

Confirm the stored command is npx with arguments -y @sapiom/mcp, then restart the coding agent. The first uncached start needs access to the npm registry.

Scaffold finished but check cannot resolve the agent package

Scaffold attempts dependency installation and returns dependenciesInstalled. If that field is false, project creation still succeeded but the best-effort install did not. Ask your coding agent to repair dependency setup in the generated project, then check it again.

Build your first agent Use the connected project tools to create and verify the default starter.

Sapiom MCP overview See the complete task map and where each part of the lifecycle runs.