MCP
Connect the Vruum MCP server to an agent harness, authenticate it, verify setup, and know when to use the CLI.
The Vruum MCP server is:
https://api.vruum.ai/mcpMCP lets an AI harness call Vruum tools directly. Every call is authorized server-side under your token. MCP does not grant authority beyond what your Vruum account can already do.
MCP is the runtime. Skills are workflow instructions. Plugins are the packaging layer that can install or configure both for a harness.
Connect
Use the simplest path your harness supports:
| Path | Use when | Result |
|---|---|---|
| Plugin | The harness supports installing Vruum as one unit. | MCP connection plus skills/instructions where the harness supports them. |
| Direct remote MCP | The harness supports remote MCP but not plugins. | The agent can call Vruum tools from https://api.vruum.ai/mcp. |
| Local CLI setup | You are technical, running a local coding harness, debugging, or using local files. | vruum init writes MCP config and installs skills for supported harnesses. |
MCP vs local CLI
The MCP server exposes supported workflows as explicit tools. It does not run
the CLI server-side. Technical users who need the full command tree should
install and run the local @vruum/cli in their own
harness or terminal.
Technical local setup:
vruum login
vruum initvruum init requires the Node-based CLI and writes Bearer-auth MCP
configuration for supported harnesses. Non-technical clients should prefer a
plugin or direct remote MCP setup when available.
For Codex, export the token before launching Codex:
export VRUUM_MCP_TOKEN=<your-vruum-token>
codexHosted chat clients that support remote MCP can connect to
https://api.vruum.ai/mcp and authenticate with your Vruum login or token,
depending on the client.
Connect by harness
| Harness | Recommended MCP path |
|---|---|
| Claude Code | Plugin when available, or vruum init, which runs claude mcp add -s user --transport http vruum https://api.vruum.ai/mcp --header "Authorization: Bearer <token>". |
| Codex CLI | Plugin when available, or vruum init, which runs codex mcp add vruum --url https://api.vruum.ai/mcp --bearer-token-env-var VRUUM_MCP_TOKEN. Export VRUUM_MCP_TOKEN before launching Codex. |
| Cursor | vruum init writes ~/.cursor/mcp.json with a Bearer-auth HTTP MCP entry, or add that server through Cursor's MCP UI/config. |
| Cline | vruum init writes Cline's cline_mcp_settings.json with a streamableHttp Vruum server entry. |
| OpenCode | vruum init writes the private global OpenCode config with a remote Vruum MCP entry. |
| Windsurf | vruum init writes ~/.codeium/windsurf/mcp_config.json with serverUrl and the Bearer header. |
| Gemini CLI | vruum init writes Gemini settings with an httpUrl Vruum MCP entry. |
| ChatGPT and other hosted MCP clients | Use the client's remote MCP setup flow and connect https://api.vruum.ai/mcp. |
For local config files, vruum init stores Bearer credentials in the harness
config path the harness expects. Do not paste tokens into project files or
agent instructions.
Verify setup
After connecting MCP, ask your agent to confirm it can see Vruum and run a read-only Vruum check. If the server is missing, rerun setup and restart the harness. If auth fails, confirm the Vruum token or client login used by that harness.
When to use CLI instead
Use local CLI when:
- MCP is unavailable in the harness.
- You are setting up a local harness with
vruum init. - The operation needs a local file, such as
vruum people import csv ./file.csv. - You need shell pipelines,
jq, CI, or deterministic exit codes. - You are debugging auth with
vruum whoami --json.
Use MCP when:
- The agent is already in a chat/harness with Vruum tools loaded.
- You want it to read evidence, act, and summarize in one transcript.
- You are invoking or publishing skills.
See also
- Getting Started — install, login, init, first call.
- Skills — workflow skills and the calls they use underneath.
- CLI Reference — granular command tree and exit codes.