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. The server is anonymous and public — leave any OAuth or API-key field empty. There is nothing to register or configure.

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

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.
`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, scorecard, and links.

Argument	Type	Meaning
`name`	string, required	Package name.
`sha`	string	Catalog commit to resolve against.

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.

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.

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.
`format`	`"cyclonedx"` \| `"spdx"`	Document format: CycloneDX 1.5 (default) or SPDX 2.3.

Returns the raw SBOM document.

`list_catalog_commits`

Recent commits on gominimal/pkgs:main — the shas the sha arguments and diff_catalog operate on.

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

Returns { commits }, newest first.

`diff_catalog`

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.