# MCP server

> Reference for the hosted Model Context Protocol server at /api/mcp — connecting MCP clients and the nine read-only tools it exposes over the catalog.

Source: https://minimal.dev/docs/reference/mcp

minimal.dev hosts a [Model Context Protocol](https://modelcontextprotocol.io)
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](https://minimal.dev/docs/reference/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](#tools): the sha-pinned half of the catalog
requires a signed-in session that this server has no way to present.

**Claude Code:**

```shell
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:

```json
{
  "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](https://minimal.dev/docs/reference/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](https://minimal.dev/docs/reference/api)).

| Argument | Type | Meaning |
|----------|------|---------|
| `name` | string, required | Package name. |
| `sha` | string | Catalog commit to resolve against. **Requires authentication** — see [Tools](#tools). |

Same payload as [`/api/pkgs/{name}.json`](https://minimal.dev/docs/reference/api).

### `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](#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](#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](#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](#tools). |

Same payload as
[`/api/pkgs/{name}/attestation.json`](https://minimal.dev/docs/reference/api#get-apipkgsnameattestationjson)
(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](#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](https://minimal.dev/docs/reference/api) JSON response carries. A major bump signals
a breaking change to result shapes.