Connect Claude Code with MCP

Connect Claude Code directly to Sapiom’s local authoring MCP when you want to work from Claude’s terminal or IDE experience without opening Agent Studio.

You need Claude Code, Node.js 18 or newer, and network access for the first uncached npx download. A Sapiom account is not required to scaffold, check, or run an agent locally.

1. Register the server

   From the folder in which you plan to use Claude Code, run exactly:

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

   Claude Code registers a local-scope stdio server by default. The configuration stores:

   Field	Value
   Registration alias	sapiom
   Command	npx
   Arguments	-y @sapiom/mcp

   The -y flag accepts the npx package-install prompt. It does not authenticate you to Sapiom.

2. Verify the connection

   Run:

   claude mcp get sapiom

   The entry should report Connected and show npx with the arguments -y @sapiom/mcp. If Claude Code was already open, start a new session so it loads the new server.

3. Check the tool identity

   Three names appear in this setup, and each owns a different layer:

   Name	What it identifies
   sapiom	The client-local alias you chose in claude mcp add
   @sapiom/mcp	The npm package Claude starts through npx
   sapiom_dev_*	The local authoring tool namespace exposed by the server

   The alias does not rename the tools. After connecting, Claude should see tools including sapiom_dev_agents_scaffold, sapiom_dev_agents_check, and sapiom_dev_agents_run_local.

4. Start with local authoring

   Ask Claude to scaffold into an empty directory by calling sapiom_dev_agents_scaffold with an absolute dir and the default template. The scaffold is npm-install-ready, so run npm install before the first full check.

   Continue to Build your first agent for the exact scaffold, check, input, and verified local-run result.

Local and cloud tools

The same package exposes local authoring and authenticated cloud-lifecycle tools:

Operation	Requires a Sapiom account?	Boundary
Scaffold	No	Writes a local project; may query npm for package versions
Check	No	Type-checks, bundles, and validates locally
Local run	No	Runs real step code with stubbed capabilities and no capability spend
Link, deploy, production run, inspect, schedule, signal	Yes	Reads or changes hosted Sapiom state

If a local operation works while sapiom_status reports signed out, that is expected. Authenticate only when you reach the first cloud action.

Not the hosted capability MCP

This package scaffolds and operates an agent from a local checkout while Claude edits its source. The hosted capability MCP is a separate Direct Access surface for remote tool calls and implemented cloud operations. MCP aliases must be unique, so do not register both surfaces under sapiom in the same Claude Code scope.

Troubleshooting

claude: command not found

Install Claude Code and confirm the claude executable is on your PATH, then rerun the registration command.

The server is disconnected

Run claude mcp get sapiom outside an active Claude session. Confirm the command and arguments match this page, then start a new session. The first uncached start needs access to the npm registry.

Check cannot resolve @sapiom/agent

The scaffold does not install dependencies. Run npm install in the scaffolded agent project, then call sapiom_dev_agents_check again.

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

Understand local and cloud See exactly where authentication and real capability spend begin.