HTTP API

The API exposes two endpoints: a lookup for a single server and a full list of everything we track. Both are read-only, anonymous, and serve the same data the CLI displays.

• Base URL · https://polygraph.so
• Auth · none on these endpoints; subscriber endpoints land later under a separate path.
• Rate limit · none currently. We'll publish a budget here if we add one.
• Content type · application/json in and out.

Prefer the CLI for ergonomics: npx polygraphso check <ref> and npx polygraphso list. The CLI hits these same routes.

Every server we track is addressed by a registry-prefixed reference. Three variants, each matching its registry's native namespace:

npm/<package>@<version>           name (unscoped) or @scope/name (scoped)
pypi/<name>@<version>             flat — no owner segment
github/<owner>/<repo>@<version>   owner required

Real examples:

npm/@modelcontextprotocol/server-filesystem
npm/@notionhq/notion-mcp-server
pypi/mcp-server-git
pypi/mcp-server-fetch

The version segment is optional. Lookups are versionless — 1.0.0 and 1.0.1 of the same package resolve to the same grade.

Looks up one server’s published polygraph grade, or a notify URL if it hasn’t been graded yet.

Request

{
  "server_ref": "npm/@modelcontextprotocol/server-filesystem"
}

Response · graded

{
  "status": "graded",
  "polygraph": "A",
  "polygraph_detail": {
    "grade": "A",
    "c01": "pass",
    "c02": "pass",
    "c03": "pass",
    "tool_defs_fingerprint": "0x256a…66db6",
    "methodology_version": "litmus-v2",
    "rationale": "All three categories passed.",
    "computed_at": "2026-06-11T14:14:04Z"
  },
  "notify_url": "https://polygraph.so/notify?for=npm/@modelcontextprotocol/server-filesystem"
}

Note · polygraph is one of "A", "B", "D", "F" (there is no C — see the rubric). polygraph_detail carries the per-check results, tool-surface fingerprint, and methodology version.

Response · not graded

{
  "status": "not_available",
  "notify_url": "https://polygraph.so/notify?for=npm/some-owner/some-package"
}

A miss bumps an anonymous demand counter so we can see which ungraded servers are most in demand. No request body is logged beyond the ref itself.

curl

curl -X POST https://polygraph.so/api/cli/check \
  -H 'content-type: application/json' \
  -d '{"server_ref":"npm/@modelcontextprotocol/server-filesystem"}'

Errors

• 400 — missing, malformed, or too-long server_ref. The body includes a short error string.
• 500 — lookup failed server-side. Safe to retry.

Returns every server with a published polygraph grade, sorted by grade (A first), then alphabetically. No pagination in v0 — the graded set is small and the payload is well under a megabyte. We'll add pagination here if it grows past that.

Response shape

{
  "servers": [
    {
      "server_ref": "npm/@modelcontextprotocol/server-filesystem",
      "polygraph": "A"
    },
    {
      "server_ref": "npm/@upstash/context7-mcp",
      "polygraph": "D"
    }
  ],
  "total": 6
}

polygraph is one of "A", "B", "D", "F" (there is no C — see the rubric). Only graded servers appear; check a specific ungraded server with /api/cli/check.

curl

curl https://polygraph.so/api/cli/list

v0 changes are additive. We add fields; we don't remove or rename them. A breaking change — a removed field, a renamed key, a changed shape — would ship under a new path (/api/v1/...), and the v0 path would keep its existing behavior for a deprecation window we'll announce here.

The harness version that produced a given polygraph will be exposed on the grade payload once behavioral grading lands, so grades stay comparable within a harness version.

These endpoints are the contract the CLI is built against, so the URLs and field names are stable. The notify URL pattern (polygraph.so/notify?for=<ref>) is stable too; it's the same place the website's "tell me when this is graded" funnel writes to.

What isn't stable yet: the cadence of behavioral grade publication. The methodology and rubric are documented at /methodology.

• /llms.txt · short, machine-readable summary for agents.
• Landing · positioning, principles, who we are.