Eparch MCP Server

eparch-mcp is a Model Context Protocol server that exposes your Eparch instance’s agent-management API as tools. Point any MCP client — Claude Desktop, Cursor, or your own — at it, and you can create, inspect, and run governed agents from an ordinary LLM conversation.

It authenticates to Eparch with a tenant API key, so every action is subject to the same OPA authorization, Postgres RLS, and tenant isolation as a normal user — the MCP server holds no special privilege.

This is the provider side. It is unrelated to Eparch consuming external MCP servers as agent tools (that’s the tool registry, see the UI → Tools → MCP Servers).

Tools exposed

Tool	Does
`list_agents` / `get_agent`	List agents / get one by id
`create_agent`	Create an agent (name, model, system prompt)
`run_agent` / `get_execution`	Run an agent; poll its execution
`list_tools`	List tools available to your agents
`list_topics` / `create_topic` / `delete_topic`	Manage event-bus topics
`list_collections` / `create_collection` / `delete_collection`	Manage RAG collections
`list_documents` / `ingest_document`	List / upload RAG documents (pass text directly)
`query_rag`	Semantic search over a collection

1. Get an API key

Mint a key via the API (requires a tenant-admin login). The key carries a platform role that governs what it can do — pick tenant:admin for a key that manages agents, topics, and RAG (the default agent:developer can create/run agents but not topics or RAG collections):

curl -s -X POST http://localhost:8080/api/v1/api-keys \
  -H "Authorization: Bearer <your-login-token>" \
  -H 'Content-Type: application/json' \
  -d '{"name":"mcp","role":"tenant:admin"}'

Copy the eparch_sk_… value from the response — it is shown once. Keys are revocable (Settings → API keys, or DELETE /v1/api-keys/{id}).

2. Build the server

go build -o eparch-mcp ./cmd/eparch-mcp     # from the repo
# or install it:
go install github.com/eparchai/eparch/cmd/eparch-mcp@latest

It is a single static binary with no dependencies. Configure it with two env vars:

Env	Default	Meaning
`EPARCH_API_URL`	`http://localhost:8031`	Your Eparch gateway URL
`EPARCH_API_KEY`	(required)	The `eparch_sk_…` key from step 1

3. Connect a client

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "eparch": {
      "command": "/absolute/path/to/eparch-mcp",
      "env": {
        "EPARCH_API_URL": "http://localhost:8031",
        "EPARCH_API_KEY": "eparch_sk_…"
      }
    }
  }
}

Restart Claude Desktop. You can now say things like “list my Eparch agents” or “create an Eparch agent named triage that uses llama and triages support tickets.”

Cursor

In ~/.cursor/mcp.json (or the workspace .cursor/mcp.json):

{
  "mcpServers": {
    "eparch": {
      "command": "/absolute/path/to/eparch-mcp",
      "env": { "EPARCH_API_URL": "http://localhost:8031", "EPARCH_API_KEY": "eparch_sk_…" }
    }
  }
}

How auth works (for the curious)

The MCP server sends the API key to the gateway. The gateway resolves the key to your tenant + role, then exchanges it — via identity’s internal, service-token-gated mint endpoint — for a short-lived, tenant-scoped platform JWT that it forwards to the data-plane services. So the data-plane still validates a real signed JWT, the signing key never leaves identity, and OPA + RLS apply to every call. A revoked key stops working immediately.

Quick test without a client

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_agents","arguments":{}}}' \
  | EPARCH_API_URL=http://localhost:8031 EPARCH_API_KEY="eparch_sk_…" ./eparch-mcp