Un servidor de Protocolo de Contexto de Modelo (MCP) que se integra perfectamente con el diverso ecosistema de modelos de OpenRouter.ai. Acceda a diversos modelos de IA a través de una interfaz unificada con seguridad de tipos, almacenamiento en caché integrado, limitación de velocidad y gestión de errores.
Acceso al modelo
Acceso directo a todos los modelos de OpenRouter.ai
Validación automática de modelos y verificación de capacidad
Compatibilidad con la configuración del modelo predeterminado
Optimización del rendimiento
Almacenamiento en caché de información del modelo inteligente (expiración de 1 hora)
Gestión automática del límite de velocidad
Retroceso exponencial para solicitudes fallidas
Formato de respuesta unificado
Estructura ToolResult consistente para todas las respuestas
Identificación clara de errores con el indicador isError
Mensajes de error estructurados con contexto
Related MCP server: OpenRouter MCP Multimodal Server
pnpm install @mcpservers/openrouteraiObtenga su clave API de OpenRouter de OpenRouter Keys
Elija un modelo predeterminado (opcional)
OPENROUTER_API_KEY=your-api-key-here
OPENROUTER_DEFAULT_MODEL=optional-default-modelAgregue a su archivo de configuración de MCP ( cline_mcp_settings.json o claude_desktop_config.json ):
{
"mcpServers": {
"openrouterai": {
"command": "npx",
"args": ["@mcpservers/openrouterai"],
"env": {
"OPENROUTER_API_KEY": "your-api-key-here",
"OPENROUTER_DEFAULT_MODEL": "optional-default-model"
}
}
}
}Todas las herramientas devuelven respuestas en una estructura estandarizada:
interface ToolResult {
isError: boolean;
content: Array<{
type: "text";
text: string; // JSON string or error message
}>;
}Ejemplo de éxito:
{
"isError": false,
"content": [{
"type": "text",
"text": "{\"id\": \"gen-123\", ...}"
}]
}Ejemplo de error:
{
"isError": true,
"content": [{
"type": "text",
"text": "Error: Model validation failed - 'invalid-model' not found"
}]
}Enviar mensajes a los modelos de OpenRouter.ai:
interface ChatCompletionRequest {
model?: string;
messages: Array<{role: "user"|"system"|"assistant", content: string}>;
temperature?: number; // 0-2
}
// Response: ToolResult with chat completion data or errorBusca y filtra los modelos disponibles:
interface ModelSearchRequest {
query?: string;
provider?: string;
minContextLength?: number;
capabilities?: {
functions?: boolean;
vision?: boolean;
};
}
// Response: ToolResult with model list or errorObtenga información detallada sobre un modelo específico:
{
model: string; // Model identifier
}Compruebe si un ID de modelo es válido:
interface ModelValidationRequest {
model: string;
}
// Response:
// Success: { isError: false, valid: true }
// Error: { isError: true, error: "Model not found" }El servidor proporciona errores estructurados con información contextual:
// Error response structure
{
isError: true,
content: [{
type: "text",
text: "Error: [Category] - Detailed message"
}]
}Categorías de errores comunes:
Validation Error : parámetros de entrada no válidos
API Error : Problemas de comunicación de la API de OpenRouter
Rate Limit : detección de limitación de solicitudes
Internal Error : errores de procesamiento del lado del servidor
Manejo de respuestas:
async function handleResponse(result: ToolResult) {
if (result.isError) {
const errorMessage = result.content[0].text;
if (errorMessage.startsWith('Error: Rate Limit')) {
// Handle rate limiting
}
// Other error handling
} else {
const data = JSON.parse(result.content[0].text);
// Process successful response
}
}Consulte CONTRIBUTING.md para obtener información detallada sobre:
Configuración de desarrollo
Estructura del proyecto
Implementación de funciones
Pautas de manejo de errores
Ejemplos de uso de herramientas
# Install dependencies
pnpm install
# Build project
pnpm run build
# Run tests
pnpm testConsulte CHANGELOG.md para obtener actualizaciones recientes, incluidas:
Implementación del formato de respuesta unificado
Sistema mejorado de gestión de errores
Mejoras en la interfaz de tipos seguros
Este proyecto está licenciado bajo la Licencia Apache 2.0: consulte el archivo de LICENCIA para obtener más detalles.
Sends conversational context (messages) to OpenRouter.ai for completion using a specified model. Use this for dialogue, text generation, or instruction-following tasks. Supports advanced provider routing and parameter overrides. Returns the generated text response.
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | (Optional) The specific OpenRouter model ID (e.g., "google/gemini-pro") to use for this completion request. If omitted, the server's configured default model will be used. | |
| messages | Yes | (Required) An ordered array of message objects representing the conversation history. Each object must include `role` ("system", "user", or "assistant") and `content` (the text of the message). Minimum 1 message, maximum 100. | |
| provider | No | (Optional) An object allowing fine-grained control over how OpenRouter selects the underlying AI provider for this request, overriding any server-level defaults. | |
| max_tokens | No | (Optional) Sets an upper limit on the number of tokens generated in the response. Overrides the server default if specified. Influences provider routing based on model context limits. | |
| temperature | No | (Optional) Controls the randomness of the generated output. Ranges from 0.0 (deterministic) to 2.0 (highly random). Affects creativity versus coherence. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions 'advanced provider routing and parameter overrides' and that it returns a 'generated text response', but does not disclose important behaviors such as authentication requirements, rate limits, what happens on failure, or whether the request is destructive. The description is adequate but not comprehensive for an unannotated tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loaded with the primary action, and contains no filler. Every sentence adds meaningful information: action, use cases, and key features.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description mentions returning 'the generated text response' but does not specify the exact output structure (e.g., whether it's a raw string or an object with choices). With no output schema, more detail would be helpful. It covers the main purpose and parameters adequately but lacks detail on error handling or response format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds context like 'advanced provider routing and parameter overrides' which connects to the provider parameter, but does not elaborate on the semantics of individual parameters beyond what the schema already provides. The description adds marginal value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that it sends conversational messages to OpenRouter.ai for completion using a specified model, explicitly listing use cases like dialogue, text generation, and instruction-following. This effectively distinguishes it from sibling tools (get_model_info, search_models, validate_model) which are about model metadata, not generating completions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells when to use the tool ('for dialogue, text generation, or instruction-following tasks') but does not explicitly state when not to use it or provide alternatives. Given the sibling tools are unrelated, the guidance is clear enough but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieves the complete metadata for a single OpenRouter.ai model specified by its unique ID. Use this when you know the model ID and need its full details (pricing, context limits, capabilities, etc.). Returns a model information object.
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | (Required) The unique identifier string of the OpenRouter.ai model whose details are being requested. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description adequately discloses the read-only nature and the type of information returned (pricing, limits, capabilities). However, it does not discuss rate limits or authentication requirements, which are acceptable for a simple retrieval tool without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states the action and resource, second provides usage guidance and output description. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool with no output schema, the description covers what the tool does, when to use it, and what it returns. It is complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description's mention of 'unique ID' mirrors the schema description. No additional semantics are added beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves complete metadata for a single model by ID, distinguishing it from siblings like search_models (which likely doesn't require exact ID) and chat_completion (generates completions).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using the tool when the model ID is known and full details are needed, but does not mention when not to use or name alternatives directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Queries the OpenRouter.ai model registry, filtering by various criteria like capabilities, pricing, or provider. Use this to discover models suitable for specific needs. Returns a list of matching model metadata objects.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | (Optional) Limits the number of matching models returned in the response. Must be between 1 and 50. Defaults to 10. | |
| query | No | (Optional) A text query string to search within model names, descriptions, and provider details. | |
| provider | No | (Optional) Restricts the search to models offered by a specific provider ID (e.g., "openai", "anthropic"). | |
| capabilities | No | (Optional) An object specifying required model capabilities. | |
| maxPromptPrice | No | (Optional) Filters for models whose price for processing 1,000 prompt tokens is less than or equal to this value. | |
| maxContextLength | No | (Optional) Filters for models that support at most the specified context window size (in tokens). | |
| minContextLength | No | (Optional) Filters for models that support at least the specified context window size (in tokens). | |
| maxCompletionPrice | No | (Optional) Filters for models whose price for generating 1,000 completion tokens is less than or equal to this value. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It describes a query operation returning metadata, which implies non-destructive behavior, but it doesn't specify authentication, rate limits, or potential side effects. Adequate but minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the main action and filtering intent. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description at least states the return type (list of metadata objects). All 8 parameters have schema descriptions, and the description covers the core use case. Lacks mention of pagination or ordering, but the limit parameter mitigates this slightly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed parameter descriptions. The description adds high-level purpose ('filtering by various criteria') but does not introduce meaning beyond what the schema already provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it queries the model registry with filtering, and differentiates from siblings like chat_completion (generation) and get_model_info (single model details). The phrase 'Use this to discover models' directly indicates purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this to discover models suitable for specific needs.' While it doesn't list when not to use or alternatives, the sibling context provides differentiation, making usage guidance clear if not exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verifies if a given model ID exists within the OpenRouter.ai registry. Use this for a quick check of model ID validity before making other API calls. Returns a boolean value (true if valid, false otherwise).
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | (Required) The unique identifier string of the OpenRouter.ai model to check for validity. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool returns a boolean ('true if valid, false otherwise') and the action is a read-only existence check. No contradictions or hidden behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences with no extraneous information. The key information (verb, resource, when to use, return value) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, boolean return), the description is nearly complete. It lacks details on error states or network requirements, but these are minor for a simple existence check.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'model'. The description adds little beyond the schema—it restates the purpose but doesn't provide additional format or usage details. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Verifies' and resource 'model ID exists within OpenRouter registry', clearly distinguishing from sibling tools like get_model_info (which likely returns details) and search_models (which is for searching).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Use this for a quick check of model ID validity before making other API calls.' This tells when to use it, though it doesn't explicitly state alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.1chat_completionget_model_infosearch_modelsvalidate_modelScored across 4 tools
All four tools serve clearly distinct purposes: chat_completion generates text, get_model_info retrieves details for a specific model, search_models filters models by criteria, and validate_model checks model existence. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern (chat_completion, get_model_info, search_models, validate_model) using snake_case. This makes the API predictable and easy to use.
With 4 tools, the set is well-scoped for OpenRouter's purpose: one core action (chat), two for model discovery (get and search), and one for validation. No bloat or deficiency.
The tool set covers the essential workflows: chatting, retrieving model metadata, searching for models, and verifying model existence. No critical missing functionality for typical use.
OpenRouter for tools and data. Compare catalog providers and call them from one hosted MCP endpoint.
AI model routing on your own vendor keys: pick the best model per prompt, or route and run it.
The OpenRouter MCP server plugs OpenRouter into the AI tools you already use. Once connected, your assistant can pull live OpenRouter data (models, prices, your credits, rankings, and docs) and send quick test messages, all without leaving your editor.
