mcp-gw: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

mcp-gw is an aggregating MCP (Model Context Protocol) gateway. It runs as a single HTTP endpoint that Claude Code (or any MCP client) connects to, and it fans out tool calls to multiple registered backend MCP servers plus a built-in RAG (retrieval-augmented generation) knowledge-base subsystem. Backend tools are namespaced as backend__tool_name to avoid collisions; RAG tools are namespaced rag__<kb_id> (per-KB search) and rag_admin__* (KB/doc management).

Commands

npm install
npm run dev      # tsx hot-reload against src/ (reads config from ./config/backends.json)
npm run build    # compile TypeScript -> dist/
npm start        # run compiled dist/index.js

There is no test suite and no lint script configured in package.json.

Docker (production and dev-in-container):

docker compose up -d                            # production image, port 3000
docker compose --profile dev up mcp-gateway-dev  # dev image: tsx watch, src/public bind-mounted, no rebuild needed on edits

config/backends.json is gitignored (holds backend auth headers/tokens) and must be created manually on a fresh clone (see README "First-time setup"). It is bind-mounted into the container and written to at runtime whenever backends are added/removed via the dashboard or REST API — treat it as generated state, not source.

Architecture

Everything is wired together in src/index.ts: a BackendRegistry (backend MCP client connections) and a RagManager (local knowledge bases) are both handed to a single ToolAggregator, which is the only thing that knows how to route a prefixed tool name to either a backend client or the RAG subsystem. The Express app (dashboard.ts) and the MCP HTTP routes (mcp-server.ts) both sit on top of the aggregator/registry/rag instances — there's no other communication path between them.

• backend-registry.ts — owns MCP client connections to registered backends (Streamable HTTP or SSE transport). Maintains a 30s heartbeat per backend (_ping) that refreshes tools/status/latencyMs; a backend only appears in getAllConnected() once status === 'connected'. Reconnecting a backend fully tears down and recreates its client.
• tool-aggregator.ts — the routing layer. listAllTools() merges namespaced backend tools with RAG tools for the MCP tools/list response. callTool(prefixedName, args) checks rag.isRagTool() first, otherwise splits on the first __ to get backendName/toolName and calls through registry.getClient(backendName). All backend tool calls are logged (start + duration + ok/error) via logger.
• mcp-server.ts — implements the MCP Streamable HTTP transport by hand (session map keyed by mcp-session-id header, one Server+transport pair created per initialize call). If you need to change session lifecycle behavior, this is the only place it's handled.
• config.ts — flat load/save of config/backends.json (path overridable via CONFIG_PATH). No validation beyond JSON shape; the dashboard/API are the enforcement point for well-formed BackendConfig.
• logger.ts — in-memory circular buffer + SSE emitter, backs both the dashboard's live log view and /api/logs/stream.
• dashboard.ts — Express app exposing the REST API (/api/health, /api/backends, /api/logs*, RAG doc/KB endpoints) and serving public/index.html (a no-build-step SPA).