@lerianstudio/matcher-mcp weekly downloads statistics

matcher-mcp

A Model Context Protocol server that lets an operator drive the Matcher reconciliation engine through MCP tools.

What this is

A stateless credential relay. On every inbound MCP connection it reads the operator's Authorization: Bearer <matcher-jwt> header and forwards it verbatim to the Matcher API, exposing the reconciliation surface as MCP tools. It holds no credentials and performs no token validation — Matcher and plugin-auth own that (Matcher itself does no local signature/exp/nbf checks either; it delegates to plugin-auth). The server keeps no per-connection session state: a fresh in-memory server is built per request, so it can be scaled or restarted freely.

Tenant identity derives entirely from the token. The MCP server never accepts, injects, or infers a tenant_id / tenantId / tenant parameter on any tool, and Matcher resolves the tenant from the relayed JWT.

Auth model

The operator's MCP client supplies the matcher bearer token as an Authorization: Bearer <matcher-jwt> header on the connection. The server:

• forwards that header verbatim to the Matcher API on every tool call;
• never logs, stores, or persists the token;
• never places it in errors, tool output, spans, span attributes, span events, or metrics.

The relay is fail-closed: a tool call with no relayed bearer credential is rejected with operator-remediation text and makes no call to Matcher — it never falls back to an unauthenticated or default-tenant request. Use the mcp_whoami tool to confirm your client is sending the header; it reports presence only and never echoes the token value.

Deployment

The server ships as the segregated matcher-mcp Docker image — a distroless Node service built by the mcp group in .github/workflows/release.yml and published to GHCR. The image rides the same v<version> semantic-release tag as the matcher app, which also pins the embedded OpenAPI spec to the matched matcher version. The bearer token the relay forwards is never baked into the image.

It speaks Streamable HTTP and binds MCP_PORT (default 4019). The server also hosts the optional console copilot and voice routes:

Method	Path	Purpose
GET	/healthz	Plain liveness probe.
POST	/mcp	The Streamable HTTP MCP endpoint clients connect to.
POST	/agent/turns	Stream an authenticated copilot turn when a provider is configured.
GET	/agent/transcribe	Report voice-transcription availability for the authenticated caller.
POST	/agent/transcribe	Transcribe an authenticated voice recording when configured.

Point any Streamable-HTTP MCP client at POST /mcp and send the matcher bearer token as the Authorization header.

Installing in an MCP client

The server speaks Streamable HTTP, so you connect a client to its POST /mcp endpoint over the network and send your matcher JWT as Authorization: Bearer <token>. There is no stdio transport — the usual command: npx … MCP wiring does not apply here; every client below is configured as a remote / HTTP server.

1. Get an endpoint

Three options for <mcp-url>:

• Connect to a deployed server (recommended for clients). Point your client at a running matcher-mcp (the GHCR image), e.g. https://matcher-mcp.example.com/mcp. Clients connect remotely and install nothing locally.

• Local matcher dev (repo clone). make up brings the relay up as a compose service on :4019 alongside the rest of the stack (restart: unless-stopped, so it stays up — no separate process to babysit). Use http://localhost:4019/mcp. If Matcher runs on the host, stop both Compose app and mcp first and start the host relay with MATCHER_API_URL=http://localhost:4018; the Compose relay targets the Docker-only name app:4018. See ../docs/development.md.

• Run it standalone with npx. @lerianstudio/matcher-mcp is a public package (Apache-2.0) — no registry auth needed. Start the relay (binds :4019) pointed at your Matcher API:

  MATCHER_API_URL=https://your-matcher-api npx @lerianstudio/matcher-mcp
  

  then use http://localhost:4019/mcp as <mcp-url>.

2. The token

Every client sends the matcher JWT as Authorization: Bearer <matcher-jwt> on the MCP connection. The relay forwards it verbatim to the Matcher API; tenant and identity derive entirely from it. Get it from your Access Manager / plugin-auth — the same token you'd use against the Matcher API directly. The relay holds no credentials of its own.

Replace <matcher-jwt> and <mcp-url> below accordingly.

3. Wire it into your client

Claude Code — CLI:

claude mcp add --transport http matcher <mcp-url> \
  --header "Authorization: Bearer <matcher-jwt>"

or .mcp.json (${MATCHER_JWT} is read from the environment at connect time):

{
  "mcpServers": {
    "matcher": {
      "type": "http",
      "url": "<mcp-url>",
      "headers": { "Authorization": "Bearer ${MATCHER_JWT}" }
    }
  }
}

opencode — opencode.json ({env:VAR} reads from the environment):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "matcher": {
      "type": "remote",
      "url": "<mcp-url>",
      "enabled": true,
      "headers": { "Authorization": "Bearer {env:MATCHER_JWT}" }
    }
  }
}

droid (Factory) — CLI:

droid mcp add matcher <mcp-url> --type http \
  --header "Authorization: Bearer <matcher-jwt>"

or ~/.factory/mcp.json (user-level) / .factory/mcp.json (project-level):…