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

# Mcp integration

# EvalGate agent tool access

> EvalGate provides public protocol and read-only schema discovery plus an
> authenticated, permission-filtered **read and write** surface at `/api/mcp`.
> The older `/api/mcp/tools` and `/api/mcp/call` are a separate proprietary HTTP
> Tool API. Anonymous clients cannot execute product tools.

The separate documentation endpoint at `https://www.evalgate.com/api/mcp/docs`
is public and read-only. It serves a reviewed catalog of already-published
EvalGate documentation, has no organization context, and cannot read customer
data or invoke product operations. Use it when an agent needs to learn EvalGate
before a person has approved product access.

Tool names use snake\_case, for example `project_plan` and `docs_search`.
Existing dotted names remain accepted as call-time aliases. Discovery lists
only canonical names; aliases retain the same role, scope and release checks.
For modern calls, use the same tool name in `Mcp-Name` and `params.name`.

All three documentation tools publish typed input schemas. `docs_list` accepts
an optional integer `limit` (1–100) and a `cursor` returned by the previous
page. For example, call `docs_list` with `{"limit":10}`, then repeat with
`{"limit":10,"cursor":"10"}` when `nextCursor` is `"10"`. A `null`
`nextCursor` marks the last page. Omitting both arguments returns the full
catalog for existing clients; `docs_search` and `docs_get` retain their query
and slug arguments.

## Official coding-agent Skills

