Unified AI Gateway Client for Cursor (via MCP)

This implements a Model Context Protocol (MCP) adapter designed to interface with the comprehensive backend infrastructure provided by OpenRouter.ai, granting access to a vast selection of foundational models.

Prerequisites

• Runtime Environment: Requires Node.js version 18.0.0 or superior.
• Authentication: An active OpenRouter API Access Key is mandatory (obtainable from openrouter.ai/keys).

Core Capabilities

• Establishes MCP communication conduit to the OpenRouter endpoint.
• Provides abstraction over numerous generative models (e.g., models from Google, Meta, Anthropic, Mistral).
• Utilizes the standard MCP transport layer for interaction within supporting clients (like Cursor).
• Implements an internal cache mechanism for frequently requested model metadata, minimizing redundant external queries.
• Full compatibility with both complimentary (free-tier) and commercial (pay-per-use) AI offerings.
• Features utility functions for parallel or sequential multi-model response fusion.

Accessible Model Catalog

This client exposes the entirety of the OpenRouter catalog, including high-profile examples such as:

• Google Gemini 2.5 Pro
• DeepSeek Chat v3
• Meta Llama 3.1 Series
• DeepSeek R1
• Qwen Code Generation Models
• Mistral Small 3.1
• And numerous others.

Deployment Procedures

Automated Setup Script

The quickest path to operational readiness involves executing the bundled setup utility:

# Acquire the source repository
git clone https://your-repo-url/openrouter-mcp-client.git
cd openrouter-mcp-client

# Execute the configuration installer
node install.cjs

This script automates: 1. Generation of the required .env configuration file, prompting for your API key. 2. Installation of all necessary project dependencies. 3. Compilation of the source code. 4. Displaying subsequent operational instructions.

Manual Configuration

For environments where automated scripts are restricted:

# Clone the repository
git clone https://your-repo-url/openrouter-mcp-client.git
cd openrouter-mcp-client

# Install library dependencies
npm install

# Configure credentials by copying the template and editing
cp .env.example .env
# Manually populate .env with your OpenRouter API Key

# Compile the project artifacts
npm run build

Runtime Parameterization

Adjust critical operational settings within the .env file, specifically defining your access credential and the default engine for requests:

OPENROUTER_API_KEY=your_secret_key_here
OPENROUTER_DEFAULT_MODEL=google/gemini-2.5-pro-exp-03-25:free

Your key is secured at OpenRouter Keys Management.

Client Integration (Cursor Specific)

To activate this service within the Cursor IDE environment, the MCP configuration file must be modified:

1. Locate Cursor's configuration root:

   • Windows: %USERPROFILE%\.cursor\
   • Unix-like Systems (macOS/Linux): ~/.cursor/

2. Modify or create the mcp.json manifest. Introduce a new server entry:

{
  "mcpServers": {
    "custom-openrouter-client": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO/openrouter-mcp-client/dist/index.js"
      ],
      "env": {
        "OPENROUTER_API_KEY": "your_api_key_here",
        "OPENROUTER_DEFAULT_MODEL": "google/gemini-2.5-pro-exp-03-25:free"
      }
    }
  }
}

Note: Ensure ABSOLUTE_PATH_TO accurately points to your local directory structure.

1. Restart the Cursor application.

2. Activate the connection via the model selector interface (e.g., Ctrl+Shift+L or Cmd+Shift+L), selecting custom-openrouter-client.

Local Verification (Standalone Testing)

For direct validation of API connectivity, independent of the MCP layer, temporarily uncomment the following routines in src/index.ts:

// Uncomment to test the direct API
testDirectApi().catch(console.error);
testMultiModelCompletion().catch(console.error);

Then execute the primary execution script:

npm start

Development Workflow

To facilitate continuous integration and iterative changes:

# Activate file watching for automatic recompilation
npm run dev

Debugging Common Issues

Node.js Version Incompatibilities

Crucial Requirement: Node.js version 18.0.0 or newer is mandatory. Older installations may result in EBADENGINE errors or unpredictable behavior.

Verify your active version:

node --version

If outdated, procure the current Long-Term Support (LTS) release from nodejs.org.

Module System Conflicts (ESM vs. CJS)

• Source logic is written using ECMAScript Modules (ESM), as declared by "type": "module" in package.json.
• The bootstrap installer utilizes CommonJS syntax (hence the .cjs extension).
• Ensure the installation entry point is invoked correctly: node install.cjs.

Connection Failure in Cursor

If the IDE fails to establish communication:

1. Confirm the absolute path specified in mcp.json is correctly formatted (Unix-style forward slashes are preferred).
2. Verify that the latest build artifacts are present (npm run build executed).
3. Double-check the API key and model parameters in the environment settings.
4. Inspect the diagnostic output from Cursor itself for underlying runtime errors.

Supplementary References

• OpenRouter API Specifications
• Model Context Protocol (MCP) Specification
• Cursor IDE Platform

Smithery Deployment Pipeline

This service can be containerized and deployed via Smithery for broad accessibility across various agentic frameworks.

Prerequisites for Smithery Deployment

• Valid GitHub Account credentials.
• Your OpenRouter Authentication Token.

Deployment Sequence

1. Repository Forking: Create a personal fork of this source repository on GitHub.

2. Smithery Authentication: Log in to the Smithery Dashboard using your GitHub identity.

3. Server Registration:

   • Initiate the "Add Server" workflow.
   • Select the newly forked repository.
   • Verify build settings: Confirm the base directory is the root, and that the Dockerfile and smithery.yaml configurations are recognized.

4. Activation: Smithery will proceed with automated building and service deployment.

5. Post-Deployment Usage: Once live, consumers can integrate this hosted endpoint via the Smithery registry within their own MCP-compliant applications, supplying their unique OpenRouter API credentials during configuration.

Deployment Strategy Comparison

• Smithery Hosting: Optimal for dissemination; removes local setup burden from end-users.
• Local Execution: Preferred for active development, debugging, and localized testing; offers maximum environmental control.