Models MCP

Search, compare, and inspect AI models by pricing, context window, and capabilities. An MCP server over the models.dev catalog (models.dev/api.json), so your agent always has current model data without you hand-maintaining a list.

models.dev itself doesn't ship an MCP server, just a JSON API and a TypeScript SDK for reading it. This fills that gap.

Runs two ways from the same tool code:

• stdio (src/index.ts) for local MCP clients

• Cloudflare Worker (src/worker.ts) as a remote Streamable HTTP endpoint at /models-mcp

Tools

All search-style tools (find_models, top_models) share one filter schema, so filter semantics are identical everywhere. Ranking and estimation exclude models that lack the relevant data (e.g. unpriced local models) rather than guessing.

Related MCP server: model-version-mcp

Install

npm install
npm run build

Run standalone over stdio (for testing)

npm start

It speaks MCP over stdio, so you won't see much directly; use the MCP Inspector to poke at it:

npx @modelcontextprotocol/inspector node dist/index.js

Host on Cloudflare Workers

The Worker entry (src/worker.ts) serves the same tools over Streamable HTTP at /models-mcp, with:

• Catalog caching in the Workers Cache API (caches.default) with a 1-hour TTL, shared across requests and isolates.

• Per-IP rate limiting via a Workers rate limiting binding: 60 requests/minute per IP, enforced per Cloudflare location. Excess requests get 429 with Retry-After: 60.

# local dev at http://localhost:8787/models-mcp
npm run dev:worker

# deploy
npm run deploy

After deploy, the canonical endpoint is https://mcp.dosa.dev/models-mcp. The generated https://models-mcp.<your-subdomain>.workers.dev/models-mcp URL stays live as a fallback.

Point MCP clients at it:

Claude Code:

claude mcp add --transport http models-mcp https://mcp.dosa.dev/models-mcp

Generic client config (anything that speaks Streamable HTTP):

{
  "mcpServers": {
    "models-mcp": {
      "url": "https://mcp.dosa.dev/models-mcp"
    }
  }
}

For stdio-only clients (Claude Desktop), bridge with mcp-remote:

{
  "mcpServers": {
    "models-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.dosa.dev/models-mcp"]
    }
  }
}

No API keys required anywhere. All data comes from the public models.dev/api.json endpoint.

Try it out

With the dev server running (npm run dev:worker), the endpoint is http://localhost:8787/models-mcp.

Quick curl (MCP initialize):

curl -X POST http://localhost:8787/models-mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"1.0"}}}'

Expect an SSE response with serverInfo.name: "models-mcp".

MCP Inspector (best for poking at tools interactively):

npx @modelcontextprotocol/inspector

Set Transport Type to Streamable HTTP and URL to http://localhost:8787/models-mcp, then call tools from the UI.

Claude Code against the local server:

claude mcp add --transport http models-mcp-local http://localhost:8787/models-mcp

Then ask it something like "which anthropic models cost under $1 per million input tokens?" and watch it reach for find_models.

Rate limiting: fire 61 rapid requests at the endpoint and request 61 onwards returns 429 with Retry-After: 60.

Things worth trying in the Inspector:

• find_models with combined filters, e.g. maxInputCost: 0.5 together with minContext: 200000

• get_model with a bare id like gpt-5.2 (resolves) and with a nonsense id (clean tool error)

• compare_models with one invalid id mixed in (it lands under notFound)

• The first call fetches the live catalog (~200ms); repeat calls are cache hits

Tests

npm test

Covers the catalog client (flattening, TTL caching, force refresh, stale-on-failure fallback, id resolution) and all eight tools end-to-end through a real MCP client session over an in-memory transport.

Notes on the data

• The catalog is cached for 1 hour: in the Workers Cache API when hosted, in process memory over stdio. Call refresh_catalog to force an update. If a refetch fails, the last good catalog keeps being served and refresh_catalog reports servedStale: true so you can tell.

• A daily GitHub Actions workflow (Catalog drift) fetches the live api.json and sanity-checks it against the flattening logic, since models.dev publishes no versioned schema. It opens a catalog-drift issue if upstream changes shape. Run it locally with npm run build && npm run test:live.

• models.dev doesn't publish a versioned schema for consumers, so the types in src/types.ts are intentionally loose (index signatures preserve any fields not explicitly typed).

• Model ids follow the provider/model convention used by the AI SDK and OpenCode, e.g. anthropic/claude-sonnet-4-5. get_model and compare_models also accept a bare model id when it names exactly one model across all providers; if the bare id is ambiguous (common with aggregator providers mirroring first-party models), the tool errors with the list of candidate provider/model ids instead of silently picking one. get_provider emits full provider/model ids so its output round-trips through get_model unchanged.

Possible extensions

• A list_facets tool (modalities, tokenizers) similar to what other model-catalog MCPs expose.

• A test_model tool that makes a live call through whichever provider key you have configured, for latency/cost sanity checks.

• OAuth or Cloudflare Access in front of the Worker, if you want it private.