vantage-plan-mcp

MCP server that connects external agents (Claude Desktop, Codex, Claude Code, custom clients) to the running Vantage Plan app on the same Mac. It talks to the app's loopback bridge (127.0.0.1, bearer token) — it never touches the database file directly, so CloudKit sync stays safe.

v1.0: write-capable. Reads and view navigation are open by default; data writes route through Vantage Plan's in-app owner-approval queue — nothing changes in your workspace unless you approve it in the app.

How it works

Instead of registering ~380 native MCP tools (which would preload ~80k tokens of schemas per message), this server exposes a discovery surface:

| Tool | Purpose | |---|---| | vantage_status | Is the app running, token accepted, workspace loaded? Tool counts + permission preset. | | search_tools | Search the compact catalog (name + one-liner + category) | | describe_tools | Fetch full JSON Schemas for up to 20 named tools | | call_tool | Execute one tool against the live app (writes may queue for owner approval) |

There is also an MCP resource vantage://tools/catalog with the full compact catalog.

Hot set (v1.1.0, opt-in)

Vantage Plan can additionally serve your ~20 most-used tools as real native MCP tools (full schemas preloaded, marked [HOT-SET SHORTCUT]), so common actions skip the search → describe → call round-trip. It is off by default — turn it on in Vantage Plan → MCP Settings → Tool Exposure → "Meta + hot set".

• Self-learning: the set is ranked by your real usage and re-checked at session start, after every 10th tool call, and every ~5 minutes. Tools are promoted in and demoted out automatically (notifications/tools/list_changed fires only when the set actually changes). Flipping the toggle in the app propagates live — no restart, no config edit.
• Additive, never a replacement: the 4 meta-tools stay, and the full catalog (~377 tools) remains reachable through search_tools/call_tool in both modes.
• Approval still applies: a hot write tool queues for owner approval in Vantage Plan exactly like call_tool — the hot set changes how tools are surfaced, never what they're allowed to do.
• Older app versions (bridge < 0.4.0) simply have no hot set; the adapter degrades to the standard 4-meta behaviour.

Permission model

The app — not this adapter — decides what an external agent may do, per category (reads, navigation, writes, destructive, money, AI-metered):

• Allow — executes immediately (default for reads + navigation).
• Confirm — the call is queued; Vantage Plan shows it in Pending Approvals (tool, arguments, a "Data writes" badge). call_tool waits while polling for the decision (~5-minute approval TTL, poll ≤5.5 min). Approve → the call executes and the real result returns; Deny/expiry → a refusal returns.
• Deny — the category is hidden from the agent entirely.

The agent can never approve its own calls: approval endpoints are read-only over HTTP; Approve/Deny exist only in the app's UI. Presets are managed in Vantage Plan → Settings → MCP Bridge (or the menu-bar MCP Bridge menu).

The app must stay running — this adapter is a thin translator; if Vantage Plan quits or the bridge restarts (token rotate, port change), the stdio server exits and the client must reconnect.

Prerequisites

