# AgentTrust > AgentTrust is an MCP trust server for AI agents: reliability > monitoring, endpoint-ownership verification, and pre-invocation trust > evaluation for MCP and A2A agents. Before invoking an unknown AI agent > or MCP server, call check_agent_trust with its exact endpoint URL to get > a machine-readable trustDecision for your own evaluation -- a signal > derived from AgentTrust's own observed and verified data, never a > certification or guarantee of safety. This anonymous, read-only check > needs no AgentTrust account or API key. Creating an agent identity, or > reading the fuller per-agent record (agent card, capabilities, health > history), does require one -- see Authentication below. > > Agents register an identity, get health-checked once a day, > optionally prove ownership of their endpoint, and accumulate a > deterministic reliability score from that observed history. Base URL: https://getagenttrust.com Full human-readable reference: https://getagenttrust.com/docs Official MCP Registry identity: io.github.agenttrust-ai/agenttrust TypeScript SDK: `npm install @getagenttrust/sdk` (see SDK below) ## First 5 minutes (TypeScript SDK) No account or API key. Node.js 18 or later. 1. Install. `assessAgent` needs SDK 0.2.0 or later: `npm install @getagenttrust/sdk@^0.2.0` 2. Check an endpoint. This checks AgentTrust's own monitored test agent, so it returns a real result. The check is read-only, and AgentTrust never contacts the endpoint you ask about. import { assessAgent } from "@getagenttrust/sdk"; // AgentTrust's own monitored test agent. Swap in the URL your agent is about to call. const assessment = await assessAgent("https://agenttrust-umber.vercel.app/api/test-agent"); console.log(assessment.decision, assessment.confidence, assessment.reasonCodes); // e.g. allow_with_caution high ["OWNERSHIP_VERIFIED", "REACHABLE_AT_LAST_CHECK", …] if (assessment.decision === "allow_with_caution") { // Reachable and not failing in AgentTrust's observations. Not proof that the // agent behaves safely: keep your own safeguards when you call it. } else { // "avoid", or "insufficient_evidence" — also the answer for a URL AgentTrust // doesn't monitor (matched: false, reasonCodes includes "UNKNOWN_ENDPOINT"). console.log("Not calling it:", assessment.limitations); } 3. Read the answer. `confidence`, `reasonCodes` and `limitations` say why. allow_with_caution — AgentTrust's observations show the endpoint reachable and not failing: a current historical reliability score, or at least two successful observations at least 10 minutes apart. What to do: Call it, with your own safeguards. It isn't proof that the agent behaves safely. avoid — AgentTrust's observations show it failing — for example two or more consecutive failures, or a current reliability score below 50. What to do: Don't call it. insufficient_evidence — Not enough evidence either way: an endpoint AgentTrust doesn't monitor, too few or too old observations, or a single failure that may be temporary. What to do: Don't treat it as approval — handle it as an unknown endpoint. Which call should I use? assessAgent(url) — Your agent needs one decision to act on before it calls an endpoint. You get: `decision`, `confidence`, `reasonCodes` and `limitations`, with the evidence behind them. checkAgentTrust(url) — You want the evidence itself — `status`, `reliabilityScore`, `verified` and `trustDecision` — to apply your own rules. You get: `{ matched: true, … }`, or `{ matched: false }` for an endpoint AgentTrust doesn't monitor. assertTrusted(url, policy) — You want a gate: go ahead only if the endpoint meets your policy. You get: The `checkAgentTrust` result, or a thrown `NotTrustedError`. All three are anonymous and read-only, and never contact the endpoint (over MCP: `assess_agent` and `check_agent_trust`). They report what AgentTrust has observed; they don't certify an endpoint's security. Unknown endpoints are an answer, not an error. AgentTrust only has evidence for endpoints it monitors, so your first check of a real URL may come back unknown. That is an answer, not an API failure — the call succeeds: - `assessAgent` returns `matched: false`, `decision: "insufficient_evidence"`, `confidence: "none"`, and `reasonCodes` including `"UNKNOWN_ENDPOINT"`. - `checkAgentTrust` returns `{ matched: false }`, sometimes with an `observation` status when AgentTrust has queued the URL for a lookup in the official MCP Registry. - `assertTrusted` throws `NotTrustedError` ("AgentTrust has no data for this endpoint") unless you pass `allowUnknown: true`. Real failures — `RATE_LIMITED`, `TIMEOUT`, `NETWORK_ERROR` and the rest — throw an `AgentTrustError` instead. Handle an unknown endpoint as not trusted: don't map `insufficient_evidence` to "allow", keep `allowUnknown: false` (the default) unless you have chosen otherwise on purpose, and ask a human or run your own checks before calling an endpoint nobody has observed. Next steps: - Gate a real connection: examples/check-before-connect.ts (https://github.com/agenttrust-ai/agenttrust/blob/main/packages/sdk/examples/check-before-connect.ts) puts `assertTrusted` in front of an MCP client connection. - Tune the gate: `minConfidence`, `requireVerified` and `minReliabilityScore` in the `assertTrusted` policy (see SDK below). - Running an agent yourself? Register it so other agents can check it — that needs an account and an API key: see Authentication below and https://getagenttrust.com/docs#getting-started. ## Workflow 1. Discover — this file, /docs, or AgentTrust's own A2A Agent Card at /.well-known/agent-card.json (for A2A-capable agents/clients). 2. Authenticate, if you need to. The MCP tools `check_agent_trust` and `assess_agent` at /api/mcp/public are anonymous and read-only: no AgentTrust account or API key (both are also served at /api/mcp; see MCP below). Every REST `/api/v1/*` request, and every MCP tool except `check_agent_trust` and `assess_agent`, requires an API key: a human creates one once, via the dashboard (sign up -> /dashboard/api-keys -> "Create key"). The raw key (`at_live_...`) is shown exactly once at creation; AgentTrust cannot show it again. Send it as `Authorization: Bearer `. 3. Look up an agent by the URL you are about to call: `GET /api/v1/agents?endpoint_url=` (API key), or with no key, `check_agent_trust({endpointUrl})` over MCP at /api/mcp/public. For a use-or-avoid decision instead, `assess_agent({endpointUrl})`. 4. Receive trust information: reliabilityScore, status, verified, lastCheckedAt/latencyMs/httpStatus, and a derived trustDecision. 5. Interpret trustDecision: recommended (boolean), confidence (high|medium|low|insufficient_data), reasons (string[]). 6. Make your own policy decision — e.g. only proceed when `recommended === true`, or apply a stricter rule yourself using `confidence`/`verified` directly. ## Authentication Every `/api/v1/*` request requires `Authorization: Bearer `. Getting a key is a one-time human step (sign up, then create a key in the dashboard) — there is currently no unauthenticated or self-service account-creation API. Revoked keys remain visible in the owner's dashboard for audit/usage history but can never authenticate again once revoked. Missing key -> 401: `{"error":{"code":"UNAUTHENTICATED","message":"Missing API key. Provide one as: Authorization: Bearer "}}` Invalid/expired/revoked key -> 401: `{"error":{"code":"UNAUTHENTICATED","message":"Invalid, expired, or revoked API key."}}` ## Rate limits Anonymous (no API key): `check_agent_trust` and `assess_agent` share one limit, counted in fixed 60-second windows: 10 checks per caller IP address, and 300 across all anonymous callers combined. It applies to both tools on `/api/mcp/public` and on `/api/mcp` (even when an API key is sent), and to the browser checker at `/check-agent-trust`. Over the limit, the HTTP response is still 200: the tool returns an error result (`isError: true`) whose `structuredContent.error` has the code `RATE_LIMITED` and `retryAfterSeconds`. The SDK reports it as an `AgentTrustError` with the code `RATE_LIMITED` and never retries on its own. A call whose IP address can't be determined is refused the same way. With an API key (REST `/api/v1/*`): 100 requests / 60 seconds, per API key, fixed window. Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers. Over the API-key limit -> 429 with a `Retry-After` header (seconds): `{"error":{"code":"RATE_LIMITED","message":"Rate limit exceeded. Try again later."}}` ## Endpoints GET /api/v1/agents Plain listing of public, active agents. Query params: `limit` (1-100, default 20), `cursor` (opaque, from a previous response's `pagination.nextCursor`). No endpoint_url given -> the base fields only (no reliabilityScore/trustDecision — see the lookup form below). GET /api/v1/agents?endpoint_url= The trust-check entry point. Exact match only (see Normalization) on an agent's registered endpoint URL. Same response envelope as the plain listing, but each matched agent also carries reliabilityScore, reliabilityScoreComputedAt, lastCheckedAt, latencyMs, httpStatus, and trustDecision. An unregistered URL returns 200 with `"data": []` — not an error. Example request: GET /api/v1/agents?endpoint_url=https%3A%2F%2Fapi.example-acme.com%2Fv1%2Finvoke Authorization: Bearer at_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Example response (200, fictional values): { "data": [ { "id": "3fa1c2b0-1234-4a5b-8c9d-abcdef123456", "slug": "acme-support-bot", "name": "Acme Support Bot", "description": "Handles tier-1 customer support requests.", "version": "1.2.0", "capabilities": ["chat", "ticket-triage"], "status": "healthy", "createdAt": "2026-01-15T10:00:00.000Z", "agentCard": { "schemaVersion": "1.0", "name": "Acme Support Bot", "description": "Handles tier-1 customer support requests.", "capabilities": ["chat", "ticket-triage"], "authentication": { "type": "none" }, "interfaces": { "modalities": ["text"], "interactionType": "request-response" }, "documentationUrl": null }, "source": "owner_registered", "verified": false, "ownershipVerifiedAt": null, "reliabilityScore": 97, "reliabilityScoreStatus": "fresh", "reliabilityScoreComputedAt": "2026-09-14T00:44:16.440Z", "lastCheckedAt": "2026-09-14T00:44:13.152Z", "latencyMs": 142, "httpStatus": 200, "trustDecision": { "recommended": true, "confidence": "low", "reasons": ["Endpoint ownership has not been verified."] } } ], "pagination": { "nextCursor": null } } This is a realistic pattern, not a corner case: a strong, healthy, UNVERIFIED agent is still `recommended: true` — see "trustDecision" below for why. `source` (`"owner_registered"` | `"externally_observed"`): how the agent entered AgentTrust. `owner_registered` means a human registered and activated it. `externally_observed` means AgentTrust discovered it from a public agent registry on nobody's behalf — it is always unclaimed (`ownerId` null) and unverified, exactly like any other unverified agent; `source` is provenance, not a trust signal by itself. GET /api/v1/agents/{slug} Same enrichment as the endpoint_url lookup, for one agent by its AgentTrust slug. 404 `{"error":{"code":"NOT_FOUND", "message":"..."}}` if the slug doesn't exist or isn't public+active. GET /api/v1/agents/{slug}/health `{agentId, slug, status, lastCheckedAt, latencyMs, httpStatus, checkStatus, reliabilityScore, reliabilityScoreStatus, reliabilityScoreComputedAt}` POST /api/v1/agents/{slug}/heartbeat Owner-only (the key must belong to that agent's own account) — records a push-mode liveness signal. Reads no request body. For a pull-mode agent (the default) it only updates lastHeartbeatAt; status and score come from AgentTrust's own checks. `{slug, status, lastHeartbeatAt}` GET /api/v1/assessments?endpoint_url= The assess_agent result (see MCP below) as `{"data": {...}}`. Read-only: built from stored observations, never contacts the URL. An unknown URL returns decision "insufficient_evidence", never an error. ## Common errors - 401 UNAUTHENTICATED — missing, invalid, expired, or revoked key. - 404 NOT_FOUND — unknown slug on `GET /agents/{slug}`. An unknown `endpoint_url` on the list endpoint is NOT an error — it's 200 with an empty `data` array. - 400 VALIDATION_ERROR — e.g. `limit=0` or a malformed `cursor`; the body includes a `details` object with per-field messages. - 429 RATE_LIMITED — see Rate limits above. ## URL normalization (endpoint_url lookup) Exact match only — never fuzzy or partial. Both the URL you pass and each registered URL go through standard URL parsing, plus one extra rule, before comparing: 1. A trailing slash on a non-root path (`.../invoke/` matches `.../invoke`). 2. Scheme/host casing (`HTTPS://Example.com` matches `https://example.com`), and the other effects of standard URL parsing — e.g. a default port is dropped (`https://example.com:443/a` matches `https://example.com/a`). Nothing else is normalized — path casing, query strings, fragments and non-default ports are compared exactly as given. ## Interpreting trustDecision Derived entirely from an agent's existing status, reliability score, and verification state — never a second/independent score. recommended (boolean): true only when `status === "healthy"` AND `reliabilityScore !== null` AND `reliabilityScore >= 50` AND `reliabilityScoreStatus === "fresh"`. reliabilityScoreStatus ("none" | "fresh" | "stale"): - `none`: no score computed yet. - `fresh`: the latest score was produced by the agent's most recent health check (a score needs at least 5 checks in the 7 days before it) and is at most 50 hours old. It doesn't change between monitoring runs. - `stale`: a score exists, but it's more than 50 hours old, or a newer health check couldn't produce a replacement. A stale `reliabilityScore` is the last computed value, kept for reference — NOT current evidence — and never makes an agent `recommended`. confidence ("high" | "medium" | "low" | "insufficient_data"): - `insufficient_data` if `reliabilityScore` is null (not enough monitoring history yet to compute one) or `reliabilityScoreStatus` is "stale". - otherwise `low` if the agent is unverified, regardless of score. - otherwise `high` if score >= 90, `medium` if score >= 50, `low` below that. reasons (string[]): a plain-language explanation for every factor that counted against the agent — empty only when nothing did. IMPORTANT: `verified` is a trust SIGNAL, not a hard requirement. Ownership verification is optional and does not gate `recommended` — an unverified agent with strong health/reliability history can still be `recommended: true` (see the example above). Verification instead affects `confidence`, and its absence is always spelled out explicitly in `reasons`, so a caller who wants a stricter policy (e.g. "only trust verified agents") can enforce that themselves using the raw `verified` field — AgentTrust doesn't impose that policy for everyone. ## MCP No-auth endpoint with only check_agent_trust and assess_agent: `https://getagenttrust.com/api/mcp/public` (Streamable HTTP). ### Connect an MCP client Two endpoints, both Streamable HTTP. Most agents need only the first: Public connector — no key (recommended): https://getagenttrust.com/api/mcp/public No authentication. Two read-only tools, check_agent_trust and assess_agent. Full MCP server — API key: https://getagenttrust.com/api/mcp Every tool except check_agent_trust and assess_agent needs `Authorization: Bearer `. Adds list_agents, get_agent, get_agent_health and send_heartbeat. Claude Code (https://code.claude.com/docs/en/mcp): claude mcp add --transport http agenttrust https://getagenttrust.com/api/mcp/public Add `--scope user` to make it available in every project; confirm with `claude mcp list`. Claude Desktop and claude.ai (https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp): AgentTrust is listed in Claude's connector directory: https://claude.ai/directory/agenttrust. Or add a custom connector: Customize -> Connectors -> + Add -> Add custom connector, name AgentTrust, URL https://getagenttrust.com/api/mcp/public, then Continue -> Add (no authentication). Team and Enterprise: an owner adds it under Organization settings -> Connectors. In a chat: + -> Connectors -> turn AgentTrust on. Free plans can add one custom connector. claude_desktop_config.json is not needed (it is for local servers). Cursor (https://cursor.com/docs/context/mcp) — in ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project): { "mcpServers": { "agenttrust": { "url": "https://getagenttrust.com/api/mcp/public" } } } Any HTTP client: see the curl example in the Quick Start at https://getagenttrust.com/docs#quick-start. Full MCP server (API key) — only if you need the keyed tools. Replace with a key from Dashboard -> API keys, and keep it out of shared files (Claude Code: keep the default local scope; Cursor: use ~/.cursor/mcp.json, not a project file you commit): claude mcp add --transport http agenttrust-account https://getagenttrust.com/api/mcp --header "Authorization: Bearer " { "mcpServers": { "agenttrust-account": { "url": "https://getagenttrust.com/api/mcp", "headers": { "Authorization": "Bearer " } } } } ### Endpoints and tools Endpoint: `https://getagenttrust.com/api/mcp` (GET and POST, Streamable HTTP transport). Auth: the same Bearer token as REST, in the `Authorization` header — except `check_agent_trust` and `assess_agent`, below, which need none. `tools/list` works without a key; calling any other tool requires one (the same 401 as REST on a missing/bad key). check_agent_trust({endpointUrl}) — pre-invocation trust check for an unknown AI agent or MCP server endpoint. No API key or account required. Read-only, and never contacts endpointUrl itself — it only reads AgentTrust's own already-observed data. Returns { matched: false } for an unregistered URL, or { matched: true, slug, name, status, verified, reliabilityScore, reliabilityScoreStatus, trustDecision } for a known public+active agent. Anonymous calls are rate-limited per caller IP; over the limit the tool returns an error result with the code RATE_LIMITED and retryAfterSeconds (see Rate limits). assess_agent({endpointUrl}) — a use-or-avoid decision for an agent about to call endpointUrl. No API key or account required. Read-only, and never contacts endpointUrl: built only from AgentTrust's stored observations. Returns { assessmentVersion, mode, status, matched, decision, confidence, reasonCodes, reachability, initialRisk, historical, agent, limitations, freshness }: decision: "allow_with_caution" | "avoid" | "insufficient_evidence" confidence: "high" | "medium" | "low" | "none" reasonCodes: machine-readable reasons, e.g. UNKNOWN_ENDPOINT, FEW_OBSERVATIONS, TRANSIENT_NETWORK_FAILURE, PERSISTENT_FAILURE, RECOVERING, SUFFICIENT_HISTORY, OWNERSHIP_UNVERIFIED (new codes may be added) reachability: the latest stored observation (outcome, httpStatus, latencyMs, checkedAt, ageSeconds, fresh) — not a live check initialRisk.level: "low" | "moderate" | "elevated" | "high" | "unknown" historical: the reliability score and trustDecision, unchanged (null when unmatched) limitations: what the result does not show; the first always says reachability is not safety Rules: allow_with_caution needs a fresh historical score (healthy, >= 50) or at least two successful observations 10+ minutes apart — one success is never enough. avoid: two or more consecutive failed observations, a down agent that is still failing, a fresh score below 50, or a TLS failure or an endpoint resolving into a private network. A single failure that may be temporary, a recovering agent, too few observations, evidence older than 50 hours, or an unknown URL is insufficient_evidence. Same anonymous per-IP rate limit as check_agent_trust. Tools requiring an API key (each backed by the exact same handler as its REST equivalent): list_agents({limit?, cursor?, endpointUrl?}) — `endpointUrl` triggers the same trust-check enrichment as the REST `?endpoint_url=` filter, plus the full public agent record (agentCard, capabilities, etc.) that check_agent_trust deliberately omits. get_agent({slug}) — same enriched shape as `GET /agents/{slug}`. get_agent_health({slug}) — same as `GET /agents/{slug}/health`. send_heartbeat({slug}) — owner-only, same as `POST /agents/{slug}/heartbeat`. Example — list_agents with endpointUrl: Request: { "endpointUrl": "https://api.example-acme.com/v1/invoke" } Response: `structuredContent.agents[0]` has the exact same fields as the REST example above. ## SDK (TypeScript) Official SDK for AgentTrust's two anonymous checks: `npm install @getagenttrust/sdk` (https://www.npmjs.com/package/@getagenttrust/sdk). checkAgentTrust and assertTrusted call check_agent_trust, and assessAgent calls assess_agent, on https://getagenttrust.com/api/mcp/public, with typed results and errors. No API key or account. Node.js 18 or later; an ES module (`require()` works on Node.js 20.19+ and 22.12+). Use version 0.2.0 or later — the current release, and the first with assessAgent; 0.1.0 and 0.1.1 are deprecated. Not affiliated with the `@agenttrust` npm scope. Example endpoint: https://agenttrust-umber.vercel.app/api/test-agent is AgentTrust's own monitored test agent, so checking it returns a real result. AgentTrust never contacts the endpoint you check. import { checkAgentTrust, assertTrusted, NotTrustedError } from "@getagenttrust/sdk"; const result = await checkAgentTrust("https://agenttrust-umber.vercel.app/api/test-agent"); if (result.matched) { // result.status, result.verified, result.reliabilityScore, // result.reliabilityScoreStatus, result.trustDecision } // Throws NotTrustedError (see error.failures) unless the endpoint meets the policy. await assertTrusted("https://agenttrust-umber.vercel.app/api/test-agent", { minConfidence: "medium" }); Functions: checkAgentTrust(endpointUrl, { timeoutMs?, signal? }?) — the trust check. Resolves to { matched: true, slug, name, status, verified, reliabilityScore, reliabilityScoreStatus, trustDecision } or { matched: false, observation? } (never a score). assertTrusted(endpointUrl, policy?, options?) — throws NotTrustedError unless the endpoint meets the policy; fails closed on unknown endpoints. Returns the result it decided on. evaluatePolicy(result, policy?) — the same policy check on a result you already have; returns the failed requirements (empty = passes). assessAgent(endpointUrl, { timeoutMs?, signal? }?) — the assess_agent decision (see MCP above): decision, confidence, reasonCodes, reachability, initialRisk, historical, limitations, freshness. Requires @getagenttrust/sdk 0.2.0 or later. createAgentTrustClient({ endpoint?, timeoutMs?, fetch?, userAgent? }) — a client with its own options (default timeout 10000 ms) and the same checkAgentTrust/assertTrusted/assessAgent methods. Policy options (booleans must be true or false; any other value, or any other invalid policy, throws TypeError before a request is made): requireRecommended (default true) — require trustDecision.recommended. minConfidence — "low", "medium" or "high". requireVerified (default false) — require proven endpoint ownership. minReliabilityScore — 0-100; a missing or stale score fails it. allowUnknown (default false) — accept an endpoint with no data. Errors: invalid client options, per-call options and policies throw a plain TypeError. Everything else is an AgentTrustError with a `code`: INVALID_URL (not an absolute http(s) URL, or it contains a username or password; no request is made), RATE_LIMITED (see retryAfterSeconds), TIMEOUT, ABORTED, NETWORK_ERROR, HTTP_ERROR (see status), PROTOCOL_ERROR (not a valid check_agent_trust or assess_agent result), TOOL_ERROR, NOT_TRUSTED (NotTrustedError, with failures and result). The SDK never retries on its own. Full reference: https://github.com/agenttrust-ai/agenttrust/tree/main/packages/sdk#readme ## Not yet built The official SDK covers only the two anonymous checks, check_agent_trust and assess_agent (see SDK above); for everything else — registering agents, and the REST API and keyed MCP tools — use those directly. No programmatic/self-service account creation — a human creates the account and first API key. No batch/multi-URL lookup — call `?endpoint_url=` once per URL.