TavilyProxyManager: Aggregated Reverse Proxy Tool for Managing Multiple Tavily Proxy Pool Account API Quotas

The TavilyProxyManager is a program for the Tavily Tavily API is an open source transparent reverse proxy system designed by Tavily API. Its core function is to developers in the hands of multiple Tavily API key (Key) unified convergence to a proxy pool, only a custom Master Key exposed to the outside for security authentication. Through this multi-account pooling management mechanism, the system is able to intelligently monitor the remaining quota of each key and automatically allocate the calling task, effectively solving the problem of limited calling of a single free account interface, low concurrency frequency (Rate Limit) and quota fragmentation.

In addition to the basic proxy forwarding functions, the system also has a built-in visual Web management panel based on Vue 3, which allows users to add/remove API keys at any time, synchronize the remaining quota of all accounts with one click, and support graphical presentation of the historical call volume and quota consumption trends. Due to the completely transparent proxy strategy, TavilyProxyManager is compatible with all request paths and parameters of the original official interface. For the AI-assisted development ecosystem, the system natively provides HTTP MCP (Model Context Protocol) endpoints for seamless out-of-the-box access. Claude The project adopts a lightweight Go language single-file compilation architecture with a Docker containerization solution to accomplish rapid deployment with minimal resource consumption. The project adopts a lightweight Go language single-file compilation architecture with Docker containerization scheme, which can complete rapid deployment under the premise of extremely low resource consumption.

Function List

• Intelligent key pool concurrent schedulingTavily API Key: Integrate multiple Tavily API Keys entered and automatically determine the remaining quota of each key. Priority is given to calling keys with sufficient quota, and a random dispersion strategy is adopted for keys with the same quota, which significantly reduces the pressure of concurrent access to a single key and avoids the 429 request overrun error.
• Automatic Fault Interception and Seamless HandoverThe request disaster recovery mechanism is set up so that when a call to the downstream encounters an official exception status code such as 401 (unauthorized), 429 (too frequent request), 432/433, etc., the proxy layer will automatically intercept the error report and silently switch the request to the next healthy alternate key for retrying.
• Web Visualization Centralized Management Panel: Embedded with a complete GUI console (Vite + Vue 3), it provides the functions of adding, deleting, modifying, and batch synchronizing the latest quota information of multiple accounts, and at the same time, it uses a trend chart to show the consumption of request volume and the overall operation status.
• Global request log auditingReal-time logging of every search request and response details (including status code, consumption amount, time consumed, etc.) forwarded by the agent. Support the use of conditional filtering search history log , and comes with a long-lasting storage of manual and automatic cleanup mechanism .
• Native HTTP MCP endpoint support:: Complies with Model Context Protocol Specification, system built-in /mcp Endpoint services and support for both stateful and stateless operation modes, greatly reducing the threshold for configuring network search capabilities for AI intelligences (Agents) and editors.
• Master Key Unified Access Authentication: The client and business code don't need to care how many Tavily accounts are connected at the bottom, they just replace the API domain name with the proxy address and initiate a standard Authorization: Bearer Authentication can be invoked.
• Periodic automated O&M tasksThe background timing script will automatically trigger the quota reset logic on the 1st of each month, and at the same time, it can automatically clear the expired and discarded log data, so that the whole process can be operated stably for a long time without human intervention.
• Extreme lightweight deploymentThe back-end (Go 1.23+) and front-end static resources are compiled and bundled into a single, extremely compact binary executable that supports all major architectural platforms, and combined with Docker Compose, it can be pulled up and ready to use with a single click.

Using Help

🛠️ TavilyProxyManager Detailed Installation and Usage Guide

In order to enable users to smoothly manage and use multiple Tavily API quotas, this guide will explain in detail everything from setting up the Docker environment, configuration file settings, panel management to API and MCP Complete operational procedures for client docking.

I. Recommended Installation: Docker Compose-based Environment Deployment

Since the project uses an architecture that packages the front-end and back-end into a single binary file, using Docker containerized deployment is the most efficient way to avoid contamination of the host environment. Make sure you have Docker and the Docker Compose plugin installed on your server.

