🔍 Nexus MCP Server

AI integration without the complexity

Intelligent AI model search and discovery with zero-install simplicity

Quick Start • Features • Documentation • Contributing

What is Nexus?

Nexus is a Model Context Protocol (MCP) server that provides AI-powered search functionality through the OpenRouter API. It integrates with MCP-compatible clients including Claude Desktop and Cursor, providing search capabilities via multiple model families including Perplexity Sonar (real-time web search) and Grok 4 (training-data knowledge).

Key Characteristics

Zero-install deployment: Executable via bunx (or npx) with no build requirements
OpenRouter integration: Multiple AI models including Perplexity Sonar (web search) and Grok 4 (training data)
MCP protocol compliance: Implements standard MCP tool and resource interfaces
Production architecture: Includes request caching, deduplication, retry logic, and error handling
Type-safe implementation: Full TypeScript coverage with strict type checking

Features

Deployment

Bunx/NPX-based execution with zero local installation
Cross-platform compatibility (macOS, Linux, Windows)
Bun 1.0+ or Node.js 18+ runtime requirement
Automated version updates via npm registry

Search Capabilities

Multiple model tiers with different capabilities:
- sonar - Fast Q&A, real-time web search (30s timeout, standard tier)
- sonar-pro - Multi-step queries, real-time web search (60s timeout, premium tier)
- sonar-reasoning-pro - Chain-of-thought reasoning, real-time web search (120s timeout, premium tier)
- sonar-deep-research - Exhaustive research reports, real-time web search (300s timeout, premium tier)
- grok-4 - Training-data knowledge, no real-time search (60s timeout, premium tier)
Real-time web search with current information (Perplexity models)
Training-data knowledge responses (Grok 4)
Structured citation extraction from responses
Configurable model parameters (temperature, max tokens, timeout override)

Architecture

Comprehensive error handling with typed error classes
Request caching with configurable TTL
Request deduplication for concurrent identical queries
Automatic retry logic with exponential backoff
Winston-based structured logging
TypeScript strict mode implementation with full type coverage

Quick Start

Prerequisites

Bun 1.0+ (recommended) or Node.js 18+
OpenRouter API key (register at openrouter.ai)

Quick Install

Execute the server without local installation:

# Set your OpenRouter API key
export OPENROUTER_API_KEY=your-api-key-here

# Run the server via bunx (recommended)
bunx nexus-mcp

# Or via npx
npx nexus-mcp

The server starts and listens for MCP client connections via STDIO transport.

Testing the Installation

# Test the CLI help
bunx nexus-mcp --help

# Test the version
bunx nexus-mcp --version

# Run with your API key
OPENROUTER_API_KEY=your-key bunx nexus-mcp

Alternative: Local Development Installation

For local development or customization:

Clone the repository:

git clone https://github.com/adawalli/nexus.git
cd nexus

Install dependencies:

bun install

Build the server:

bun run build

Configure your OpenRouter API key:

# Copy the example environment file
cp .env.example .env

# Edit .env and add your actual API key
# OPENROUTER_API_KEY=your-api-key-here

Test the server:

bun run start

Integration with MCP Clients

Bunx-Based Integration (Recommended)

Configure MCP clients to execute the server via bunx:

Claude Code

Configuration in ~/.claude/mcp_settings.json:

