@mentoringo/vantage-ops-mcp

MCP server that makes Vantage CRM operable from Claude Code. Read-only DynamoDB queries plus authenticated write tools that flow through the Vantage Lambda API.

Install this in your local environment so Claude Code can search, mutate, and orchestrate Vantage records on your behalf — creating companies, launching campaigns, tracking outreach, advancing pipeline stages, and more.

Location: This package lives at tools/vantage-ops-mcp/ inside the mentoringo/vantage monorepo. It is published to npm as @mentoringo/vantage-ops-mcp so end users do not need to clone the repo.

Architecture

flowchart LR
    subgraph local["Your machine"]
        CC[Claude Code]
        MCP[vantage-ops MCP<br/>this package]
        ENV[(env<br/>VANTAGE_MCP_KEY)]
    end
    subgraph aws["AWS (us-east-1)"]
        APIGW[API Gateway<br/>/mcp/proxy+]
        AUTH[api_key_authorizer]
        LAM[Unified Lambda<br/>scope-gated handlers]
        DDB[(DynamoDB<br/>vantage-*)]
    end

    CC -- stdio --> MCP
    ENV -. resolve on startup .-> MCP
    MCP -- HTTPS + Bearer key --> APIGW
    APIGW --> AUTH
    AUTH -- allow + scopes --> LAM
    LAM -- @require_scope<br/>checks scope --> DDB

    style MCP fill:#e0f2fe
    style AUTH fill:#fef3c7
    style LAM fill:#fef3c7

One path. Reads and writes both flow through /mcp/{proxy+} with a scope-gated bearer token. Reads hit a /v2/mcp-reads dispatcher (scope mcp:read) that executes allowlisted DynamoDB queries with the Lambda's IAM role; writes hit resource endpoints that run the same handlers the dashboard uses, preserving slug generation, stage history, audit trails, and access control. No AWS credentials are required on the operator machine.

Full tool reference: docs/TOOLS.md Scope / key model: docs/SCOPES.md Common workflows: docs/RECIPES.md

Who this is for

Team operators with a provisioned VANTAGE_MCP_KEY. If you don't have a key yet, ask the platform admin — your key's scopes determine which tools you can use.

Typical rollouts:

| Role | Scopes on key | Tools available | |---|---|---| | Full operator (Justin, biz partner) | * or all :* | Every read + write tool | | BD researcher | companies:*, contacts:*, activities:write | Read everything + create contacts + log activities | | SDR / caller | contacts:write, activities:write, outreach:write | Log touches, update contacts, record outreach attempts | | Read-only analyst | *:read | All reads, no mutations |

Prerequisites

• Node 20+
• VANTAGE_MCP_KEY — issued once by the platform admin; covers both reads and writes. Your key's scopes (mcp:read, contacts:write, etc.) determine which tools you can call.

Install

Add to ~/.claude.json under mcpServers:

