Skip to main content

​
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:
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 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: 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. 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.
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.
Use /api/mcp for MCP clients. The legacy routes remain available only for integrations that intentionally implement their proprietary HTTP contract.