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

# Discover EvalGate from an agent

> Official Skills, MCP endpoints, packages, branding, and verification boundaries.

## Official sources

Use the [EvalGate developer hub](https://www.evalgate.com/developers) as the
first-party starting point. The official
[EvalGate Skills repository](https://github.com/evalgate/skills) links back to
that hub and contains the portable Skill collection and MCP configuration.

The public repository's [AGENTS.md](https://github.com/evalgate/skills/blob/main/AGENTS.md)
describes how coding agents should work on that distribution. Its root
[plugin.json](https://github.com/evalgate/skills/blob/main/plugin.json) targets the
[Agent Plugins 1.0.0 specification](https://agent-plugins.org/specification);
compatible clients discover the bundled `skills/` collection and
[mcp.json](https://github.com/evalgate/skills/blob/main/mcp.json) from that same
repository. The public documentation MCP needs no credential. Product MCP tool
execution still requires approved organization-scoped credentials, managed by
the client; installing the plugin does not grant access.

For machine-readable discovery, request
[`GET /?mode=agent`](https://www.evalgate.com/?mode=agent). It returns JSON with
API URLs, authentication guidance, capabilities, public repository provenance
and a runnable test request. It is public even when the caller has a browser
session. Normal homepage visits and explicit Markdown requests keep their
existing representations.

```bash theme={null}
npx skills add evalgate/skills --list
npx skills add evalgate/skills
npx skills add evalgate/skills --skill evaluate-ai-change
```

Install the complete collection or a single self-contained Skill. Selected
installs include that Skill's required references. Skills do not configure MCP
servers or grant credentials. Read the
[coding-agent guide](https://evalgate.com/docs/guides/write-evals-with-your-agent.md) for its experimental
support boundary. Skill instructions do not grant credentials or authorize a release.

| Interface | Official destination |
| - | - |
| TypeScript SDK and CLI | [@evalgate/sdk on npm](https://www.npmjs.com/package/@evalgate/sdk) — read the published package version and command inventory from npm / `npx @evalgate/sdk capabilities --format json`, not from source trees |
| Python SDK | [evalgate-sdk on PyPI](https://pypi.org/project/evalgate-sdk/) — discover the published PyPI version separately; source parity is not publication |
| Go REST SDK | [evalgate-go/v3 3.17.0](https://pkg.go.dev/github.com/evalgate/evalgate-go/v3@v3.17.0) — Go 1.23+, typed operations and models; [first request](https://evalgate.com/docs/sdk/go.md) |
| Ruby REST SDK | [evalgate-sdk 3.17.0 on RubyGems](https://rubygems.org/gems/evalgate-sdk/versions/3.17.0) — Ruby 3.2+, generated methods, model validation and RBS; [first request](https://evalgate.com/docs/sdk/ruby.md) |
| API | [OpenAPI](https://www.evalgate.com/openapi.json) |
| Authentication | [auth.md](https://www.evalgate.com/auth.md) |
| Product MCP | [Product card](https://www.evalgate.com/.well-known/mcp/server-card.json) |
| Public documentation MCP | [Documentation card](https://www.evalgate.com/.well-known/mcp/docs-server-card.json) |
| Decision schema | [evaluate-ai-change decision schema](https://www.evalgate.com/schemas/evaluate-ai-change-decision.schema.json) |
| Brand asset | [EvalGate logo](https://www.evalgate.com/brand/evalgate.svg) |

The package registries can have different published versions. Consult
[feature status](https://evalgate.com/docs/platform/feature-status.md) before using source-only commands.

## Install a client and make the first read

The structured [`?mode=agent` response](https://www.evalgate.com/?mode=agent)
lists the four official ecosystems, installation commands, runtime requirements,
version metadata and language guides. The Go and Ruby packages are independently
public-install verified; both record OpenAPI 18.4.0 and 915 operations.

| Ecosystem | Install | Verify without customer access |
| - | - | - |
| npm | `npm install @evalgate/sdk` | `npm view @evalgate/sdk version` |
| PyPI | `pip install evalgate-sdk` | `pip show evalgate-sdk` |
| Go modules | `go get github.com/evalgate/evalgate-go/v3@v3.17.0` | `go list -m github.com/evalgate/evalgate-go/v3` |
| RubyGems | `gem install evalgate-sdk --version 3.17.0` | `ruby -revalgate -e 'puts EvalGate::VERSION'` |

For hosted REST calls, obtain a human-approved organization-scoped credential
through the [authentication guide](https://evalgate.com/docs/authentication.md). The examples use
`EVALGATE_API_KEY` and the optional `EVALGATE_ORGANIZATION_ID` selector, explicitly
passed to the Go/Ruby constructors. Use SDK base origin `https://www.evalgate.com`; generated paths
already include `/api`. Start with `GET /api/evaluations?limit=1` using
`eval:read`; this reads the approved organization without creating evaluations
or calling a model. Normal API-usage quotas apply. The organization selector does not grant access.

The [Go](https://evalgate.com/docs/sdk/go.md) and [Ruby](https://evalgate.com/docs/sdk/ruby.md) pages provide runnable first-request
programs and error, timeout, pagination and idempotency guidance. These clients
never automatically retry or follow redirects. Inspect `Retry-After` and
`RateLimit` on 429; preserve a stable idempotency key for the same retried mutation.

Go/Ruby provide REST clients. Native local runners and framework wrappers retain
their [language-specific support](https://evalgate.com/docs/guides/agent-framework-integrations.md). For
trace ingestion, follow the [OpenTelemetry/OpenInference and collector guide](https://evalgate.com/docs/help/telemetry/first-trace.md)
with a compatible exporter. SDK publication does not establish
live cloud endpoint or framework qualification. Public documentation and
anonymous assertion test mode can be explored over HTTP without an SDK key.

## Connect the right MCP server

`https://www.evalgate.com/api/mcp/docs` provides public, read-only documentation.
`https://www.evalgate.com/api/mcp` provides public protocol/schema discovery;
product tool execution requires organization-scoped credentials. Follow the
[MCP integration guide](https://evalgate.com/docs/platform/mcp-integration.md) for transport and authentication.

The current tool contract uses names such as `docs_list`,
`docs_search`, and `docs_get`. Retrieve `tools/list` for the actual input schemas;
`docs_list` accepts an empty object or its declared optional pagination fields.
Retrieve the new client guides with `docs_get` and `slug: "sdk/go"` or
`slug: "sdk/ruby"`. Do not rename
wire tool names to match a scanner's preferred naming style.

Find the official product server on
[Smithery: evalgate/evalgate](https://smithery.ai/servers/evalgate/evalgate).
The listing links back to EvalGate's developer hub and documents scoped
authentication. Smithery's first published scan recorded only the read-only discovery set.
The current [first-party MCP card](https://www.evalgate.com/api/mcp/server-card)
identifies the exact product server. Its live, credential-scoped `tools/list`
reports operations such as `evaluations_create`, `test_cases_add`, `runs_start`,
and `traces_create` plus authorized connector writes. Cards deliberately omit
static tool lists so they do not contradict a caller's actual permissions. An anonymous Smithery
scan may still see only read-only schemas; executable writes require an
authorized organization and a compatible client authentication flow.
The publisher listing needs a metadata refresh and authenticated acceptance
before promising a one-click write integration. An Agent Skills repository remains a separate distribution;
Glama, mcp.so, and ChatGPT app listings are not claimed. Same-name projects under
other publishers are not ownership evidence.

## Pick an agent for a fast, verifiable first result

All three start with the [official EvalGate Skills](https://github.com/evalgate/skills).
They are **recommended workflows**, not a guarantee that a client can connect
in one click or that a local result establishes production safety. Check
`npx @evalgate/sdk capabilities --format json` against the **installed** npm
version before relying on any optional CLI command.

| Agent | Best first job | Quick local, read-only start | What counts as proof |
| - | - | - | - |
| **Claude Code** | Explain the current AI behavior and identify a useful missing check | `npx @evalgate/sdk understand --format json` | Pinned source locators, limitations, and an explicit human-reviewed candidate |
| **Codex** | Examine a code change and draft a regression-gate plan | `npx @evalgate/sdk init --local --format json` | A preview first; only an approved `--apply` and a nonempty executed test can qualify a local gate |
| **Cursor** | Inspect repository readiness before modifying the code | `npx @evalgate/sdk status --json` | Distinct local/checkout/cloud states; an unlinked or unmeasured environment is not a pass |

Install with `npx skills add evalgate/skills` after previewing the list.
Connect an authenticated product MCP only after a person approves the scope.
The [EvalGate Smithery listing](https://smithery.ai/servers/evalgate/evalgate)
indexes the **product MCP**, not a public tenant-data feed. For credential-free
exploration, choose the [public documentation MCP](https://www.evalgate.com/api/mcp/docs)
or its [server card](https://www.evalgate.com/api/mcp/docs/server-card).

## Test without granting production access

The [public assertion test mode](https://www.evalgate.com/api/demo/custom-eval)
executes deterministic assertions against synthetic supplied text without an
account, customer-state access, saved evaluation results, provider calls or
evaluation charges. `GET` returns its contract and example; `POST` runs the
example at the same URL:

```bash theme={null}
curl https://www.evalgate.com/api/demo/custom-eval
curl https://www.evalgate.com/api/demo/custom-eval \
  -H 'Content-Type: application/json' \
  --data '{"output":"{\"answer\":42}","assertions":["valid-json"]}'
```

Expect `mode: "test"`, `persisted: false` and one passing assertion. Normal
access/API-usage metadata and rate-limit counters apply. This covers assertion
behavior only; it does not exercise hosted CRUD, model providers or payments.
See [API test mode](https://evalgate.com/docs/platform/api-test-mode.md) for limits and client examples.

Use the public documentation MCP to try a real remote endpoint without an
account or customer data. For application evaluation, follow the deterministic
local path in the [quickstart](https://evalgate.com/docs/quickstart.md), respecting its source-versus-published
package boundary. Local evaluation is not a hosted API sandbox. Hosted product
calls require a scoped credential and operate on the selected organization.

To exercise the real API without production data, use the
[local API sandbox](https://evalgate.com/docs/guides/api-sandbox.md). It runs this checkout in Docker with
a private database, synthetic credentials and outbound networking disabled.
Reset discards its data and credentials. Source availability and required Docker
resources apply; this is a local test mode.

## Verification boundaries

Every EvalGate page, including the homepage, registers WebMCP tools with
`document.modelContext.registerTool()` from an inline script in the page HTML,
with `navigator.modelContext` as a compatibility fallback. Four tools work
without an account: `open_evalgate_developer_resources`, `start_evalgate_setup`,
`get_evalgate_capabilities`, and `list_evaluation_templates`. The evaluation
tools (`create_evaluation`, `run_evaluation`, and the result readers) use the
visitor's signed-in session and return 401 otherwise. `start_evalgate_setup`
only opens the sign-up page; a person still chooses a provider and approves
access. EvalGate does not ship declarative `toolname` forms, which the WebMCP
specification does not define. A static crawler cannot prove that its browser
supports or executes WebMCP tools.

The public `/ask` endpoint supports `prefer.streaming: true` and SSE NLWeb 0.55
`start`, indexed `result`, `error`, and `complete` events without credentials.
It searches only the reviewed public documentation catalog, makes no model
calls and applies anonymous quota, query, body and result limits. If you supply
credentials, they must be valid and include `docs:read`. See the
[NLWeb reference](https://evalgate.com/docs/api/nlweb.md) for a runnable anonymous streaming request.

OAuth discovery starts at [auth.md](https://evalgate.com/auth.md), links to
protected-resource and authorization-server metadata, and documents supported
human-approved flows. The source candidate supports WorkOS `agent_auth`
`service_auth` through `/oauth/identity` and `/oauth/claim`, followed by a scoped
assertion exchange at `/oauth/token`. A verified person reviews the exact client,
scopes and organization; a stale claim attempt or changed workspace is rejected.
Third-party identity assertions and ID-JAG trust are not advertised. Consult the
deployed authorization-server metadata before using the flow.

The [Web Bot Auth guide](https://evalgate.com/docs/guides/web-bot-auth.md) describes the managed Ed25519
directory and outbound webhook signing lifecycle. Operators must publish and
verify a pending key before activation. An unconfigured directory fails closed;
a public JWK document alone does not verify incoming bots. Machine Payments Protocol support and
ChatGPT directory acceptance are also not claimed. These are separate product
and external-registration boundaries, not missing documentation badges.


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