1. Vantage Plan running on this Mac.
2. Menu bar → MCP Bridge → Enable MCP Bridge.
3. Copy Bridge Token (and note the URL — default http://127.0.0.1:8788; if 8788 was taken the app picks the next free port and the menu shows the real one).

Choose how to connect

There are two ways to run this adapter — pick whichever suits you. Both connect to the same app the same way; they differ only in how the adapter program is launched.

| | Option A — npx (published package) | Option B — from source (local) | |---|---|---| | Setup | none — npx fetches it | git clone + npm install + npm run build | | Updates | automatic (npx pulls the latest) | manual (git pull + rebuild) | | Network | needs internet on first launch, then cached | fully offline | | Best for | most users, quick setup, multiple machines | offline use, or hacking on the adapter itself |

Option B setup (only if you pick it)

git clone https://github.com/odames/vantage-plan-mcp.git
cd vantage-plan-mcp
npm install
npm run build
# note the absolute path printed by: pwd  → you'll point configs at <that>/dist/index.js

Client config

Each client below shows both options. Use the Option A block for npx, or the Option B block for a local build — not both. Fill in VANTAGE_BRIDGE_TOKEN from the app's Copy Bridge Token.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

Option A — npx:

{
  "mcpServers": {
    "vantage-plan": {
      "command": "npx",
      "args": ["-y", "vantage-plan-mcp"],
      "env": {
        "VANTAGE_BRIDGE_URL": "http://127.0.0.1:8788",
        "VANTAGE_BRIDGE_TOKEN": "<paste from Copy Bridge Token>"
      }
    }
  }
}

Option B — local build:

{
  "mcpServers": {
    "vantage-plan": {
      "command": "node",
      "args": ["/absolute/path/to/vantage-plan-mcp/dist/index.js"],
      "env": {
        "VANTAGE_BRIDGE_URL": "http://127.0.0.1:8788",
        "VANTAGE_BRIDGE_TOKEN": "<paste from Copy Bridge Token>"
      }
    }
  }
}

If npx isn't found, use its absolute path (macOS Homebrew: /opt/homebrew/bin/npx); same for node.

Codex

~/.codex/config.toml

Option A — npx:

[mcp_servers.vantage-plan]
command = "npx"
args = ["-y", "vantage-plan-mcp"]

[mcp_servers.vantage-plan.env]
VANTAGE_BRIDGE_URL = "http://127.0.0.1:8788"
VANTAGE_BRIDGE_TOKEN = "<paste from Copy Bridge Token>"

Option B — local build:

[mcp_servers.vantage-plan]
command = "node"
args = ["/absolute/path/to/vantage-plan-mcp/dist/index.js"]

[mcp_servers.vantage-plan.env]
VANTAGE_BRIDGE_URL = "http://127.0.0.1:8788"
VANTAGE_BRIDGE_TOKEN = "<paste from Copy Bridge Token>"

Claude Code

Option A — npx:

claude mcp add vantage-plan \
  -e VANTAGE_BRIDGE_URL=http://127.0.0.1:8788 \
  -e VANTAGE_BRIDGE_TOKEN=<token> \
  -- npx -y vantage-plan-mcp

Option B — local build:

claude mcp add vantage-plan \
  -e VANTAGE_BRIDGE_URL=http://127.0.0.1:8788 \
  -e VANTAGE_BRIDGE_TOKEN=<token> \
  -- node "/absolute/path/to/vantage-plan-mcp/dist/index.js"

Tip: Vantage Plan's MCP Bridge menu has one-click Install for Claude Desktop… / Codex… actions that write these configs for you.

Smoke test

With Vantage Plan running and the bridge enabled:

VANTAGE_BRIDGE_TOKEN=<token> npx @modelcontextprotocol/inspector node dist/index.js

Then in the inspector: vantage_status → search_tools {"query": "project"} → call_tool {"name": "list_projects"} — live project data should return. To see the approval queue, call a write (e.g. create_task) with its category on Confirm and approve it in the app's Pending Approvals window.

Security notes

• Loopback-only — the bridge binds 127.0.0.1; nothing is reachable off the machine.
• Bearer token — stored in the macOS Keychain by the app; rotate it any time from the MCP Bridge menu (clients must then be given the new token).
• search_web is permanently blocked at the bridge (SSRF surface) regardless of permission preset.
• Writes are inert without in-app owner approval; the agent-supplied confirmed flag is ignored — only the owner's Approve stamps it.

Troubleshooting

• "Vantage Plan is not reachable" — the app isn't running or the bridge is disabled/on a different port. Check the MCP Bridge menu.
• 401 / token rejected — re-copy the token from the MCP Bridge menu.
• denied_by_policy — that category is set to Deny in the app's permission preset.
• Client shows the server as disconnected after a bridge restart — expected; reconnect the client (e.g. quit + reopen Claude Desktop).

License

MIT