🔍 Nexus MCP Server
AI integration without the complexity
Intelligent AI model search and discovery with zero-install simplicity
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
npxwith 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
- NPX-based execution with zero local installation
- Cross-platform compatibility (macOS, Linux, Windows)
- 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
- Node.js 18 or higher
- OpenRouter API key (register at openrouter.ai)
NPX Installation
Execute the server without local installation:
# Set your OpenRouter API key
export OPENROUTER_API_KEY=your-api-key-here
# Run the server via NPX
npx nexus-mcp
The server starts and listens for MCP client connections via STDIO transport.
Testing the NPX Installation
# Test the CLI help
npx nexus-mcp --help
# Test the version
npx nexus-mcp --version
# Run with your API key
OPENROUTER_API_KEY=your-key npx 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:
npm install
- Build the server:
npm 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:
npm start
Integration with MCP Clients
NPX-Based Integration (Recommended)
Configure MCP clients to execute the server via NPX:
Claude Code
Configuration in ~/.claude/mcp_settings.json:
{
"mcpServers": {
"nexus": {
"command": "npx",
"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:
npx - 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:
npx - Args:
["nexus-mcp"] - Environment:
OPENROUTER_API_KEY=your-api-key-here
Alternative: Local Installation
If you prefer using a local installation (after following the local development setup):
{
"mcpServers": {
"nexus": {
"command": "node",
"args": ["/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 keyNODE_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
NPX-Specific Issues
"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
NPX takes a long time to start
- This is normal on first run as NPX downloads the package
- 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_KEYenvironment 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 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
npm run dev
# Run tests
npm test
# Run tests with coverage
npm run test:coverage
# Lint code
npm run lint
# Format code
npm 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
|
🐛 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