1. Establishment of project catalogs and configuration files
Create a new folder in the server terminal and create a directory in that directory named docker-compose.yml of the orchestration file:

mkdir tavily-proxy && cd tavily-proxy
touch docker-compose.yml

2. Preparation of configuration parameters
Open with a text editor docker-compose.yml, fill in the following and save:

version: "3.8"
services:
tavily-proxy:
image: ghcr.io/xuncv/tavilyproxymanager:latest
container_name: tavily-proxy
ports:
- "8080:8080"
environment:
# 代理服务内部监听地址与端口
- LISTEN_ADDR=:8080
# 设定内置 SQLite 数据库的存储路径
- DATABASE_PATH=/app/data/proxy.db
# 上游 Tavily 官方 API 基准地址
- TAVILY_BASE_URL=https://api.tavily.com
# 请求超时断开时间
- UPSTREAM_TIMEOUT=30s
# MCP 模式，默认 true 代表无状态模式，防止客户端报会话丢失
- MCP_STATELESS=true
volumes:
# 将宿主机的 data 目录映射给容器，持久化存储数据库
- ./data:/app/data
# 映射系统时间以保障日志时区正确
- /etc/localtime:/etc/localtime:ro
restart: unless-stopped

3. Start and pull the mirror service
Run the following command to start the container. The system will automatically fetch the latest version of the image from the Github Container Registry.

docker-compose up -d

Obtaining Core Credentials: Generating a Master Key

TavilyProxyManager enforces the use of the Master Key system to ensure that the service is not abused. In the case of the serviceinitializationIf the database is empty, the system will automatically generate a high-strength random Master Key.

Please obtain this initial admin password by querying the container log:

docker logs tavily-proxy 2>&1 | grep "master key"

Sample terminal output:

level=INFO msg="no master key found, generated a new one" key=sk_master_xxxxxx

⚠️ Important Notes: Please immediately transfer this paragraph to the key= This string is saved to your password manager. This password is both the unique password for logging into the web monitoring panel and the Bearer Token that is carried in the headers of subsequent API requests.

Basic operation of the Web visualization panel

