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.

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.