EvalGate MCP and HTTP Tool APIs

MCP endpoint

POST /api/mcp is EvalGate’s authenticated, read-only MCP endpoint. 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. The token must include eval:read; individual tools appear only when the caller also has their required read scope.

Modern request contract

MCP 2026-07-28 does not use initialize, notifications/initialized, or Mcp-Session-Id. Send every JSON-RPC request as its own authenticated POST. 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:

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:

{
  "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.

Available tools

project.inspect
project.plan
evaluations.list
runs.list
run.explain
baseline.lineage
docs.search
connector.health

All eight tools are read-only. Plans are advisory: they never write a repository, accept a baseline, start a run, change credentials, or post a pull request comment. Use the CLI or web control plane for approved mutations. connector.health requires the organization-admin read boundary.

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. 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 remains read-only and does not accept the decision object as a mutation.

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.

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.

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.

Overview

Endpoints

Mcp

EvalGate MCP and HTTP Tool APIs

MCP endpoint

Modern request contract

Legacy compatibility

Available tools

Decision output contract

Legacy EvalGate HTTP Tool API

GET /api/mcp/tools

POST /api/mcp/call

​EvalGate MCP and HTTP Tool APIs

​MCP endpoint

​Modern request contract

​Legacy compatibility

​Available tools

​Decision output contract

​Legacy EvalGate HTTP Tool API

​GET /api/mcp/tools

​POST /api/mcp/call

EvalGate MCP and HTTP Tool APIs

MCP endpoint

Modern request contract

Legacy compatibility

Available tools

Decision output contract

Legacy EvalGate HTTP Tool API

GET /api/mcp/tools

POST /api/mcp/call