Vruum

Vruum MCP (@vruum/mcp)

[npm] [license] [registry]

Official MCP access to Vruum, the AI revenue platform. Give your agent the whole revenue motion — research prospects, build pipeline, run email and LinkedIn outreach, triage replies, manage deals through close, and read Stripe-backed revenue truth — through 35 compound tools rather than a sprawl of endpoints. Outreach runs inside objectives: a goal, the people it targets, and the policy for reaching them.

This package is a stdio bridge: it serves the tool surface locally (no credentials needed to introspect) and proxies execution to https://api.vruum.ai/mcp under your token. Every call is authorized server-side — the bridge grants no authority your Vruum account doesn't already have.

[!TIP] Using a client that supports remote MCP? Connect directly instead. Claude Code, Claude Desktop, Cursor, Codex and friends should point straight at https://api.vruum.ai/mcp (OAuth 2.1). Fewer moving parts and no token in an env var. This bridge exists for stdio-only clients and for credential-free tool introspection. See vruum.ai/docs/mcp.

Quickstart

You need Node 20+ and a Vruum account. Create a personal access token in the web app under Settings → API tokens (vk_live_…).

{  "mcpServers": {    "vruum": {      "command": "npx",      "args": ["-y", "@vruum/mcp"],      "env": { "VRUUM_MCP_TOKEN": "vk_live_…" }    }  }}

{  "mcpServers": {    "vruum": {      "command": "npx",      "args": ["-y", "@vruum/mcp"],      "env": { "VRUUM_MCP_TOKEN": "vk_live_…" }    }  }}

[mcp_servers.vruum]command = "npx"args = ["-y", "@vruum/mcp"]env = { VRUUM_MCP_TOKEN = "vk_live_…" }

npx @vruum/cli login --token vk_live_…

Verify it works without configuring anything:

npx -y @modelcontextprotocol/inspector --cli npx -y @vruum/mcp --method tools/list

Reliability diagnostics

The bridge records content-free operational metadata: generated attempt IDs, the declared client family (Claude/Codex/ChatGPT/unknown), known tool name, start/outcome, timestamp and duration. It never records tool arguments, results, credentials, raw error text or conversations. The private outbox is under ~/.vruum/mcp-diagnostics/ (or VRUUM_CONFIG_DIR), separated by endpoint.

Records survive bridge restarts and upload to that same endpoint's authenticated /diagnostics route after connectivity returns. Only a durable acknowledgement removes them. A restored connection drains the backlog in bounded batches. Transient failures retry once per minute while the bridge is alive; authentication or unsupported-endpoint responses wait for subsequent activity/startup. Uploads never follow redirects or transmit credentials over non-local HTTP. The queue retains at most 500 records per endpoint and reports overflow; disk failures print a coverage warning on stderr. Stdout remains MCP JSON-RPC.

Missing-token, connection, protocol, cancellation, invalid-cursor and call failures are observable when the bridge runs. An offline machine cannot deliver reports until it reconnects, and an old installed package has none of these diagnostics. A bridge success means it received the remote result, not that the host used it correctly. Business calls are never automatically replayed after an ambiguous failure. Server and bridge evidence correlate by attempt ID.

What you can ask for

Once connected, these are ordinary requests to your agent:

Your harness authors outreach copy, replies, LinkedIn posts, and comments through their review surfaces. It can also chat with Vruum through manage_assistant (start_conversation, append_message): the same chat as the app's floating panel, which reads your records and applies reversible record changes with Undo. The chat does not draft or send messages.

Tool surface

35 compound tools. Read operations inspect saved data; write operations mutate it. Some writes buy provider work or produce external effects. Each tool describes its own authorization and retry contract.

manage_outreach also creates, configures, launches, and pauses objectives; inspect_objective reads an objective's setup, audience, forecast, and sourcing plan. No tool mixes reads with writes: research_lookup holds the external lookups (work email, LinkedIn profile, company website, careers page, LinkedIn people search), which can spend provider credits or LinkedIn budget. get_operator_companies lists the workspaces your login can act in; it is not limited to Vruum staff.

Full schemas, descriptions and MCP safety annotations live in tools.json — generated from the live server definition, never hand-edited.

