mcp-nexus

English | 中文

mcp-nexus is a robust, multi-provider Model Context Protocol (MCP) server that acts as a bridge for Tavily, Brave Search, and GrokSearch APIs. It provides a unified tool surface, rotating across pools of upstream API keys, all managed through a comprehensive Admin UI.

Features

• Unified Search APIs: Exposes Tavily, Brave, and GrokSearch tools through a single MCP endpoint.
• API Key Management: Easily add, manage, and rotate multiple Tavily, Brave, and Grok 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 source mode (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.

Quickstart (Local)

Docker Compose (recommended)

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

PostgreSQL data is stored in the Docker volume mounted at /var/lib/postgresql/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
npm run db:bootstrap
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 upstream Tavily, Brave, and Grok API keys. You can add, remove, update key status (active/disabled/cooldown/invalid), and monitor Tavily credits.
• 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.

GrokSearch Configuration

Grok tools are feature-flagged and can be controlled in Admin UI → Settings.

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", "@mcp-nexus/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.