---

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

$3

- Zero-install deployment: Executable via 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

$3

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

$3

- 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)

$3

- 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

$3

- Node.js 18 or higher
- OpenRouter API key (register at openrouter.ai)

$3

Execute the server without local installation:

``bash


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.

$3

`bash


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:

1. Clone the repository:

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

2. Install dependencies:

`bash
npm install
`

3. Build the server:

`bash
npm run build
`

4. Configure your OpenRouter API key:

`bash


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:

`bash
npm start
`

Integration with MCP Clients

$3

Configure MCP clients to execute the server via NPX:

$3

Configuration in ~/.claude/mcp_settings.json:

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

Restart Claude Code after configuration changes.

$3

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.

$3

Standard MCP client connection parameters:

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

$3

If you prefer using a local installation (after following the local development setup):

`json
{
"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:

$3

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

$3

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

$3

`


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

$3

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

$3

- 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)

$3

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

$3

"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

$3

"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 Node.js 18+ is available in your MCP client's environment
- Ensure the API key is properly set in the environment variables

$3

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

$3

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:

`bash


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

🤝 Contributing

We welcome contributions from developers of all experience levels!

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

$3 - Bug Reports - Feature Requests - Ask Questions

$3 - GitHub Discussions - Code of Conduct - Roadmap & Project Board

$3

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

📄 License

MIT License - see LICENSE file for details.

---