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.

Tool Name	Provider	Description
tavily_search	Tavily	Search the web for current information on any topic. Use for news, facts, or data beyond your knowledge cutoff. Returns snippets and source URLs.
tavily_extract	Tavily	Extract content from URLs. Returns raw page content in markdown or text format.
tavily_crawl	Tavily	Crawl a website starting from a URL. Extracts content from pages with configurable depth and breadth.
tavily_map	Tavily	Map a website's structure. Returns a list of URLs found starting from the base URL.
tavily_research	Tavily	Perform comprehensive research on a given topic or question. Returns a detailed response based on research findings.
brave_web_search	Brave	Performs a web search using the Brave Search API. Use for general web searches for information, facts, and current topics. Returns a JSON array of results.
brave_local_search	Brave	Search for local businesses and places using the Brave Search API. Commonly falls back to web search if local results are unavailable. Returns a JSON array of results.
web_search	Grok	GrokSearch web search with optional supplemental sources (Tavily/Brave/Firecrawl) and canonical URL deduplication.
get_sources	Grok	Retrieves cached source entries from a previous web_search call via session_id.
web_fetch	Grok	Fetches page content with Tavily-first extraction and Firecrawl fallback.
web_map	Grok	Maps a target website with configurable depth/breadth/limit constraints.

Configuration

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

Core Configuration

Variable	Description	Default
DATABASE_URL	Connection string for the database. Node runtime now requires PostgreSQL semantics.	postgresql://mcp_nexus:mcp_nexus_dev@localhost:5432/mcp_nexus?schema=public
KEY_ENCRYPTION_SECRET	A 32-byte (256-bit) secret key used for encrypting and decrypting upstream API keys stored in the database.	(generated in example)
ADMIN_API_TOKEN	Bearer token for accessing the Admin API.	(generated in example)
HOST	The host address for the server to listen on.	0.0.0.0
PORT	The port for the server to listen on.	8787
ENABLE_QUERY_AUTH	If true, enables MCP client token authentication for the /mcp endpoint.	false

Rate Limiting

Variable	Description	Default
MCP_RATE_LIMIT_PER_MINUTE	Max requests per minute per client token.	60
MCP_GLOBAL_RATE_LIMIT_PER_MINUTE	Max requests per minute across all clients.	600
ADMIN_KEY_REVEAL_RATE_LIMIT_PER_MINUTE	Max key reveal attempts per minute in the Admin UI.	20
MCP_MAX_RETRIES	Maximum number of retries for failed upstream requests.	2
MCP_COOLDOWN_MS	Cooldown period in milliseconds for an upstream API key after a failure.	60000

Search & Key Strategy

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

Variable	Description	Default
SEARCH_SOURCE_MODE	Defines the search behavior: tavily_only, brave_only, combined (parallel query), or brave_prefer_tavily_fallback (Brave first, then Tavily on error). Note: Combined mode with offset>0 returns Brave-only results to avoid Tavily duplication.	brave_prefer_tavily_fallback
TAVILY_KEY_SELECTION_STRATEGY	Strategy for picking an upstream Tavily key when multiple are active: round_robin (default) or random.	round_robin

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

Variable	Description	Default
TAVILY_USAGE_LOG_MODE	Log level for Tavily tool usage: none, hash (query hash only), preview (redacted query), or full query.	preview
TAVILY_USAGE_HASH_SECRET	Optional secret for creating a keyed HMAC-SHA256 hash of queries instead of a plain SHA256. Recommended for privacy.	""
TAVILY_USAGE_SAMPLE_RATE	Optional sampling rate (0.0 to 1.0) for logging usage events. Empty string means log all events.	""
TAVILY_USAGE_RETENTION_DAYS	Optional retention period for usage logs. If set, old logs will be periodically cleaned up.	""
TAVILY_USAGE_CLEANUP_PROBABILITY	The probability (0.0 to 1.0) that a cleanup of old usage logs is triggered on a new usage event.	0.001
TAVILY_CREDITS_MIN_REMAINING	Credit threshold at which a Tavily key will be automatically put into cooldown status.	1
TAVILY_CREDITS_COOLDOWN_MS	Cooldown duration for a key that has fallen below the minimum credit threshold.	300000 (5m)
TAVILY_CREDITS_REFRESH_LOCK_MS	Lock duration to prevent concurrent credit refreshes for the same key.	15000
TAVILY_CREDITS_REFRESH_TIMEOUT_MS	Timeout for the upstream Tavily credits API request.	5000
TAVILY_CREDITS_CACHE_TTL_MS	Duration to cache Tavily credit information before it's considered stale.	60000

Brave Configuration

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

Variable	Description	Default
BRAVE_API_KEY	A Brave Search API key. If set, this single key will be used. For multi-key support, add keys via the Admin UI.	""
BRAVE_MAX_QPS	Max requests per second to the Brave API to stay within rate limits.	1
BRAVE_MIN_INTERVAL_MS	Overrides BRAVE_MAX_QPS with a fixed minimum interval between requests.	""
BRAVE_MAX_QUEUE_MS	Max time a request can wait in the queue before failing or falling back to Tavily.	30000
BRAVE_OVERFLOW	Behavior when the request queue is full: fallback_to_tavily (default), queue (wait), or error.	fallback_to_tavily
BRAVE_HTTP_TIMEOUT_MS	Per-request HTTP timeout for the Brave API.	20000

GrokSearch Configuration

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

Variable	Description	Default
GROK_SEARCH_ENABLED	Enables/disables Grok tool exposure (web_search, get_sources, web_fetch, web_map).	false
GROK_MODEL_DEFAULT	Default Grok model used by web_search when caller does not override model.	grok-4.2-beta
GROK_EXTRA_SOURCES_DEFAULT	Default extra supplemental source count for web_search.	0
GROK_SEARCH_SOURCE_MODE	Grok supplemental source mode: tavily_only, brave_only, combined, brave_prefer_tavily_fallback.	combined
GROK_KEY_SELECTION_STRATEGY	Grok key selection strategy: round_robin or random.	round_robin
GROK_API_URL	Optional Grok-compatible API base URL override.	https://api.x.ai/v1
GROK_TIMEOUT_MS	Timeout for Grok-side requests in milliseconds.	20000
GROK_USAGE_LOG_MODE	Grok usage logging mode: none, hash, preview, full.	preview
GROK_USAGE_HASH_SECRET	Optional secret for keyed query hashing in Grok usage telemetry.	""
GROK_USAGE_SAMPLE_RATE	Optional sample rate (0-1) for Grok usage telemetry.	""
FIRECRAWL_API_KEY	Optional Firecrawl API key used for supplemental source/fetch fallback.	""
FIRECRAWL_API_URL	Optional Firecrawl API base URL override.	https://api.firecrawl.dev/v1

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.