Roka Docs
MCP
Connect an agent
MCP is a Pro feature. The npm package roka-mcp (v0.2.1+) can be installed by anyone, but connect, serve, and watch verify a Pro API key before they do anything.
ROKA_API_KEY or pass --api-key.Install the package
npm install -g roka-mcp # or one-shot: npx roka-mcp connect --agent cursor --api-key rk_live_...
Requires Node.js 18+. Package name on npm: roka-mcp.
connect
Registers roka-mcp as an MCP server in the agent’s real config file. Idempotent: running it again updates the existing entry in place and does not wipe unrelated servers.
npx roka-mcp connect --agent <name> [--api-key <key>]
| Flag | Description |
|---|---|
| --agent, -a | Required. One of: claude-code, cursor, codex, copilot, vscode, windsurf, cline |
| --api-key, -k | Pro API key, or set ROKA_API_KEY |
Where config is written
| Agent | Config file |
|---|---|
| claude-code | .mcp.json (project root) |
| cursor | ~/.cursor/mcp.json |
| codex | ~/.codex/config.toml — [mcp_servers.roka-mcp] |
| copilot / vscode | .vscode/mcp.json (project), type: stdio |
| windsurf | ~/.codeium/windsurf/mcp_config.json |
| cline | Cline global storage settings (path varies by host editor/OS; logged on run) |
The entry launched by the agent is:
command: npx args: ["-y", "roka-mcp", "serve"] env.ROKA_API_KEY: <your key, if provided>
Restart the IDE after connect so it reloads MCP servers.
Examples
npx roka-mcp connect --agent claude-code --api-key rk_live_... npx roka-mcp connect --agent cursor --api-key rk_live_... npx roka-mcp connect --agent codex --api-key rk_live_... npx roka-mcp connect --agent copilot --api-key rk_live_... export ROKA_API_KEY=rk_live_... npx roka-mcp connect --agent cursor
serve (default)
Starts the MCP server on stdio. This is what the agent launches after connect. You normally do not run it by hand. If you do, it prints a banner on stderr (stdout stays clean for JSON-RPC).
npx roka-mcp@latest # equivalent: npx roka-mcp serve
Missing, invalid, expired, or free-tier keys are rejected: serve will not start tools.
Verification call
The only network call this package makes for MCP is a check against https://api.roka-prune.com/api/status with the key in the Authorization header. Set ROKA_API_URL_BASE to point that check at another host (local development). Log text used by the tools stays on the machine.