Kosha Model Discovery MCP server

kosha-discovery

Tells your agent — or your code — which model to use and what it costs.

kosha discovers models across 45 providers and local runtimes, finds your API keys wherever they already live (env vars, Claude CLI, Codex, gcloud ADC, AWS SSO), fills in pricing and context limits, and answers questions like the cheapest model with tool use and 128k context that I actually hold a key for. It ships as a TypeScript library, a CLI, an HTTP API, an OpenAI-compatible proxy with a spend ledger, and an MCP server.

It works with no API keys at all — discovery falls back to the public models.dev and LiteLLM catalogs, so kosha list is useful on a fresh machine.

Install

npm install @sriinnu/kosha-discovery       # library / server
npm install -g @sriinnu/kosha-discovery    # global `kosha` CLI

Requires Node.js 22+.

Quick start

Library

import { createKosha } from "@sriinnu/kosha-discovery";

const kosha = await createKosha();

const models   = kosha.models();                          // ModelCard[] across every provider
const cheapest = kosha.cheapestModels({ role: "image" }); // ranked by price, with missingCredentials
const sonnet   = kosha.model("sonnet");                   // alias → canonical ID; undefined if unknown
console.log(sonnet?.pricing); // { inputPerMillion: 2, outputPerMillion: 10, cacheReadPerMillion: 0.2, ... }

CLI

kosha discover                       # query every provider; writes ~/.kosha/cache and the manifest
kosha list --provider anthropic      # read from the local cache
kosha model sonnet                   # one model, alias-aware
kosha routes claude-opus-5           # every serving route for a model (direct, OpenRouter, Bedrock, …)
kosha cheapest --role embeddings     # rank by price for a role
kosha doctor --ci                    # deprecations + provider health; non-zero exit for CI
kosha spend --since 2026-09-01       # roll up the proxy's spend ledger
kosha refresh                        # bypass the cache and re-discover
kosha serve --port 3000              # HTTP API + proxy; binds 127.0.0.1 (see Proxy below)

Every command takes --json. kosha --help lists the rest.

After each discovery, a stable v1 manifest lands at ~/.kosha/registry.json:

jq '.models[] | select(.pricing.inputPerMillion < 0.1) | .modelId' ~/.kosha/registry.json

Public snapshot

A weekly discovery run publishes a full snapshot — every provider, model, price and limit kosha can see without your keys — at a stable URL:

curl -sL https://github.com/sriinnu/kosha-discovery/releases/download/snapshot-latest/kosha-latest.json \
  | jq '.modelCount, .providerCount'

It is a release asset rather than a file in the repository: at ~2.8 MB growing with every provider added, committing it weekly would put roughly 150 MB of already-stale data a year into a repo people are meant to clone. Dated snapshot-YYYY-MM-DD pre-releases keep a short trail for diffing, pruned to the two most recent, and an older one is only removed once a newer one exists.

HTTP API

GET  /api/models?provider=&originProvider=&mode=&capability=
GET  /api/models/:idOrAlias             GET  /api/models/:idOrAlias/routes
GET  /api/models/cheapest?role=…        GET  /api/capabilities
GET  /api/providers[/:id]               GET  /api/roles
GET  /api/resolve/:alias                GET  /api/discovery-errors
GET  /api/discovery[/delta|/watch|/cheapest|/binding]   (stable v1 contract)
POST /api/refresh                       GET  /health          GET  /metrics
GET  /proxy/v1/models                   POST /proxy/v1/chat/completions

Parameters and response shapes: docs/api.md.

Proxy

Shortened. The full README is on GitHub.