mcp-nexus

English | 中文

mcp-nexus is a robust, multi-provider Model Context Protocol (MCP) server that acts as a bridge for both Tavily and Brave Search APIs. It provides a unified tool surface, rotating across a pool of upstream API keys, all managed through 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.

Related MCP server: MCP Nexus - Cloudflare Workers

Quickstart (Local)

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