Vruum MCP (@vruum/mcp)

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 29 compound tools rather than a sprawl of endpoints.

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
vruum login --token vk_live_…

Verify it works without configuring anything:

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

What you can ask for

Once connected, these are ordinary requests to your agent:

[!IMPORTANT] Your agent writes the prose — the server never does. Outreach copy, replies, LinkedIn posts and comments surface to your harness as work items. Vruum schedules, gates, persists and sends; it has no server-side message generation. That's a deliberate design position, not a gap.

Tool surface

29 compound tools — one per decision, so an agent never disambiguates between overlapping verbs. read is safe to call freely; write mutates; destructive can delete or archive.

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

The 0.5.0 package includes the deployed P2e revenue contracts in that snapshot: get_revenue account and service-margin views, and the reviewed finance-statement action in manage_revenue. Hosted remote MCP already exposes these contracts; stdio clients receive the updated advertised schema after package publication and upgrade. Finance attestation, binding decisions and measurement approval retain their separate server-side checks.

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. A CI guard regenerates tools.json on every backend change, so the snapshot can be one release old but never silently wrong.

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

Copy

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 live server definition, so it cannot drift from what the hosted server exposes.

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

npm install
npm test        # builds, then runs the black-box suite
npm 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, 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