> ## 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. An AI assistant, or any MCP client, can then operate Matcher on your behalf. It can inspect contexts, start reconciliation runs, work exceptions, and pull reports. It has 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 also ships 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** that adds no identity of its own:

* **Bearer token for API calls.** Tools that dispatch Matcher API requests fail closed without a bearer token. They 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. It still needs a bearer credential, because it reports that a credential arrived. Without a credential, 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 you can scale and restart the relay freely.

To check your client configuration, call `mcp_whoami` with a bearer credential after you connect. It reports only that the credential arrived, never its value.

## What you can do with it

***

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