{
  "mcpServers": {
    "vantage-ops": {
      "command": "npx",
      "args": ["-y", "@mentoringo/vantage-ops-mcp@latest"],
      "env": {
        "VANTAGE_MCP_KEY": "vk_live_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Restart Claude Code. The first invocation pre-warms the npx cache (~3 seconds); subsequent starts are instant.

To pin a specific version instead of tracking @latest, swap the tag: @mentoringo/[email protected].

Bundled skills

Slash-command workflows (/vet-leads, /lead-enrich, /contact-enrich, /campaign-launch) ship in .claude/skills/ and need to be linked into ~/.claude/skills/ so Claude Code discovers them. Until a published install-skills workflow lands (tracked in vantage roadmap), copy them by cloning vantage once:

git clone [email protected]:mentoringo/vantage.git ~/repo/vantage
ln -s ~/repo/vantage/tools/vantage-ops-mcp/.claude/skills/* ~/.claude/skills/

The MCP tools themselves do not require the clone — npx handles those.

From-source install (contributors)

git clone [email protected]:mentoringo/vantage.git ~/repo/vantage
cd ~/repo/vantage/tools/vantage-ops-mcp
npm install
npm run build
npm run install-claude

npm run install-claude does two things idempotently:

1. Registers the MCP server in ~/.claude.json under mcpServers.vantage-ops pointing at the local dist/.
2. Symlinks the bundled skills under .claude/skills/* into ~/.claude/skills/.

To uninstall: npm run install-claude -- --uninstall. To preview without changes: npm run install-claude -- --dry-run.

Configure

The env block in ~/.claude.json (above) is the canonical place for VANTAGE_MCP_KEY. Legacy local-clone installs may still read ~/repo/.env — both work, but new installs should use the env block.

The key was handed to you once at provisioning — if you lost it, it cannot be recovered. Ask for a replacement.

Verify after restart:

vantage_mcp_health

Expected:

{
  "api_url": "https://mbmhmzrur4.execute-api.us-east-1.amazonaws.com/prod",
  "key_configured": true
}

Tool inventory at a glance

24 read tools + 24 write tools + 2 health = 50 total.

Read tools (need mcp:read scope on key)

| Domain | Tools | |---|---| | Companies | companies_search, company_get, companies_stats | | Contacts | contacts_search, contact_get, contacts_by_company | | Opportunities / Pipeline | pipeline_list, pipeline_get, pipeline_summary | | Campaigns | campaigns_list, campaign_get, campaigns_stats | | Clients / Users | clients_list, client_get, users_list | | Ops | health, mcp_health, table_counts |

Write tools (need a scoped VANTAGE_MCP_KEY)

| Domain | Tools | Scope | |---|---|---| | Companies | company_create, company_update, company_delete | companies:write | | Contacts | contact_create, contact_update, contact_delete | contacts:write | | Opportunities | opportunity_create, opportunity_update, opportunity_update_stage, opportunity_delete | opportunities:write | | Campaigns | campaign_create, campaign_update, campaign_delete, campaign_start, campaign_pause, campaign_add_targets, campaign_add_recipients, campaign_recipient_update, campaign_remove_recipient, campaign_source_contacts | campaigns:write | | Apollo | apollo_search_contacts, apollo_search_companies, apollo_unlock_email, apollo_import_contact | apollo:write | | Templates | template_create, template_update, template_delete | templates:write | | Outreach | outreach_record, outreach_update | outreach:write | | Activities | activity_log | activities:write |

All tool names are prefixed with vantage_ when called (e.g. vantage_company_create). Full schemas in docs/TOOLS.md.

Bundled skills

The MCP server is the tool surface; the bundled skills are slash-command workflows that orchestrate those tools end-to-end. After linking the skills directory (see Install), all four are usable from any Claude Code session as /<skill-name>.

| Skill | Stage in lifecycle | What it does | |---|---|---| | /vet-leads | Pre-import | Deterministic file QA on a raw lead list (xlsx/csv) — flags role mailboxes, name-vs-email typos, missing fields, reseller-vs-end-user mismatches, dedup hits. Annotates each row with a disposition column. Free; no Apollo. | | /lead-enrich | Pre-import | Enriches a lead list with domains (for auto-logo), current company names, industry, dedup. Respects disposition from /vet-leads if present. | | /contact-enrich | Post-import | Fills linkedin_url + title on already-imported Vantage contacts. Apollo unlock_email (paid, optional) + WebSearch fallback. | | /campaign-launch | End-to-end | Builds a Vantage campaign from a lead file or ICP frame — companies + contacts + templates + targets + recipients staged in draft for human sign-off. |

Designed lifecycle:

/vet-leads <file>            → vetted.csv  (operator reviews)
/lead-enrich <vetted.csv>    → enriched-import.csv
import via Vantage UI / API
/contact-enrich --campaign   → fills LinkedIn + title gaps
/campaign-launch <id>        → templates, sequence, ready to launch

Each skill is also registered as an MCP prompt for forward-compat with the Claude Agent SDK and any future Claude Code support for prompt-as-slash invocation. Filesystem skill files are the canonical source — the prompts read from the same .claude/skills/<name>/SKILL.md at server startup.

Quick-check after install

vantage_health
vantage_mcp_health
vantage_companies_search status=prospect limit=3

If all three respond, you're good.

Updating

With the @latest tag in ~/.claude.json, npx fetches the newest published version on each Claude Code restart. To force a refresh without restarting Claude Code, clear the npm cache for this package: npm cache clean --force (or rm -rf ~/.npm/_npx/<hash>).

For pinned installs (@1.1.0 rather than @latest), edit ~/.claude.json to bump the version tag and restart.

For from-source installs, git pull && npm install && npm run build then restart Claude Code.

Troubleshooting

| Symptom | Fix | |---|---| | Tool missing in Claude session | Restart Claude Code. If pinned to a specific version, check the version's CHANGELOG. If on @latest, clear the npx cache to force a re-fetch. | | Vantage UI shows recipient as "Sent" after they replied | The campaign's embedded recipients[contact].engagement_status is a separate field from outreach.status and does not auto-sync. Use vantage_outreach_update AND vantage_campaign_recipient_update together when capturing an inbound reply. | | VANTAGE_MCP_KEY not set on first write | Confirm the env block in ~/.claude.json has the key and Claude Code was restarted. | | 403 insufficient scope. Required: X | Your key doesn't cover this tool — ask admin for an expanded key (see docs/SCOPES.md) | | Read tools fail with 403 Insufficient scope. Required: mcp:read | Your key lacks mcp:read — ask admin to re-mint with reads enabled | | 401 Unauthorized on every write | Key revoked, expired, or mistyped — verify with admin | | 404 Not found on a specific opp/contact | Record doesn't exist in V2 table — check vantage_pipeline_get / vantage_contact_get first |

Testing

Three layers:

npm test       # 72 tests — schema contracts + mocked HTTP (runs offline in <200ms)
npm run smoke  # live end-to-end against prod API — needs a valid VANTAGE_MCP_KEY
npm run build  # TypeScript type check

npm test is safe in any environment — sentinel values are inlined in the test script, global.fetch is stubbed, the network is never touched.

npm run smoke creates a test contact + opportunity in prod against the sharptrain client (34ec0933-…), exercises every write tool, then cleans up. Each step reports pass/fail; exit code is 0 on full pass. Your key needs: contacts:write, opportunities:write, activities:write. Provide your key via shell env or a local .env.test (gitignored).

See tests/client.test.ts for HTTP shape coverage, tests/tools.test.ts for schema contracts, and scripts/smoke.ts for the live happy path.

Key lifecycle

• Default TTL: 90 days
• Recovery: plaintext is not stored, only a SHA256 hash. Lost keys must be revoked + re-issued
• Rotation: request a new key before expiry; run in parallel briefly, then revoke the old one
• Leak response: admin runs vantage_keys.py revoke --id <uuid> immediately

Next steps

• Read docs/TOOLS.md for the full tool schema reference
• Read docs/SCOPES.md to understand which scopes unlock which tools
• Read docs/RECIPES.md for common workflows (launching a campaign, tracking an outreach touch, etc.)

For development conventions and contribution guide see CLAUDE.md.

Questions? Ping the platform admin.