MCP Nexus

🚀 mcp-nexus

mcp-nexus is a powerful, multi-provider Model Context Protocol (MCP) server that serves as a bridge for both Tavily and Brave Search APIs. It offers a unified tool interface, rotating through a pool of upstream API keys, all managed via a comprehensive Admin UI.

✨ Features

• Unified Search APIs: Exposes tools for both Tavily and Brave Search through a single MCP endpoint.
• API Key Management: Easily add, manage, and rotate multiple Tavily and Brave API keys to distribute load and handle rate limits.
• Client Authentication: Secure the MCP endpoint with bearer tokens that can be created and revoked via the Admin UI.
• Web Admin UI: A user-friendly interface to manage API keys, client tokens, view usage statistics, and configure server settings.
• Usage Monitoring: Track tool usage, inspect query history, and get summaries of your most used tools and queries.
• Flexible Search Strategy: Dynamically configure the search source (tavily_only, brave_only, combined, etc.) and key selection strategy (round_robin, random) without restarting the server.
• Rate Limiting: Built-in rate limiting for both MCP clients and upstream API calls to prevent abuse and manage costs.
• Flexible Deployment: Run locally with Node.js or deploy anywhere using the provided Docker Compose setup.

🚀 Quick Start

Local Quickstart

Docker Compose (recommended)

cp .env.example .env
# Edit .env to set your ADMIN_API_TOKEN and other configurations
docker compose up --build

SQLite data is stored in the Docker volume mounted at /data.

Then open:

• Admin UI: http://localhost:8787/admin
• MCP endpoint: http://localhost:8787/mcp

Local Node.js

Requires the env vars in .env.example to be set.

npm install
npx prisma migrate deploy --schema packages/db/prisma/schema.prisma
npm run dev:bridge-server

📚 Workspace

• packages/core: Core logic for Tavily/Brave clients, key management, and MCP tool schemas.
• packages/bridge-server: The main HTTP server, providing the MCP endpoint and the Admin API/UI.
• packages/bridge-stdio: A lightweight stdio server for local client integration.
• packages/stdio-http-bridge: A helper package to connect stdio clients to the HTTP server.
• packages/db: Prisma schema and database client for all data persistence.
• packages/admin-ui: The React-based Admin UI frontend.

📚 Admin UI

The Admin UI provides a central place to manage your mcp-nexus instance.

• Keys: Manage your pool of upstream Tavily and Brave API keys. You can add, remove, update the status (active, disabled), and monitor the remaining credits for Tavily keys.
• Tokens: Create and revoke client tokens used to authenticate with the MCP endpoint.
• Usage: View detailed tool usage statistics and query history, with options to filter by date range, tool, and client.
• Settings: Configure live server settings, such as the upstream key selection strategy and the search source mode.

💻 MCP Tools

The server exposes the following tools to MCP clients.

📚 Configuration

Configuration is managed via environment variables. Copy .env.example to .env to start.

Core Configuration

Rate Limiting

Search & Key Strategy

These settings can also be configured live in the Admin UI → Settings page.

Combined Mode

When SEARCH_SOURCE_MODE=combined:

• Requires active API keys for both Tavily and Brave Search
• Executes queries in parallel to minimize latency
• Merges and deduplicates results by URL
• Note: Each search request consumes quota from both providers (2x cost)
• Pagination: When offset>0, only Brave results are returned (Tavily doesn't support offset)

Tavily Configuration

Brave Configuration

If no Brave keys are configured, Brave tools will fall back to using Tavily.

📚 Connect an MCP client

1. Open the Admin UI and create a client token from the Tokens page.
2. Use that token to authenticate MCP requests by passing it as a bearer token in the Authorization header. Note this is different from the admin token used to access the Admin API itself.

HTTP

• MCP endpoint: POST /mcp
• Auth: Authorization: Bearer <client_token>

stdio

It is recommended to run a lightweight stdio wrapper via npx that connects to the HTTP MCP endpoint. This keeps secrets in env instead of CLI arguments.

Set TAVILY_BRIDGE_BASE_URL to your deployment URL (for local Docker Compose: http://localhost:8787).

{
  "mcpServers": {
    "mcp-nexus": {
      "command": "npx",
      "args": ["-y", "@nexus-mcp/stdio-http-bridge"],
      "env": {
        "TAVILY_BRIDGE_BASE_URL": "http://localhost:8787",
        "TAVILY_BRIDGE_MCP_TOKEN": "<client_token>"
      }
    }
  }
}

📚 Deployment

Cloudflare Workers (Recommended - Free)

One-click deployment to Cloudflare's free tier with D1 database. See packages/worker/README.md for details.

Docker Compose (Self-Hosted)

The included docker-compose.yml and Dockerfile provide a production-ready setup for self-hosting.

📚 Maintainers: Publishing @nexus-mcp/stdio-http-bridge

This repo is an npm workspaces monorepo. Only @nexus-mcp/stdio-http-bridge is intended to be published to npm.

Prereqs

• You must have npm publish permissions for the @nexus-mcp scope (or change the package name/scope).
• Login and verify:

npm login
npm whoami

Release (recommended: tag-triggered CI)

1. Bump the workspace version and create a tag:

npm version patch -w @nexus-mcp/stdio-http-bridge --tag-version-prefix stdio-http-bridge-v
git push --follow-tags

2. Configure GitHub Actions secret NPM_TOKEN (an npm access token with publish rights).
3. The workflow .github/workflows/publish-stdio-http-bridge.yml will publish on tags matching stdio-http-bridge-v*.

Release (manual)

npm publish -w @nexus-mcp/stdio-http-bridge