Skip to main content

​
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 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 and agent discovery guide.

​
Connect an MCP client

The official product server is listed as evalgate/evalgate on Smithery. 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.

​
Cursor (.cursor/mcp.json)

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

​
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. 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:
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 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

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 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: 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. 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.