> ## 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

# EvalGate MCP and HTTP Tool APIs

## MCP endpoint

`POST /api/mcp` provides public read-only schema discovery and an
authenticated, role/scope-filtered **read and write** MCP surface. It supports
the final stateless MCP `2026-07-28` protocol and a stateless 2025-era
compatibility path. The endpoint is experimental while guided connection setup
and the tested client compatibility matrix remain incomplete.

Configure a client with `https://evalgate.com/api/mcp` and a short-lived bearer
token. Request only scopes needed by the operation: `eval:read` for project
review, `eval:write` for evaluation/test-case creation, `runs:write` for
starting runs, and `traces:write` for creating traces. Read and write tool
visibility also depends on the caller's organization role.

Discovery lists snake\_case tool names, such as `project_plan` and `docs_search`.
Existing dotted names remain accepted as call-time aliases with the same
permissions and release checks. Modern clients must send matching tool names
in `Mcp-Name` and `params.name`.

### Modern request contract

MCP `2026-07-28` does not use `initialize`, `notifications/initialized`, or
`Mcp-Session-Id`. Send each JSON-RPC request as its own POST. Protocol
bootstrap and released read-only schema discovery allow anonymous calls;
`tools/call` and tenant data require authentication.
Each POST includes:

* `Content-Type: application/json`
* `Accept: application/json, text/event-stream`
* `MCP-Protocol-Version: 2026-07-28`
* `Mcp-Method: <JSON-RPC method>`
* `Mcp-Name: <tool name>` for `tools/call`
* `params._meta` with required `io.modelcontextprotocol/protocolVersion` and
  `io.modelcontextprotocol/clientCapabilities`; clients should also send
  `io.modelcontextprotocol/clientInfo`

The protocol-version header must match the value in `_meta`, and routing-header
values must match the JSON-RPC body.

Use `server/discover` to inspect supported versions and capabilities:

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

`server/discover` is available for negotiation, but modern clients may send a
fully self-describing request directly. EvalGate returns conservative cache
hints on modern discovery and tool-list results:

```json theme={null} theme={null}
{
  "ttlMs": 0,
  "cacheScope": "private"
}
```

`ttlMs: 0` means the result is immediately stale. `private` means a cache must
not reuse it across authorization contexts. This matters because the tool list
is scope-filtered. Legacy results do not contain these modern cache fields.

### Legacy compatibility

The POST endpoint also accepts the 2025-era `initialize` flow. Compatibility is
stateless: the server creates no cross-request protocol session and returns no
`Mcp-Session-Id`. Legacy POST replies use the 2025 Streamable HTTP event-stream framing. `GET` and `DELETE /api/mcp` return `405 Method Not Allowed`,
so legacy standalone SSE and session termination are not available.

Clients that support both eras should probe with `server/discover`, prefer
`2026-07-28` when advertised, and fall back to `initialize` only for a 2025-era
server. Official TypeScript SDK v2 clients should select automatic version
negotiation to enable that probe-and-fallback behavior.

### Read and write tools

Anonymous `tools/list` returns only released read-only tool schemas, never
customer data. Authenticated `tools/list` is filtered by the exact role and
scopes of that caller. Released read tools include:

* `project_inspect`, `project_plan`, `evaluations_list`, `runs_list`,
  `run_explain`, `baseline_lineage`, `docs_search`, and
  `connector_health` (which requires an admin boundary).
* Authorized connection reads such as `connections_list` and
  `connections_catalog`, subject to their declared scopes.

Released **evaluation-authoring** tools, available only to an authenticated
member or higher with the corresponding scope and explicit approval:

| Tool | Scope | Effect |
| - | - | - |
| `evaluations_create` | `eval:write` | Create a reviewed evaluation |
| `test_cases_add` | `eval:write` | Add a test case, subject to evaluation locks |
| `runs_start` | `runs:write` | Start a run after applicable cost/readiness guards |
| `traces_create` | `traces:write` | Record a trace after PII/retention review |

Connection-management writes require admin role and `admin:workspace`,
sometimes also `resources:read` and `resources:write`. A least-privilege
agent OAuth grant does not imply these elevated admin permissions. Review
the current input schema from authenticated `tools/list` before calling
any write, and verify persisted state afterward. A started run is **not**
a passing regression gate.

The separately qualified documentation MCP remains anonymous and read-only.
Portable Quality uploads/checks, baseline acceptance, release approval,
model promotion, and pull-request merging are **not** available as product
MCP writes. `project_plan` is advisory.

### Decision output contract

These MCP tools supply evidence; they do not create a separate classification
enum or make release decisions. Agents applying the `evaluate-ai-change` Skill
must use its [canonical decision schema](https://www.evalgate.com/.well-known/agent-skills/evaluate-ai-change/assets/decision-contract.schema.json).
`classification` deterministically selects `invokeEvalGate` and
`releaseDecision`; unknown labels and contradictory combinations are invalid.
The schema also requires quality, protected-slice, reliability, latency, and
cost evidence. Use `not_measured` with a reason when an MCP result does not
contain valid evidence for a dimension; do not infer a metric.
The MCP endpoint does not accept the canonical release-decision object as a
mutation. Approved evaluation authoring does not authorize release promotion.

## Legacy EvalGate HTTP Tool API

> `GET /api/mcp/tools` and `POST /api/mcp/call` are proprietary integration
> endpoints. They are not MCP transports and must not be configured in an MCP
> client.

### GET /api/mcp/tools

Returns the legacy tools available to the authenticated organization. A bearer
token with `eval:read` is required.

The legacy API identifies its proprietary contract as `evalgate-tool-api`.

```bash theme={null} theme={null}
curl https://evalgate.com/api/mcp/tools \
  -H "Authorization: Bearer YOUR_API_KEY"
```

By default, the legacy API returns only `eval.quality.latest`, `eval.get`, and
`eval.list`. The response is tenant-bound and private. Operators may set
`EVALGATE_TOOL_API_WRITES=true` to advertise its mutation tools, which still
require their authenticated write scopes. Keep the flag disabled for read-only
integrations.

### POST /api/mcp/call

Executes one of the proprietary tools. A write-capable tool returns `403
Forbidden` unless `EVALGATE_TOOL_API_WRITES=true` and the authenticated caller
has its required write scope.

```bash theme={null} theme={null}
curl https://evalgate.com/api/mcp/call \
  -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"eval.quality.latest","arguments":{"evaluationId":42}}'
```

Use `/api/mcp` for MCP clients. The legacy routes remain available only for
integrations that intentionally implement their proprietary HTTP contract.


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