MCP Server Setup

End-to-end setup is three steps:

1. Install the sikkerkey-mcp binary on the machine that will run your AI client.
2. Provision an AI agent identity from the dashboard. This issues a one-time bootstrap token.
3. Register the binary with your AI client (Claude Code, Codex, Cursor, etc.) using the agent identity.

The MCP server runs locally as a child process of your AI client. There is no daemon to start manually and no port to open.

Prerequisites

• A SikkerKey vault with the AI agents feature available on your plan.
• An AI client that supports MCP over stdio. Tested clients are listed under Compatibility.
• Linux, macOS, or Windows (the binary is platform-native).

Install the binary

npm (recommended)

npm install -g @sikkerkey/mcp

Downloads the correct prebuilt binary for your platform automatically and exposes it as sikkerkey-mcp on PATH.

Or run without installing:

npx @sikkerkey/mcp <subcommand>

Build from source

The MCP server is a Go module with no external runtime dependencies:

git clone https://github.com/SikkerKeyOfficial/sikker-key
cd sikker-key/mcp
go build -o sikkerkey-mcp .
sudo mv sikkerkey-mcp /usr/local/bin/

Verify

sikkerkey-mcp --help

Provision an AI agent

Each MCP server runs as exactly one AI agent. Provisioning is dashboard-only by design (it would be a privilege-escalation path to let an AI agent provision new AI agents).

1. Open the dashboard, go to Machines, and select the AI Agents tab.
2. Click Bootstrap AI agent.
3. Pick a name, the scopes the agent should hold, and an optional project allowlist.
4. The dashboard issues a one-time bootstrap token. Copy it.

Pick scopes deliberately. The default minimum is audit.read (so the agent can answer questions about vault state). Add write scopes only for surfaces you actively want the AI to manage. See the Security Model for the full scope list and what each unlocks. The scope set is set at provisioning time and can be edited from the dashboard later, but cannot be self-modified by the agent.

Register the bootstrap token

On the machine that will run the AI client:

sikkerkey-mcp install <token>

This:

• Generates an Ed25519 keypair locally.
• Sends the public key to SikkerKey along with the bootstrap token to register.
• Stores the keypair at ~/.sikkerkey/agents/<agentId>/.
• Returns the assigned agent id.

Pass -name=<name> to override the server-assigned default. The token is one-shot: re-running install with the same token fails. The private key never leaves the machine.

After registration, the agent is in the pending state and cannot make calls. Approve it from the dashboard to activate.

Verify

sikkerkey-mcp whoami

Lists every agent identity registered locally with their ids, names, and approval status.

Register with your AI client

The config subcommand prints a ready-to-paste config block for the supported clients.

Claude Code

sikkerkey-mcp config claude-code

Prints a JSON block to add to ~/.claude.json (user-scoped) or .mcp.json in your project root (project-scoped, checked into the repo). Or use the helper command Claude Code provides:

claude mcp add sikkerkey $(which sikkerkey-mcp) serve

Codex

sikkerkey-mcp config codex

Prints a TOML block to append to ~/.codex/config.toml.

Cursor

sikkerkey-mcp config cursor

Prints a JSON block to paste under mcpServers in ~/.cursor/mcp.json (user-scoped) or .cursor/mcp.json (project-scoped).

Claude Desktop

sikkerkey-mcp config claude-desktop

Prints a JSON block to paste under mcpServers in:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart Claude Desktop after editing.

Multiple agents on one machine

If whoami shows more than one local agent, the config output disambiguates them with per-agent keys (e.g. sikkerkey-prod, sikkerkey-staging). Each entry sets SIKKERKEY_AGENT_ID in the env so the binary picks the right identity at startup.

Verify

After registering with your client, restart it and check that the SikkerKey tools appear. The simplest sanity check is to ask the AI to list machines or recent audit entries. The first call exercises the full path: AI client invokes the binary, MCP signs the request, server validates the signature and the agent's scope, returns metadata.

If a call fails:

• auth_failure: agent not found: the agent id in the env doesn't match a row in the database. Re-run sikkerkey-mcp whoami and confirm the agent id.
• auth_failure: timestamp out of window: the local clock is off by more than 5 minutes. Sync NTP.
• auth_failure: agent is pending: the agent has registered but hasn't been approved. Approve from the dashboard.
• auth_failure: agent is disabled: the agent was disabled from the dashboard. Re-enable it or use a different agent.
• scope: missing required scope ...: the agent's scope set doesn't include the scope this tool needs. Edit the scope set from the dashboard.

Local files and where they live

SIKKERKEY_HOME overrides the base directory if you want a custom location (e.g. for CI). The directory layout is identical to ~/.sikkerkey/vaults/... used by the SDK and CLI for machine identities, just with agents/ instead of vaults/.

Revoking an agent locally

sikkerkey-mcp revoke <agentId>

Removes the local keypair and identity files. This does not unregister the agent on the server. To fully revoke, run revoke locally and then revoke from the dashboard. If you only run revoke locally, the agent's row stays in the database but no client can authenticate as it (because the private key is gone).

The dashboard-side revoke is the authoritative one. The local revoke is a cleanup convenience.

Next steps

• Tools Reference: every tool, action, and example.
• Security Model: authentication, authorization, plaintext contract, audit.