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/mcp

MCP 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`.
Optional local CLI	You need local files, scripting, CI, auth debugging, or a one-command local setup helper.	`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. The Vruum CLI is not required: a direct MCP connection plus installed Vruum skills is a complete setup. Install the local @vruum/cli only when you need its command tree, local-file operations, scripting, CI, auth debugging, or vruum init.

Technical local setup:

vruum login
vruum init

vruum 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>
codex

Hosted 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 run `claude mcp add -s user --transport http vruum https://api.vruum.ai/mcp --header "Authorization: Bearer <token>"`.
Codex CLI	Plugin when available, or run `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	Add the server through Cursor's MCP UI/config. The optional `vruum init` helper can write `~/.cursor/mcp.json` for you.
Cline	Add the server through Cline's MCP settings. The optional `vruum init` helper can write `cline_mcp_settings.json` for you.
OpenCode	Add the remote Vruum MCP entry to the private global OpenCode config, or use the optional `vruum init` helper.
Windsurf	Add the server through Windsurf's MCP settings, or use the optional `vruum init` helper.
Gemini CLI	Add the server through Gemini's MCP settings, or use the optional `vruum init` helper.
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 want the optional vruum init helper to configure a local harness.
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.

Connect

MCP vs local CLI

Connect by harness

Verify setup

When to use CLI instead

See also