MCP Server Reference

minimal.dev hosts a Model Context Protocol server at https://minimal.dev/api/mcp. It exposes the package catalog as typed tools, so an agent attaches it by URL and discovers the surface instead of hand-wiring HTTP calls.

Every tool is read-only and anonymous, and delegates to the same compose pipeline as the Packages API — a tool result carries the same payload as its JSON-endpoint twin by construction, so the two surfaces cannot drift.

Connecting

Authentication. None to configure — leave any OAuth or API-key field empty. The server is anonymous, which is also why its sha-addressed calls fail: the sha-pinned half of the catalog requires a signed-in session that this server has no way to present.

Claude Code:

claude mcp add --transport http minimal-pkgs https://minimal.dev/api/mcp

Claude (claude.ai / desktop): add a custom connector with remote MCP server URL https://minimal.dev/api/mcp.

Any other MCP client that speaks streamable HTTP:

{
  "mcpServers": {
    "minimal-pkgs": {
      "url": "https://minimal.dev/api/mcp"
    }
  }
}

Transport

The server speaks streamable HTTP in stateless mode:

POST /api/mcp carries the JSON-RPC exchange. Responses are always a single application/json body — this server never opens an SSE stream, even when the client’s Accept header offers text/event-stream (which the streamable HTTP spec still requires clients to send). Responses are never cached (Cache-Control: private, no-store).
GET and DELETE return 405. These are the SSE-resumption and session-teardown channels of the stateful variant; a stateless server has no session to resume or delete.
Request bodies are capped at 256 KB; larger requests return 413.

Because the server is stateless, no session id is issued and every request is self-contained — clients that reconnect lose nothing.

Tools

All nine tools are read-only. Results are returned as structuredContent (a typed object) plus a serialized-JSON content text block for clients that only read text.

Sha-addressed calls require authentication this server cannot present. The sha-pinned half of the JSON API is gated behind a signed-in session, and this server is anonymous, so passing a sha to any tool — and calling diff_catalog at all, since both of its arguments are shas — returns an isError: true result. That holds until API token auth lands; there is nothing to configure in the meantime. Every tool that takes an optional sha still resolves the latest gominimal/pkgs:main commit when called without one, and list_catalog_commits still lists the history; diff_catalog has no such fallback.

Once token auth lands: tools that accept an optional sha resolve against that catalog commit; omitting it resolves the latest gominimal/pkgs:main commit at call time. sha accepts a 7–40 character hex commit prefix (unique prefixes resolve, ambiguous ones error).

`search_packages`

Search and filter the catalog. All arguments are optional.

Argument	Type	Meaning
`query`	string	Full-text query over name and description.
`category`	string	Filter to one package category. `canadian` is also accepted and selects packages made by Canadians — the same pseudo-category behind the listing’s “Made by Canadians” row.
`severity`	string	Filter to packages with an active advisory at this severity.
`limit`	int (1–50)	Page size, default 20.
`offset`	int	Pagination offset.

Returns { total, packages } with listing-tier records (name, version, license, category, advisory rollup).

`get_package`

Full record for one package: versions, dependencies, direct and transitive advisories, OpenSSF scorecard, and links. The scorecard is OpenSSF Scorecard data rather than a Minimal rating; scorecard.source and scorecard.repository say who ran the scan and which repository it scored, scorecard.overall is Scorecard’s 0–10 aggregate, and scorecard.checks holds the per-check scores as the tool reports them (see the API reference).

Argument	Type	Meaning
`name`	string, required	Package name.
`sha`	string	Catalog commit to resolve against. Requires authentication — see Tools.

Same payload as /api/pkgs/{name}.json.

`get_package_versions`

Version-history timeline for one package.

Argument	Type	Meaning
`name`	string, required	Package name.
`sha`	string	Catalog commit to resolve against. Requires authentication — see Tools.

Same payload as /api/pkgs/bundle/{sha}/{name}/versions.json.

`get_advisories`

Active security advisories for one package.

Argument	Type	Meaning
`name`	string, required	Package name.
`include_transitive`	boolean	Also compute advisories reachable through the dependency closure. Defaults to `true`; pass `false` for direct-only.

Returns { name, advisories }, plus transitiveAdvisories unless include_transitive is false.

`get_dependencies`

Direct dependencies of one package, enriched with version, license, and advisory rollup.

Argument	Type	Meaning
`name`	string, required	Package name.
`sha`	string	Catalog commit to resolve against. Requires authentication — see Tools.

Same payload as /api/pkgs/bundle/{sha}/{name}/deps.json.

`get_sbom`

Software bill of materials for one package, covering the transitive build + runtime closure with a vulnerabilities block.

Argument	Type	Meaning
`name`	string, required	Package name.
`sha`	string	Catalog commit to resolve against. Requires authentication — see Tools.
`format`	`"cyclonedx"` \| `"spdx"`	Document format: CycloneDX 1.5 (default) or SPDX 2.3.

Returns the raw SBOM document.

`get_attestation`

Build provenance for one package at the latest commit, per architecture: whether a signed attestation exists for the artifact the catalog ships, the artifact sha256, builder, source commit, run id, resolved dependencies, and the result of checking each signature.

Argument	Type	Meaning
`name`	string, required	Package name.
`sha`	string	Catalog commit to answer for: what that commit shipped, not latest. Requires authentication — see Tools.

Same payload as /api/pkgs/{name}/attestation.json (or its sha-pinned sibling when sha is given), which documents the map and per-arch state values.

`list_catalog_commits`

Recent commits on gominimal/pkgs:main — the shas the sha arguments and diff_catalog operate on. Unaffected by the sha-addressed disable above: it floats with the tip rather than resolving a caller-supplied sha.

Argument	Type	Meaning
`limit`	int (1–50)	Number of commits, default 30.

Returns { commits }, newest first.

`diff_catalog`

Requires authentication — both arguments are shas, so every call returns an isError result. See Tools.

Catalog diff from base (older) to sha (newer): packages added and removed, version upgrades, and advisory-count deltas.

Argument	Type	Meaning
`sha`	string, required	Newer catalog commit.
`base`	string, required	Older catalog commit.

Same payload as /api/pkgs/bundle/{sha}/diff/{base}.json.

Errors

Expected failures — an unknown package, a bad or ambiguous sha, the vulnerability database being temporarily unavailable — come back as tool results with isError: true and an actionable message, not as protocol errors. Agents can read the message and retry or correct the call.

Versioning

The server reports its version as {schemaVersion}.0.0, where schemaVersion is the same payload schema version every Packages API JSON response carries. A major bump signals a breaking change to result shapes.