> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Matcher MCP server

> Connect AI assistants to Matcher through the Model Context Protocol — a secure, token-relayed tool surface over the reconciliation engine.

The **Matcher MCP server** exposes Matcher's reconciliation surface as [Model Context Protocol](https://modelcontextprotocol.io) tools, so an AI assistant — or any MCP client — can operate Matcher on your behalf: inspect contexts, start reconciliation runs, work exceptions, and pull reports, all with the same permissions you already have.

<Warning>
  Matcher is only available if you've acquired the Matcher product. Want access? [Get in touch with our team](https://lerian.studio/contact) to learn more.
</Warning>

## How it connects

***

The server speaks **Streamable HTTP**. It runs as its own service alongside the Matcher API and exposes a single MCP endpoint (`POST /mcp`) plus a plain liveness probe (`GET /healthz`). There is no stdio transport: every client connects to it as a *remote* server over the network.

Point any Streamable-HTTP MCP client at the endpoint your platform team provides and send your Matcher bearer token on the connection. For example, with Claude Code:

```bash theme={null}
claude mcp add --transport http matcher https://your-matcher-mcp.example.com/mcp \
  --header "Authorization: Bearer <matcher-jwt>"
```

For local development, the relay is also published as a public npm package — start it pointed at your Matcher API and connect to `http://localhost:4019/mcp`:

```bash theme={null}
MATCHER_API_URL=https://your-matcher-api npx @lerianstudio/matcher-mcp
```

Any MCP client that supports Streamable HTTP works the same way: give it the URL and the `Authorization: Bearer <matcher-jwt>` header.

## Auth posture

***

The server is a **stateless credential relay** — it adds no identity of its own:

* **Bearer token for API calls.** Tools that dispatch Matcher API requests fail closed without a bearer token and forward the client-supplied credential without logging, storing, or echoing it.
* **Local utilities.** `mcp_ping`, `matcher_list_operations`, and `matcher_describe_operation` run locally and need no token. `mcp_whoami` does not call Matcher, but it requires a bearer credential to report that one was relayed; without it, it returns a tool error.
* **Tenant follows the token for API calls.** No API-dispatching tool accepts a tenant parameter; Matcher resolves the tenant from the relayed JWT.
* **No session state.** Each request builds a fresh in-memory server, so the relay can be scaled and restarted freely.

To verify your client is wired correctly, call `mcp_whoami` with a bearer credential after connecting — it reports only that the credential arrived, never its value.

## What you can do with it

***

The server exposes curated tool families covering configuration, reconciliation runs, exceptions and disputes, ingestion, and reporting, plus a generic bridge for operations with JSON request bodies. See [Matcher MCP tools](/en/matcher/mcp/matcher-mcp-tools) for the catalog.