Browse the [official EvalGate Skills repository](https://github.com/evalgate/skills)
for the portable evaluation decision framework and setup, gate, trace,
repository, and MCP workflows. Preview the collection with
`npx skills add evalgate/skills --list`, then install the complete collection
with `npx skills add evalgate/skills` or a single Skill with
`npx skills add evalgate/skills --skill use-evalgate-mcp`.

Installing Skills copies Skill files only. It does **not** install `.mcp.json`,
configure Claude Desktop connectors, or grant product credentials. Configure
MCP servers separately for each client below.

The collection is experimental. Skills supply instructions; they do not issue
credentials or replace release-policy enforcement. See the
[coding-agent guide](https://www.evalgate.com/docs/guides/write-evals-with-your-agent)
and [agent discovery guide](https://www.evalgate.com/docs/guides/agent-discovery).

## Connect an MCP client

The official product server is listed as
[evalgate/evalgate on Smithery](https://smithery.ai/servers/evalgate/evalgate).
It connects to the first-party product endpoint below. The listing links back
to EvalGate's developer hub; authenticated tool calls still require scoped access.

Use the format documented for the actual client. Do not paste one client's JSON
into another.

### Claude Code (project `.mcp.json`)

Claude Code expands `${EVALGATE_API_KEY}` from the process environment. Never
commit a literal token.

```json theme={null}
{
  "mcpServers": {
    "evalgate-docs": {
      "type": "http",
      "url": "https://www.evalgate.com/api/mcp/docs"
    },
    "evalgate-product": {
      "type": "http",
      "url": "https://www.evalgate.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ${EVALGATE_API_KEY}"
      }
    }
  }
}
```

### Cursor (`.cursor/mcp.json`)

Cursor uses URL entries and `${env:NAME}` syntax:

```json theme={null}
{
  "mcpServers": {
    "evalgate-docs": { "url": "https://www.evalgate.com/api/mcp/docs" },
    "evalgate-product": {
      "url": "https://www.evalgate.com/api/mcp",
      "headers": { "Authorization": "Bearer ${env:EVALGATE_API_KEY}" }
    }
  }
}
```

### Claude Desktop / claude.ai

Add the remote docs URL through the custom connector UI. Remote connectors
differ from local Desktop server configuration; do not paste Claude Code JSON
into `claude_desktop_config.json`. Product access requires a client-supported
authentication flow. Do not assume arbitrary bearer headers or EvalGate OAuth
interoperability were tested in the Desktop connector. If the client cannot
supply the required credential, use an authorized client with header support
instead of claiming it is connected.

Obtain product tokens through OAuth authorization code with PKCE, the
human-approved device flow, or a manually created key as described in
[Agent API-key authentication](https://evalgate.com/docs/api/agent-authentication.md). Public discovery
does not issue a credential, execute a tool, or expose tenant results.

Use a client that supports MCP `2026-07-28`. A conforming client supplies the
protocol metadata and routing headers for each request. Do not paste a
long-lived organization-admin key into an agent configuration.

The endpoint is still experimental. EvalGate has not completed a guided
connection flow or published a tested compatibility matrix for every Cursor,
Claude, Copilot, or other MCP client release.

## Stateless modern protocol

For MCP `2026-07-28`, every operation is a separate POST. `server/discover`,
schema-only `tools/list`, and UI `resources/list`/`resources/read` are public;
`tools/call` and all organization data require a scoped bearer token. There is no `initialize` exchange and no
`Mcp-Session-Id`.

Each request carries its protocol version and client capabilities in
`params._meta`, and clients should also include their identity. Streamable HTTP
also carries `MCP-Protocol-Version` and `Mcp-Method`, plus `Mcp-Name` when
calling a tool, so gateways can route the request without parsing its body.
Header and body values must match.

EvalGate implements `server/discover` to advertise its supported protocol
versions and capabilities. Discovery is useful for negotiation, but a modern
client can send any complete, self-describing request directly.

## Public bootstrap request

The modern method header and JSON-RPC body method must match:

```bash theme={null}
curl -X POST https://www.evalgate.com/api/mcp \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: server/discover' \
  --data '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"evalgate-probe","version":"1.0.0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'
```

The response advertises the tools capability. Anonymous `tools/list` returns
only the **released read-only schemas**, descriptions, annotations, and MCP App
resource links. An authenticated caller receives only tools allowed by its
role, scopes, and the release catalog—including supported writes. Anonymous
discovery returns no organization identity or customer data and cannot execute
a product tool.
Anonymous `tools/call` receives a bearer challenge pointing to RFC 9728 metadata.

Modern `server/discover` and `tools/list` responses use `ttlMs: 0` and
`cacheScope: "private"`. Treat an authenticated list as immediately stale and
keep it within the same authorization context; a different token can expose a
different tool set. The protocol cache hints do not replace HTTP cache controls.

## Version negotiation and legacy clients

A dual-era client should probe `server/discover`, select `2026-07-28` when it is
advertised, and fall back to the 2025 `initialize` flow only when the endpoint
is legacy. Official TypeScript SDK v2 clients must select automatic version
negotiation to get this probe-and-fallback behavior; the SDK's default remains
legacy-only.

EvalGate accepts legacy `initialize` on POST for compatibility, but the
fallback is stateless. It does not mint an `Mcp-Session-Id` or keep a
cross-request transport session. Legacy results omit modern `ttlMs` and
`cacheScope` fields. Legacy POST replies use the 2025 Streamable HTTP event-stream framing. `GET` and `DELETE /api/mcp` return `405 Method Not Allowed`,
so neither a standalone SSE stream nor session termination is available.

## Released product tools: read evidence or author with permission

The released tool inventory comes from the same
[capability contract](https://www.evalgate.com/.well-known/mcp/server-card.json)
used by the running MCP server. Anonymous `tools/list` shows only read-only
schemas; after authentication, `tools/list` is **filtered by the caller's
tenant, role and exact scopes**. A displayed schema never grants access.

For read-only work, tools include `project_inspect`, `project_plan`,
`evaluations_list`, `runs_list`, `run_explain`,
`baseline_lineage`, `docs_search`, `connector_health` and
authorized connection-read tools. `connector_health` requires an elevated
admin scope. `project_plan` is advisory and never mutates a repository.

### Evaluation-authoring writes

| MCP tool | Minimum role | Required scope | Effect and verification |
| - | - | - | - |
| `evaluations_create` | member | `eval:write` | Creates an evaluation; read back its ID |
| `test_cases_add` | member | `eval:write` | Adds a reviewed case; locked evaluations refuse |
| `runs_start` | member | `runs:write` | Starts a run after readiness/spend guards; poll `runs_list`/`run_explain` |
| `traces_create` | member | `traces:write` | Records a trace; redact content and check retention |

Each write replays the validated calling credential into EvalGate's own REST
route. Authentication, rate limiting, quotas, locks, and business guards are
preserved. Request the **least-privilege scope**, confirm explicit approval for
writes or metered execution, then verify the persisted result. A successful
`runs_start` response means the run was requested, not that a regression
gate passed. A Skill install, server card or Smithery listing does not grant
a credential or permission.

### Admin-only connector writes

`connections_create_root`, `connections_repair_root`,
`connections_set_root_state`, `connections_backfill`, and
`connections_select_resources` require **admin role** and
`admin:workspace`, with some operations also requiring
`resources:read` and `resources:write`. These elevated operations are
not part of the least-privilege OAuth agent handoff; use explicitly approved
admin API keys or authenticated browser sessions where supported.

Portable Quality MCP operations such as `quality_check_submit`,
`quality_context_create`, resource upload, standards acceptance and
background grants remain **unreleased**. This MCP also cannot approve a
baseline, promote a candidate, authorize purchases, merge a pull request,
or make a separate release decision.

### Smithery and other agent clients

The existing [Smithery listing](https://smithery.ai/servers/evalgate/evalgate)
was initially indexed with read-only copy. The server card and OAuth protected
resource now describe the available evaluation write scopes, but a third-party
directory scan may still use **anonymous discovery** and see only read schemas.
Re-publish the same Smithery slug with updated authenticated-write copy; do
not expose writes anonymously or furnish a production admin token to a scanner.
A real authenticated creation/readback from the target client is required
before claiming one-click writes.

### Repository improvement campaigns

Agents can drive most of a repository improvement campaign through the CLI
and REST API, but some steps are reserved for a person:

| Step | Agent (CLI, API key, MCP token) | Person signed in to EvalGate |
| - | - | - |
| Compile an Optimization Contract (`auto contract`, `POST /api/improvement/cycles/{cycleId}/contracts`) | Yes | Yes |
| Approve a hosted contract (`…/contracts/{contractId}/approve`) | Refused | Yes |
| Run the local loop, freeze, report, export, open a **draft** PR (`auto propose --open-pr`) | Yes | Yes |
| Import a campaign and start its independent confirmation | Yes, with `eval:write` | Yes |
| Start release review on a confirmed campaign | Refused | Yes |
| Adopt a candidate under a contract | Refused | Yes |
| Merge the pull request | Never automated by EvalGate | Yes, in the code host |

The MCP endpoint exposes **none of these campaign approval/promotion operations**.
Its separate evaluation-authoring tools above can create evaluations, cases,
runs and traces, but cannot authorize a campaign release. An MCP client can
read the resulting evidence and hand a person the link to approve,
start release review, or merge. "Signed in" means a browser session: API keys
and MCP-issued tokens are not treated as a person, whatever role they carry.

## Use MCP evidence in an evaluation decision

MCP tools return read-only project, run, baseline, connector, and documentation
evidence. They do not define a second release vocabulary or authorize a release
action. When an agent uses MCP evidence to assess an AI change, it should follow
the public `evaluate-ai-change` Skill and serialize the result with the
[canonical decision schema](https://www.evalgate.com/schemas/evaluate-ai-change-decision.schema.json).

The canonical `classification` determines both `invokeEvalGate` and
`releaseDecision`. Unknown synonyms and contradictory pairs such as
`regression` with `promote` are invalid. The MCP server does not accept this
decision object as a mutation; use the reviewed CLI or web workflow for an
approved action.

The same schema requires an `evidenceSummary` for quality, protected slices,
reliability, latency, and cost. Report MCP measurements under the matching
dimension. If MCP did not return valid evidence for a dimension, use
`not_measured` with a reason instead of estimating a value.

`run_explain` links to the self-contained `ui://evalgate/run-evidence.html`
MCP App. The HTML template is public; its structured run result is available
only after the host completes an authenticated, scope-checked tool call. The
public docs server also exposes every reviewed page through native
`resources/list` and `resources/read`, plus a responsive docs App. Neither App
loads external scripts, fonts, analytics, or customer data on its own.

## Legacy HTTP Tool API

`GET /api/mcp/tools` and `POST /api/mcp/call` are an authenticated proprietary
HTTP API for direct integrations. Do not add either route to an MCP client
configuration.

The legacy API exposes `eval.quality.latest`, `eval.get`, and `eval.list` by
default. These routes are not a standards-conformant MCP transport. Their
optional write operations require both operator opt-in with
`EVALGATE_TOOL_API_WRITES=true` and the caller's required write scopes. That write path is
separate from the read-only `/api/mcp` endpoint. The legacy tier is limited to
100,000 requests per day.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.