Capability Matchmaker

MCP Capability Matchmaker is an MCP gateway and an offline catalog CLI. The gateway reads a trusted catalog, starts or connects to the configured upstream MCP servers, discovers their live tools, and exposes those tools through one stdio MCP endpoint. The CLI remains useful for importing, inspecting, and ranking catalog metadata without connecting to any upstream.

Gateway quick start

Install and build once:

npm install
npm run build

Configure an MCP client with the gateway entry point:

{
  "mcpServers": {
    "capability-gateway": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-capability-matchmaker/dist/mcp-server.js",
        "--catalog",
        "/absolute/path/to/catalog.json"
      ]
    }
  }
}

The package also installs the equivalent executable alias mcp-capability-gateway (the historical mcp-capability-matchmaker alias is retained). For local development:

npm run dev:mcp -- --catalog examples/catalog.json

The gateway connects all configured upstreams in parallel. A healthy upstream is still available when another one fails. Discovered tools are published as server__tool; names are normalized and made unique when necessary. Calls to those tools are forwarded to the original upstream tool with its JSON Schema, annotations, output schema, and result content preserved.

When a connected upstream closes, the gateway removes its stale routes immediately and reconnects with exponential backoff (1 second initially, capped at 30 seconds). A successful reconnect republishes the live tools and notifies downstream clients. Reconnect attempts and the next delay are visible through gateway__inspect_catalog.

The gateway also exposes two built-in read-only tools:

MCP tool	Purpose
gateway__recommend_tools	Recommend a small, explainable set from currently connected tools
gateway__inspect_catalog	Report configured upstreams, connection state, live tool counts, and metadata gaps

The gateway uses stdio for its downstream interface. Upstreams may use either stdio or Streamable HTTP. HTTP authentication belongs in headers. Every env or headers value must be a complete ${ENV_VAR} placeholder resolved from the gateway process environment. Missing variables disable only the affected upstream and are never returned in status or error messages.

Catalog format

Catalog files use version: 1. tools is optional in the gateway workflow and defaults to an empty array: live tools/list results are authoritative. Static tools are still useful to the offline CLI for ranking and metadata review.

{
  "version": 1,
  "servers": [
    {
      "name": "linear",
      "description": "Read and update Linear issues.",
      "transport": {
        "command": "npx",
        "args": ["-y", "@example/linear-mcp"],
        "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" }
      },
      "tools": []
    },
    {
      "name": "slack",
      "transport": {
        "url": "https://mcp.example.com/slack",
        "headers": { "Authorization": "${SLACK_AUTHORIZATION}" }
      },
      "tools": []
    }
  ]
}

Each transport is either stdio (command, optional args and env) or Streamable HTTP (url, optional headers). Treat a catalog as executable configuration: starting the gateway can execute local commands and make network requests.

Offline CLI

The mcp-match CLI never starts, connects to, or executes an MCP server. It normalizes registry exports, checks metadata quality, and produces an explainable tool recommendation.

node dist/cli.js index examples/registry-export.json --output catalog.json
node dist/cli.js inspect --catalog catalog.json
node dist/cli.js recommend \
  "Read Linear issue ENG-42, modify the GitHub repository, then notify Slack" \
  --catalog catalog.json

Commands:

Command	Purpose
mcp-match index <input>	Normalize JSON/YAML catalog data from a file or URL
mcp-match inspect -c <catalog>	Report catalog size and metadata quality
mcp-match recommend <task> -c <catalog>	Select and explain a minimal tool set

Output formats are markdown, json, claude, cursor, and codex.

Runtime boundaries

• Only Tools are proxied in this release; Resources, Prompts, Sampling, Elicitation, and task-based execution are not gateway features.
• Gateway-level reconnect handles closed upstream connections. Initial startup failures remain isolated and require a gateway restart after configuration or credential fixes.
• The gateway downstream transport is stdio only; HTTP gateway serving, production authentication, auditing, and rate limiting are out of scope.
• A failed upstream is isolated and reported by the inspection tool. A failed refresh keeps its last known tool snapshot until the connection closes.

Development

npm install
npm run check

MIT licensed. See CONTRIBUTING.md and SECURITY.md.