🔍 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:

1. Clone the repository:

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

2. Install dependencies:

bun install

3. Build the server:

bun run build

4. 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

5. 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

• Bug Reports
• Feature Requests
• Ask Questions

💬 Join Community

• GitHub Discussions
• Code of Conduct
• Roadmap & Project Board

🌟 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