MCP Integration

Connect any AI client that supports the Model Context Protocol (MCP) to this registry.

Endpoint

POST https://openrouter-registry-mcp.aroughidea.com/api/mcp

Production deployments use OAuth bearer tokens. Server-side clients can exchange MCP_CLIENT_ID and MCP_CLIENT_SECRET at /api/oauth/token; never expose those credentials in browser code.

Available Tools

list_models

List all models in the registry with optional filtering and sorting.

{ limit?: number, offset?: number, provider?: string, query?: string, sortBy?: string, sortDir?: "asc"|"desc", availableOnly?: boolean }

resolve_model

Resolve a model ID to its canonical form and fetch its details

{ input: string }

get_model

Get full details for a single model by canonical ID

{ id: string }

search_models

Search models by name, ID, or provider substring

{ query: string, limit?: number, offset?: number, sortBy?: string, sortDir?: "asc"|"desc" }

find_models_by_criteria

Filter models by budget, context, and modality constraints

{ maxInputPricePer1k?: number, maxOutputPricePer1k?: number, minContextLength?: number, modality?: string, limit?: number, offset?: number, sortBy?: string, sortDir?: "asc"|"desc" }

compare_models

Compare 2–5 models side-by-side on pricing, context length, and metadata

{ ids: string[] }

semantic_search

Find models by semantic similarity to a natural language description. Powered by openai/text-embedding-3-small via OpenRouter.

{ query: string, limit?: number, offset?: number }

get_registry_status

Get the current sync status of the model registry (last sync time, record count, errors)

{}

get_sync_history

Get the history of sync attempts (most recent first), including success/failure, record count, and any error messages

{ limit?: number }

Available Resources

Read registry data directly via MCP resource URIs (read-only, accessible via resources/read).

registry://models

Full list of models in the registry (up to 500)

registry://status

Current sync status (last sync time, record count, errors)

registry://models/{id}

Details for a specific model — URL-encode the canonical ID (e.g. registry://models/anthropic%2Fclaude-sonnet-4-5)

Available Prompts

Reusable prompt templates that guide model-selection and comparison workflows (accessible via prompts/get).

select_model

Generate a structured prompt to select the best model for a task

{ task_description: string, budget_usd_per_1k_tokens?: string, min_context_length?: string }

compare_models_prompt

Generate a structured prompt to compare a set of models side-by-side

{ model_ids: string }

Claude Desktop Configuration

Add this to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "openrouter-registry": {
      "url": "https://openrouter-registry-mcp.aroughidea.com/api/mcp",
      "transport": "streamable-http"
    }
  }
}

GitHub Copilot (VS Code)

Add to your workspace's .vscode/mcp.json (or under "mcp" in settings.json):

{
  "servers": {
    "openrouter-registry": {
      "type": "http",
      "url": "https://openrouter-registry-mcp.aroughidea.com/api/mcp"
    }
  }
}

If your client cannot complete OAuth discovery automatically, add a short-lived bearer token in a headers object as "Authorization": "Bearer YOUR_SHORT_LIVED_ACCESS_TOKEN".

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.openrouter-registry]
url = "https://openrouter-registry-mcp.aroughidea.com/api/mcp"

For authenticated deployments, add bearer_token = "YOUR_SHORT_LIVED_ACCESS_TOKEN" if your client does not perform OAuth discovery automatically.

Usage Examples

Resolve a model ID in your agent:

// In your agent/assistant:
const result = await mcp.callTool('resolve_model', { input: 'anthropic/claude-sonnet-4-5' });
// → { resolved: 'anthropic/claude-sonnet-4-5', source: 'canonical', found: true, model: {...} }

Search models by name or provider:

const results = await mcp.callTool('search_models', { query: 'claude', limit: 10 });

Find models by natural language description:

const results = await mcp.callTool('semantic_search', {
  query: 'fast cheap summarization model with large context',
  limit: 10,
});

Filter models by modality (e.g. vision models):

const models = await mcp.callTool('find_models_by_criteria', {
  modality: 'text+image',
  limit: 20,
});

Find models within a budget and context window:

const models = await mcp.callTool('find_models_by_criteria', {
  maxInputPricePer1k: 0.005,
  maxOutputPricePer1k: 0.015,
  minContextLength: 32000,
  limit: 20,
});

Compare models side-by-side:

const comparison = await mcp.callTool('compare_models', {
  ids: ['anthropic/claude-sonnet-4-5', 'openai/gpt-4o', 'google/gemini-pro-1.5'],
});

Read the model list as a resource:

const result = await mcp.readResource('registry://models');
// → { contents: [{ mimeType: 'application/json', text: '{"models":[...]}' }] }

Use the select_model prompt to guide model selection:

const prompt = await mcp.getPrompt('select_model', {
  task_description: 'Summarize long legal documents',
  budget_usd_per_1k_tokens: '0.005',
  min_context_length: '32000',
});
// → prompt messages that instruct the model how to pick the best option

Use the compare_models_prompt for a structured comparison:

const prompt = await mcp.getPrompt('compare_models_prompt', {
  model_ids: 'anthropic/claude-sonnet-4-5,openai/gpt-4o',
});

Cron Sync

The registry is automatically refreshed weekly via Vercel Cron:

// vercel.json
{
  "crons": [
    {
      "path": "/api/cron/sync",
      "schedule": "0 0 * * 0"
    }
  ]
}