Claude Code

The @sapiom/mcp package is an MCP server that gives Claude Code direct access to Sapiom services — authentication, verification, and more — with a browser-based login flow.

Installation

Claude Code Config
CLI Command

Add to your Claude Code settings file (~/.claude/settings.json or project .claude/settings.json):

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

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

Available Tools

Once installed, Claude Code gains access to 5 tools:

Tool	Description
`sapiom_authenticate`	Open browser to log in to Sapiom
`sapiom_status`	Check current authentication status
`sapiom_logout`	Remove cached credentials
`sapiom_verify_send`	Send an SMS verification code
`sapiom_verify_check`	Verify a received SMS code

`sapiom_authenticate`

Opens a browser window for OAuth login. If already authenticated, returns the current session info instead.

This tool takes no parameters.

Behavior:

Starts a local HTTP server on a random port
Opens your browser to the Sapiom login page
After login, exchanges the OAuth code for an API key
Stores credentials locally for future use
Times out after 5 minutes if login is not completed

`sapiom_status`

Returns whether you’re currently authenticated and which organization you’re logged into.

This tool takes no parameters.

`sapiom_logout`

Removes cached credentials for the current environment. You’ll need to run sapiom_authenticate again to use Sapiom tools.

This tool takes no parameters.

`sapiom_verify_send`

Sends an SMS verification code to a phone number. Returns a verification ID needed to check the code later.

phoneNumber string required

Phone number in E.164 format with country code (e.g. +15551234567)

Returns: A verification ID and instructions to collect the 6-digit code from the user.

`sapiom_verify_check`

Checks a verification code that was sent via sapiom_verify_send.

verificationId string required

The verification ID returned by sapiom_verify_send

code string required

The 6-digit verification code the user received via SMS

Returns: Whether the code is correct or incorrect/expired.

Authentication Flow

When you use sapiom_authenticate, the following happens:

Local server — A temporary HTTP server starts on 127.0.0.1 with a random port
Browser redirect — Your default browser opens to app.sapiom.ai/auth/cli with a callback URL and CSRF state parameter
User login — You log in through the Sapiom web app
Callback — The browser redirects back to the local server with an authorization code
Token exchange — The code is exchanged for an API key via api.sapiom.ai/v1/auth/cli/token
Storage — Credentials are saved to ~/.sapiom/credentials.json

After authentication, all other Sapiom tools (like sapiom_verify_send) use the stored API key automatically.

Multi-Environment Support

By default, the MCP server connects to Sapiom’s production environment. For development or staging, set the SAPIOM_ENVIRONMENT environment variable:

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

Custom environments must be defined in ~/.sapiom/credentials.json:

{
  "currentEnvironment": "staging",
  "environments": {
    "staging": {
      "appURL": "https://staging.app.sapiom.ai",
      "apiURL": "https://staging.api.sapiom.ai",
      "services": {
        "prelude": "https://staging.prelude.services.sapiom.ai"
      }
    }
  }
}

Resolution priority: SAPIOM_ENVIRONMENT env var > currentEnvironment in credentials file > "production"

Credential Storage

Credentials are stored at ~/.sapiom/credentials.json with file permissions 0600 (owner read/write only). The file contains:

API key — Used for authenticating requests to Sapiom services
Tenant ID — Your organization’s identifier
Organization name — Display name of your organization
API key ID — Unique identifier for the issued key

Troubleshooting

Browser doesn’t open

If the browser doesn’t open automatically, copy the URL printed in Claude Code’s output and paste it into your browser manually. The MCP server supports macOS, Windows, and Linux.

Authentication times out

The login flow has a 5-minute timeout. If it expires, run sapiom_authenticate again.

”Not authenticated” errors

Run sapiom_status to check your current state. If not authenticated, use sapiom_authenticate to log in. If credentials are stale, use sapiom_logout first, then re-authenticate.

Wrong environment

If tools are hitting the wrong server, check SAPIOM_ENVIRONMENT in your MCP config and verify the environment is defined in ~/.sapiom/credentials.json.

Next Steps

MCP Servers Overview Learn about MCP integrations

Agent Frameworks Programmatic integrations for LangChain