AIPI Bridge MCP

SSE-transport MCP server exposing a curated slice of Bot Army to external MCP clients that only speak SSE — specifically AIPI's "Custom MCPs" skill config, which documents SSE as the only currently supported format.

Deliberately narrow, not a generic bridge.* passthrough: this is meant to be reachable from a third-party vendor's cloud (via ngrok), not a trusted local dev session, so it exposes exactly three tools instead of letting a caller invoke arbitrary bridge subjects. For local/trusted MCP clients that want the full surface (any bridge.* subject, NATS observe, registry queries), use tools/nats-gateway-mcp instead — stdio transport, generic bridge_request tool.

Tools

Deliberately not exposed: bridge.task.update (a misheard voice command could silently mutate an existing task's fields with no confirmation screen — if wanted later, scope it to status→completed only, i.e. reuse gtd_task_complete's shape rather than open-ended field updates) and bridge.project.* (bridge.project.list is a known-broken responder as of 2026-08-15 — returns empty despite tasks carrying project_ids).

Related MCP server: Hermes MCP Bridge

Setup

1. Build (from repo root or this directory):

   cd tools/aipi-bridge-mcp && npm install && npm run build

2. Run

   NATS_URL=nats://localhost:4222 \
   AIPI_BRIDGE_MCP_PORT=39895 \
   AIPI_BRIDGE_MCP_TOKEN=<pick-a-token> \
   npm start

   • AIPI_BRIDGE_MCP_TOKEN is required before tunneling this externally — without it the SSE endpoint is unauthenticated. Server logs a warning on startup if it's unset.

   • SSE endpoint: GET /sse (requires Authorization: Bearer <token>), message endpoint: POST /messages?sessionId=..., health check: GET /health (no auth).

3. Expose it

   Same pattern as everything else externally-reachable in this repo: tunnel via air.ngrok (reserve a port label, e.g. surface-aipi-mcp), point AIPI's Custom MCP config at the resulting HTTPS URL + /sse, with the bearer token in whatever auth field their SSE MCP config exposes.

Requirements

• Node.js 18+

• NATS server reachable at NATS_URL — use prod (nats://localhost:4222) for real bridge responses; bridge.chat / bridge.task.* only have responders on the production cluster, not dev (4223).

Development

• npm run build — compile TypeScript to dist/

• npm run dev — run with tsx (no build) for quick iteration

• Verified end-to-end against dev NATS (4223) with a throwaway MCP client: SSE handshake, tools/list, and tools/call all round-trip correctly; tool calls correctly report failure (NATS 503 no responders) rather than fabricating a success, since nothing listens on bridge.chat / bridge.task.list on the dev cluster. Full happy-path verification needs a run against prod NATS.