The current package also carries the retained-email decision instructions in manage_messages. A saved email uses its displayed Action version, proposal revision, and fingerprint. Approval is not a delivery receipt; changed content requires new work.

Chat with Vruum through manage_assistant. start_conversation takes payload={request_id, message, context?} and waits up to 50 seconds for the answer; append_message takes id=<chat UUID> and the same payload. The result names the chat, the turn's state, the question, the answer, changes (each record change the chat applied, with its Undo state) and cards. A turn still running after 50 seconds returns running; read the chat later with inspect_assistant action=read id=<chat UUID>. Actions Undo cannot reverse, and actions that reach a customer or spend, come back as a card with the exact call, and the turn returns awaiting_approval. manage_assistant action=decide_card id=<item UUID> payload={decision: approved|declined} decides one, only with the user's own answer: approved runs that exact call once under your credentials, declined never runs it; it waits up to 50 seconds for the turn. manage_assistant action=undo id=<item UUID> runs a change's exact inverse and is refused when the record was edited since; action=rate id=<message UUID> rates an answer. Keep the same request_id on a retry after an uncertain response: the server runs each request once.

Configuration

How it works

your agent  ──stdio/JSON-RPC──▶  @vruum/mcp                                     │                    tools/list ──────┤  served locally from tools.json                                     │  (no network, no credentials)                                     │                    tools/call ──────┴──HTTPS+Bearer──▶  api.vruum.ai/mcp                                                          (authorized server-side)

Listings are a static snapshot bundled at release. That's what makes credential-free introspection possible, and it means a newly added tool won't appear until the next release — calls still execute correctly, since they proxy through. In the monorepo, a snapshot test fails any change that lets tools.json drift from the server definition, so a release never ships a stale listing.

Safety and credentials

• Server-side authorization. The bridge adds no permissions. Your token is exactly your Vruum account, and role/tenant checks happen on the server.
• No automatic retries. A failed tools/call is never replayed. Many of these tools send outreach or spend money, and an ambiguous failure may mean the server already executed — a silent retry could double-send. The connection is discarded, the error says so, and your agent decides whether re-running is safe.
• Your token never leaves your machine except as a Bearer header to api.vruum.ai.

[!WARNING] The bridge picks up ambient credentials. With no VRUUM_MCP_TOKEN set it falls back to ~/.vruum/credentials. If you are logged in with the Vruum CLI, then running this server — via the MCP Inspector, a client, or a script — executes against your real account and real data. Write tools will really write.

To poke at it with no credentials, pass an explicit env that reaches the process:

sh

env -i PATH="$PATH" HOME=/tmp/empty node dist/index.js

Note that MCP clients following the SDK default only forward an allowlist (HOME, PATH, SHELL, TERM, USER, LOGNAME) to spawned servers — so setting VRUUM_CONFIG_DIR in your shell may be stripped before it reaches the bridge, while HOME survives and the credentials file is found anyway. Set credentials in the client's own env block instead.

Development

This repo is a build artifact of the Vruum monorepo, resynced automatically on release. tools.json is generated from the server definition, and a snapshot test in the monorepo fails when the two differ. Between releases, the hosted server can be ahead of this snapshot.

src/index.ts   the bridge — token resolution, static listings, proxied callstools.json     generated tool surface (do not edit by hand)test/          black-box tests: spawn the built binary, speak raw JSON-RPC

npm installnpm test        # builds, then runs the black-box suitenpm run typecheck

Tests drive the built binary over stdin/stdout and assert at the wire level rather than through an SDK client — an SDK-mediated test hides protocol mistakes, since it will happily hand back a result object whether the server returned result or error. They cover the initialize handshake (including negotiation down to older clients on earlier spec revisions), credential-free listing, protocol-vs-execution error semantics, cursor rejection, capability declaration, and stdout hygiene.

Issues and PRs are welcome here. Maintainers apply accepted changes upstream in the monorepo and they flow back on the next sync — so a merged fix here may appear as part of a sync commit rather than your original one. Changes to tools.json must come from the generator, not by hand.

Links

Vruum · MCP docs · Getting started · CLI reference

Registry entry ai.vruum/mcp · Claude & Codex plugin vruum-gtm/skills

License

MIT