Context7 Account Broker

License: MIT

A drop-in Context7 MCP proxy for people who use more than one authorized APIkey. It balances requests by quota usage, keeps each library on the same account,and caches successful responses on disk.

OpenCode sees the standard Context7 tools:

resolve-library-id
query-docs

The broker handles account selection, failover, caching, and quota refresheswithout changing tool schemas or results.

What it does

Routes new work to the account with the lowest proportional quota usage.
Keeps a library on the same account within each project.
Fails over when an account is blocked, rate limited, unauthorized, ortemporarily unreachable.
Reads Context7's RateLimit-* headers instead of estimating quota locally.
Caches exact successful calls for 30 days by default.
Coalesces concurrent identical requests into one upstream call.
Stores named credentials in a private 0600 configuration file.
Provides CLI commands for account management, quota status, and diagnostics.

Quick start

1. Add your Context7 accounts

The command prompts for the API key without displaying it:

npm_config_allow_git=all npx -y \
  git+https://github.com/mirsella/context7-account-broker.git \
  accounts add personal

Repeat the command with a different name for each account. To verify the savedaccounts without exposing their keys:

npm_config_allow_git=all npx -y \
  git+https://github.com/mirsella/context7-account-broker.git \
  accounts list

2. Configure OpenCode

Add the server to ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "context7": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "git+https://github.com/mirsella/context7-account-broker.git"
      ],
      "environment": {
        "npm_config_allow_git": "all"
      },
      "timeout": 30000,
      "enabled": true
    }
  }
}

Restart OpenCode, then check the connection:

opencode mcp list

npm_config_allow_git=all is required by npm 12, which blocks Git packagesources by default. It permits the GitHub package used by this MCP entry.

CLI

The examples below use the GitHub version directly.

Command	Purpose
`accounts add [name]`	Add a named API key using a hidden prompt or stdin
`accounts list`	List account names, sources, and key fingerprints
`accounts remove <name>`	Remove a file-configured account
`status`	Fetch current quota usage and reset times
`config`	Print effective paths and runtime settings
`help`	Show command help
`serve`	Start the stdio MCP server (the default)

For example:

REPO=git+https://github.com/mirsella/context7-account-broker.git

npm_config_allow_git=all npx -y "$REPO" status
npm_config_allow_git=all npx -y "$REPO" config
npm_config_allow_git=all npx -y "$REPO" accounts remove personal

For non-interactive account setup:

printf '%s\n' "$CONTEXT7_API_KEY" |
  npm_config_allow_git=all npx -y "$REPO" accounts add personal

Account selection

At startup, the broker probes each key and reads Context7's authoritativeRateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers.

For a library without an existing assignment, it chooses the available accountwith the lowest proportional usage:

used / limit = (limit - remaining) / limit

Equal accounts rotate in round-robin order. Once selected, the account is savedas the preferred account for that library and project. A temporary failure canmove one request elsewhere without discarding the preference.

Blocked accounts are checked again at their reset time. Free-plan accounts arealso checked at the next UTC day so Context7's daily bonus calls can becomeavailable.

Cache

Successful tool results are cached by:

project scope
tool name
canonicalized arguments
API-key hash

The API-key partition prevents a removed account from serving its cached privatecontent. Expired files are removed on startup and lazily when read. Concurrentidentical calls share one in-flight request.

The default cache directory is:

~/.cache/context7-account-broker

Delete that directory to invalidate all cached results and affinities.

Credentials

Named accounts are stored at:

~/.config/context7-account-broker/accounts.json

The directory uses mode 0700 and the file uses mode 0600.

When this file contains accounts, it acts as an allowlist. InheritedCONTEXT7_API_KEY and CONTEXT7_API_KEYS values are ignored unlessCONTEXT7_BROKER_INCLUDE_ENV=1 is set. This prevents an unrelated shell key fromsilently joining a configured pool.

With no configured account file, the broker accepts:

export CONTEXT7_API_KEYS='ctx7sk_first,ctx7sk_second'

Configuration

Environment variable	Default	Description
`CONTEXT7_API_KEY`	unset	One API key when no account file is configured
`CONTEXT7_API_KEYS`	unset	Separated API keys
`CONTEXT7_BROKER_CONFIG`	XDG config path	Override the accounts file path
`CONTEXT7_BROKER_INCLUDE_ENV`	unset	Include environment keys with `1`
`CONTEXT7_MCP_URL`	`https://mcp.context7.com/mcp`	Upstream MCP endpoint
`CONTEXT7_ACCOUNT_COOLDOWN_MS`	`30000`	Transient failure cooldown
`CONTEXT7_CACHE_TTL_DAYS`	`30`	Result and affinity cache lifetime
`CONTEXT7_CACHE_DIR`	XDG cache path	Override the cache directory
`CONTEXT7_PROJECT_ID`	current directory	Cache and affinity scope

Quota cost

Context7 attaches quota state to normal API responses rather than exposing afree status endpoint. Each startup probe, refresh, and status check consumesone API request per checked account.

Development

Requirements: Node.js 20 or newer and pnpm.

git clone https://github.com/mirsella/context7-account-broker.git
cd context7-account-broker
pnpm install
pnpm typecheck
pnpm test
pnpm build

Run the local binary:

node dist/index.js accounts list
node dist/index.js status
node dist/index.js serve

Responsible use

Use API keys only for accounts you own or are authorized to aggregate. FollowContext7's terms and plan limits. The broker does not create accounts, bypassauthentication, or hide upstream failures.

License

MIT

Context7 Account Broker