{
  "mcpServers": {
    "nexus": {
      "command": "bunx",
      "args": ["nexus-mcp"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart Claude Code after configuration changes.

Cursor

Add server configuration in Cursor's MCP settings:

Name: nexus
Command: bunx
Args: ["nexus-mcp"]
Environment Variables: OPENROUTER_API_KEY=your-api-key-here

Restart Cursor after configuration changes.

Generic MCP Client Configuration

Standard MCP client connection parameters:

Transport: stdio
Command: bunx
Args: ["nexus-mcp"]
Environment: OPENROUTER_API_KEY=your-api-key-here

Alternative: npx or Local Installation

If you don't have Bun installed, use npx in place of bunx in any of the configurations above.

For a local installation (after following the local development setup):

{
  "mcpServers": {
    "nexus": {
      "command": "bun",
      "args": ["run", "/path/to/nexus-mcp/dist/cli.js"],
      "env": {
        "OPENROUTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Usage

Once integrated, you can use the search tool in your MCP client:

Basic Search

Use the search tool to find information about "latest developments in AI"

Advanced Search with Parameters

Search for "climate change solutions" using:
- Model: sonar-pro
- Max tokens: 2000
- Temperature: 0.3

Using Different Models

# Fast Q&A with real-time web search (default)
Search for "latest news" with model: sonar

# Deep research with comprehensive analysis
Search for "AI safety research" with model: sonar-deep-research

# Knowledge from training data (no web search)
Search for "explain quantum computing" with model: grok-4

Available Tools

`search`

The main search tool that provides AI-powered search capabilities.

Parameters:

query (required): Search query (1-2000 characters)
model (optional): Model to use (default: sonar)
- sonar - Fast Q&A with real-time web search (30s timeout)
- sonar-pro - Multi-step queries with real-time web search (60s timeout, premium)
- sonar-reasoning-pro - Chain-of-thought reasoning with real-time web search (120s timeout, premium)
- sonar-deep-research - Exhaustive research reports with real-time web search (300s timeout, premium)
- grok-4 - Training-data knowledge, no real-time search (60s timeout, premium)
maxTokens (optional): Maximum response tokens (1-4000, default: 1000)
temperature (optional): Response randomness (0-2, default: 0.3)
timeout (optional): Override default timeout in milliseconds (5000-600000)

Example Response (Perplexity model):

Based on current information, here are the latest developments in AI...

[Detailed AI-generated response with current information]

---
**Search Metadata:**
- Model: perplexity/sonar
- Response time: 1250ms
- Tokens used: 850
- Timeout: 30000ms
- Search type: realtime
- Sources: 5 found

Example Response (Grok 4 model):

Quantum computing is a type of computation that harnesses quantum mechanics...

[Response based on training data knowledge]

---
**Search Metadata:**
- Model: x-ai/grok-4
- Response time: 3500ms
- Tokens used: 650
- Timeout: 60000ms
- Search type: training-data
- Cost tier: premium

Configuration

Environment Variables

OPENROUTER_API_KEY (required): Your OpenRouter API key
NODE_ENV (optional): Environment setting (development, production, test)
LOG_LEVEL (optional): Logging level (debug, info, warn, error)

Advanced Configuration

The server supports additional configuration through environment variables:

OPENROUTER_TIMEOUT_MS: Request timeout in milliseconds (default: 30000)
OPENROUTER_MAX_RETRIES: Maximum retry attempts (default: 3)
OPENROUTER_BASE_URL: Custom OpenRouter API base URL

Resources

The server provides a configuration status resource at config://status that shows:

Server health status
Configuration information (with masked API key)
Search tool availability
Server uptime and version

Troubleshooting

Bunx/NPX-Specific Issues

"bunx: command not found"

Install Bun: curl -fsSL https://bun.sh/install | bash
Or fall back to npx if you have Node.js 18+ installed

"npx: command not found"

Ensure Node.js 18+ is installed: node --version
Update npm: npm install -g npm@latest

"Cannot find package 'nexus-mcp'"

The package may not be published yet. Use local installation instead
Verify network connectivity for npm registry access

Slow startup on first run

This is normal on first run as the package is downloaded
Subsequent runs will be faster due to caching
For faster startup, use local installation instead

"Permission denied" errors with npx

Try: npx --yes nexus-mcp --stdio
Or set npm permissions: npm config set user 0 && npm config set unsafe-perm true

Common Issues

"Search functionality is not available"

Ensure OPENROUTER_API_KEY environment variable is set
Verify your API key is valid at OpenRouter
Check the server logs for initialization errors

"Authentication failed: Invalid API key"

Double-check your API key format and validity
Ensure the key has sufficient credits/permissions
Test the key directly at OpenRouter dashboard

"Rate limit exceeded"

Wait for the rate limit to reset (usually 1 minute)
Consider upgrading your OpenRouter plan for higher limits
Monitor usage in your OpenRouter dashboard

Connection timeouts

Check your internet connection
The server will automatically retry failed requests
Increase timeout if needed: OPENROUTER_TIMEOUT_MS=60000

MCP client can't connect to server

Verify your MCP configuration uses the correct command and arguments
Check that Bun 1.0+ or Node.js 18+ is available in your MCP client's environment
Ensure the API key is properly set in the environment variables

Debug Logging

Enable debug logging by:

For local development: Add LOG_LEVEL=debug to your .env file

For MCP clients: Add LOG_LEVEL: "debug" to the env section of your MCP configuration

This will provide detailed information about:

Configuration loading
API requests and responses
Error details and stack traces
Performance metrics

Testing Connection

You can test if the server is working by checking the configuration status resource in your MCP client, or by running a simple search query.

Development

For developers working on this server:

# Development with hot reload
bun run dev

# Run tests
bun run test

# Run tests with coverage
bun run test:coverage

# Lint code
bun run lint

# Format code
bun run format

API Costs

OpenRouter charges for API usage based on token consumption:

Pricing: See current rates at OpenRouter Models
Monitoring: Usage tracking available in OpenRouter dashboard
Limits: Configure spending limits in OpenRouter account settings
Optimization: Server implements response caching and request deduplication to minimize redundant API calls

📚 Documentation

📖 Guide	🔗 Link	📝 Description
Quick Start	Getting Started	Zero-install setup in 30 seconds
API Reference	MCP Tools	Complete command reference
Configuration	Environment Setup	Advanced configuration options
Contributing	Contributing Guide	Join our open source community
Troubleshooting	Common Issues	Solutions to common problems

🤝 Contributing

We welcome contributions from developers of all experience levels!

🚀 Get Started

Fork the repository
Read our Contributing Guide
Check out good first issues

🐛 Report Issues

💬 Join Community

🌟 Recognition

Contributors are recognized in our:

Contributors list
Release notes for significant contributions
Community spotlights and testimonials

🔗 Related Projects

Model Context Protocol - The standard we implement
OpenRouter - Our AI model provider
Claude Desktop - Primary MCP client
Cursor - AI-powered code editor with MCP support

📞 Support & Community

💬 Need Help?	🔗 Resource
Quick Questions	GitHub Discussions
Bug Reports	GitHub Issues
Documentation	OpenRouter Docs • MCP Specification
Feature Requests	Enhancement Proposals

📄 License

MIT License - see LICENSE file for details.

Made with ❤️ by the open source community

⭐ Star us on GitHub • 📦 View on NPM • 📚 Read the Docs

Nexus: AI integration without the complexity

Nexus