1. Login system: Access your server IP in a browser or a bound domain name (e.g. http://<服务器IP>:8080 ). Enter the Master Key you just intercepted at the login screen to access the console.
2. Adding an Agent Key Pool：
   • After logging in, navigate to the Key Management module.
   • Click “Add Key” to paste multiple Tavily free or paid API Keys that you have registered for into the system one by one.
   • After the entry is completed, it is recommended to click the “Synchronize Quota” button, the system will be sent to the official verification of the validity of all the Keys, and will refresh the [current remaining calling quota] to the list.
3. Monitor usageThe Dashboard provides an intuitive view of request frequency histograms and system success rates, while the Logs page retains the specific time consumption and hit status of each search command, making it easy to perform request troubleshooting and auditing.

Code Access Guidelines: REST API Transparent Proxy Mode

The system's exposed interface specification is consistent with Tavily's official document 100%, which means that existing open source projects can be migrated at zero cost.

Core Change Points:

• The URL of the original request is changed from https://api.tavily.com Replace with the address of your deployment http://<服务器IP>:8080
• The authentication information is replaced with the Master Key

CURL test sample code:

curl -X POST "http://<服务器IP>:8080/search" \
-H "Authorization: Bearer <您的_MASTER_KEY>" \
-H "Content-Type: application/json" \
-d '{"query": "2026年最新AI模型架构解析", "search_depth": "basic"}'

Note: The system is fully compatible with many older versions of passing parameters, whether you pass them inside the Payload body or inside the {"api_key": "<MASTER_KEY>"} or spliced at the end of the URL ?api_key=<MASTER_KEY> All can be recognized correctly.

V. Advanced Integration: MCP (Model Context Protocol) Protocol Access

A large number of new AI productivity tools (e.g., the Claude Desktop app, VS Code in the Cline plugins, etc.) are based on the MCP protocol to extend the tool invocation capabilities. This agent integrates natively with this endpoint.

VS Code Configuration Modification Example (used in conjunction with mcp-remote):
Add the following Server node to your VS Code MCP profile:

{
"servers": {
"tavily-proxy": {
"command": "npx",
"args":[
"-y",
"mcp-remote",
"http://<您的服务器IP>:8080/mcp",
"--header",
"Authorization: Bearer <您的_MASTER_KEY>"
]
}
}
}

Principle of operation: enabled by default MCP_STATELESS=true The environment variable is intended to allow the proxy to maintain a stateless connection. Because the MCP protocol is meant to maintain a constant SSE / WebSocket state, cross-network and reverse proxy forwarding can easily lead to session ID disconnections that result in errors session not foundIn stateless mode, each command is invoked independently. In stateless mode, each instruction is invoked independently, guaranteeing the ultimate stability of AI tools over long connections.

application scenario

1. AI application R&D team quota pooling management
   When a small R&D team builds an Agent workflow that relies heavily on search engines, the quota in the official free version of Tavily is not enough to support the debugging frequency. Developers can register multiple test accounts to get the key and inject it into the system, aggregating the fragmented quota into a massive quota pool without modifying the underlying business code in the middle of the process.
2. Anti-blocking and Retry Strategies for Highly Concurrent Business Scenarios
   When crawling search results in large batches, or experiencing sudden high traffic calls to the search capability, a single Tavily Key is prone to hitting the Rate Limit, causing 429 errors to interrupt the process. Deploying the system as a relay layer minimizes concurrent blocking and task failures by relying on its smooth random-dispersion algorithm and automatic failover switching to compensate for errors.
3. Immersive AI-assisted programming eco-integration
   The developer uses the IDE locally (e.g. Cursor, When writing code that needs to incorporate the latest Internet documentation with an AI coding assistant (VS Code, VS Code), simply register the TavilyProxyManager address with the IDE using the MCP node, after which the AI model will autonomously carry out the retrieval operation, and the developer will be able to clearly review whether the AI is over-consuming the API through the web panel, enhancing billing transparency.
4. Enterprise-level shared call interface audit monitoring
   The enterprise intranet uniformly provides a master key for developers in each department to use. IT administrators monitor the usage statistics and log data in the background to locate the server-side scripts with abnormal calls in a dead loop, and at the same time, automatically execute the monthly quota re-estimation to meet the needs of enterprise-wide asset reuse and internal control.

QA

1. Since Tavily officially upgrades the interface frequently (e.g. adding advanced search parameters), will the proxy tool report errors due to incompatibility?
   A: There is no incompatibility. The system adopts the proxy philosophy of “transparent and non-destructive transmission”, and the code layer only intervenes in the Authorization header and proxy distribution logic. Specific URL paths sent by business requests and any custom parameters in the request body are routed to the official API without any changes, so it has immunity and full compatibility with upstream upgrades.
2. I can't find the originally generated Master Key through the terminal, what should I do and can the panel still be logged in?
   A: The initial Master Key is the only super credential for the survival of the service. If the console logs have been overwritten on a rolling basis, you can set the master key that is mapped to the host's /data/proxy.db（Download the SQLite database file locally and use a tool such as SQLiteStudio to open it and review the settings table to retrieve or change it to your own customized ciphertext password.
3. Why does MCP access occasionally fail or disconnect frequently?
   A: This is usually caused by network fluctuations that cause stateful connection interruptions. It is recommended to first confirm docker-compose.yml environment variable in the MCP_STATELESS=true If you have an additional layer of self-built gateway services such as Nginx/Caddy nested in front of the proxy container, make sure that the gateway does not intercept specific request headers and does not brute-force buffer truncate the SSE response format.
4. How is the polling strategy handled for different Keys with the same remaining amount?
   A: If the system determines that multiple available Keys have the same maximum value, it will skip the simple sequential allocation and use the underlying Random Shuffle algorithm for dispatching. This maximizes the avoidance of request fixed routing in the first few Key and thus a single point of contact with the official concurrency per second control (QPS threshold).