4q Tokenz

MCP Proxy Gateway

A context-aware MCP proxy that reduces token usage by exposing only 3 tools (mcp_search, mcp_call, mcp_schema) to LLMs instead of the full catalog.

Why This Exists

When you connect multiple MCP servers to an LLM, every tool from every server is listed in the LLM's context window. For a typical workspace with 50-100 tools across multiple MCP servers, that's thousands of tokens of schema documentation on every request.

MCP Proxy Gateway sits between your LLM and your MCP servers, offering:

• JIT tool loading — tools from upstream servers are discovered once at startup, then tools are called on-demand. Clients never see the full catalog.
• Intelligent search — fast lexical (BM25) search to find the right tool for a query. Tool tokens are pre-computed at startup for zero-overhead per-query scoring.
• Token savings — LLMs only see 3 tool schemas (search, call, schema) instead of 50+. Typical savings: 20-40% per turn for tool-heavy workflows.
• Zero native dependencies — pure JavaScript, no native modules, no model downloads, no supply chain risk from ML packages.

┌─────────────────────────────────────────────────────────────────┐

│ Your LLM │ │ (sees only: mcp_search, mcp_call, mcp_schema) │ └────────────────────┬────────────────────────────────────────────┘ │ ┌───────────▼──────────────┐ │ MCP Proxy Gateway │ │ ┌──────────────────────┐ │ │ │ Tool Registry │ │ │ │ (BM25 lexical) │ │ │ └──────────────────────┘ │ │ ┌──────────────────────┐ │ │ │ Connector Manager │ │ │ │ (Idle timeout reap) │ │ │ └──────────────────────┘ │ └────────────┬─────────────┘ │ ┌─────────────┼─────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │Google │ │MailerLite│ │Your Svc │ │Gmail │ │ Campaigns│ │ Custom │ │Calendar │ │ │ │ Tools │ │Drive │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘

Prerequisites

• Node.js 18+ with npm or pnpm
• One or more MCP servers to proxy (stdio or HTTP)

Installation

From Source

git clone https://github.com/steveweltman/4q-tokenz.git

cd 4q-tokenz

pnpm install pnpm build

Install to ~/.local/bin and configure

./install.sh

As a Dependency

npm install -g 4q-tokenz

Getting Started: Google Workspace Example

Here's a concrete walkthrough to connect Google Workspace (Gmail, Calendar, Drive) to your LLM through the proxy:

Step 1: Choose or Build an MCP Server for Google

You need an MCP server that wraps Google APIs. Options:

• @antidrift/mcp-google (recommended) — A collection of MCP server implementations for Google Workspace (Gmail, Calendar, Drive, Docs, Sheets). Works out of the box with this proxy.

  npm install @antidrift/mcp-google

or

npx @antidrift/mcp-google --help

• @modelcontextprotocol/server-gmail — Gmail-only, official MCP server
• Build your own — See the MCP spec to wrap your own APIs

Step 2: Set Up Google OAuth

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable these APIs:

• Gmail API
• Google Calendar API
• Google Drive API

1. Create an OAuth 2.0 credential (type: Desktop application)
2. Download the credential JSON
3. Run the Google MCP server once to generate token.json:

   GOOGLE_CREDENTIAL_FILE=~/Downloads/credentials.json \

npx @antidrift/mcp-google

   This opens a browser for you to authorize. Once done, it saves `token.json` locally.

Step 3: Configure the Proxy

Create ~/.config/4q-tokens/config.json:

{

"upstreams": [ { "name": "google-workspace", "transport": "stdio", "command": "npx", "args": ["@antidrift/mcp-google"], "env": { "GOOGLE_TOKEN_FILE": "~/.local/share/google-mcp/token.json", "GOOGLE_CONNECTORS": "gmail,calendar,drive" } } ], "searchLimit": 5, "callItemLimit": 30, "maxTextLength": 800, "maxOutputTokens": 10000, "idleTimeoutMs": 600000 }

Step 4: Start the Proxy

mcp-proxy

Or via systemd if installed:

systemctl --user start mcp-proxy

Step 5: Connect Your LLM

Configure your LLM to use http://127.0.0.1:9200/mcp as its MCP server. It will see:

• mcp_search — find tools by natural language
• mcp_call — invoke a tool
• mcp_schema — see tool details

Example query:

mcp_search("send an email")

Returns: google_send_email (Gmail)

mcp_call(ref="google_send_email", args={"to": "user@example.com", "subject": "Hello", "body": "Test"})

Configuration

Quick Start with Environment Variables

export MCP_PROXY_UPSTREAMS='[

{ "name": "google", "transport": "stdio", "command": "node", "args": ["/path/to/google/server.mjs"], "env": { "GOOGLE_TOKEN_FILE": "token.json" } } ]'

export MCP_PROXY_SINGLETON_PORT=9200 export MCP_PROXY_DASHBOARD_PORT=9100

node dist/index.js

Config File (Recommended)

Create ~/.config/4q-tokens/config.json:

{

"upstreams": [ { "name": "google-workspace", "transport": "stdio", "command": "npx", "args": ["@antidrift/mcp-google"], "env": { "GOOGLE_TOKEN_FILE": "token.json", "GOOGLE_CONNECTORS": "gmail,calendar,drive" } }, { "name": "external-api", "transport": "http", "url": "https://mcp.example.com/", "auth": { "apiKey": "MY_API_KEY_ENV_VAR" } } ], "searchLimit": 3, "callItemLimit": 20, "maxTextLength": 500, "maxOutputTokens": 8000, "idleTimeoutMs": 300000 }

Then run:

node dist/index.js

The proxy will load the config from ~/.config/4q-tokens/config.json if it exists, otherwise fall back to the MCP_PROXY_UPSTREAMS environment variable.

Configuration Reference

Upstream Server Config

{

"name": "unique-id", "transport": "stdio" | "http",

// For stdio transport: "command": "node", "args": ["path/to/server.mjs"], "cwd": "/working/dir", // optional "env": { "KEY": "value" }, // optional

// For http transport: "url": "https://example.com/mcp", "auth": { "apiKey": "ENV_VAR_NAME" // reads from process.env[ENV_VAR_NAME] } }

Proxy Options

Environment variable overrides:

export MCP_PROXY_SEARCH_LIMIT=5

export MCP_PROXY_CALL_ITEM_LIMIT=30 export MCP_PROXY_MAX_TEXT_LENGTH=800 export MCP_PROXY_MAX_OUTPUT_TOKENS=10000 export MCP_PROXY_IDLE_TIMEOUT_MS=600000

Multi-Agent Lanes (Per-Agent Isolation)

When several agents share one proxy, each agent should only be able to see and call its own tools. 4Q-Tokenz does this with lanes. A lane is a named view of the tool registry that is served at its own URL, /mcp/ . An agent connected to its lane cannot discover or call tools from any other lane, even if it knows the ref.

agent hope    -> entry "tokens-hope"   -> /mcp/hope    -> google-hope, hope-memory

agent clark -> entry "tokens-clark" -> /mcp/clark -> google-clark, clark-memory (no lane) -> /mcp -> refused (HTTP 403)

Defining lanes

Add an agents block next to upstreams in ~/.config/4q-tokens/config.json (or set MCP_PROXY_AGENTS as JSON). Each lane lists the upstream providers it may use and, optionally, individual tools to deny:

{

"upstreams": [ ... ], "agents": { "hope": { "allow": ["google-hope", "hope-memory"], "deny": ["google-hope.drive_share", "google-hope.share_doc"] }, "clark": { "allow": ["google-clark", "clark-memory"] } } }

Agent ids must match ^a-z0-9_{0,63}$. The plain array form ("hope": ["google-hope"]) is still accepted and means allow-only.

Fail-closed behavior

• The unscoped route /mcp is refused with 403. A client that is not bound to a lane never sees the whole tool pool. For local development only, set MCP_PROXY_ALLOW_UNSCOPED=1 to re-enable it.
• An unknown lane (/mcp/nobody) returns 404.
• A stdio instance that would become the primary (and so serve the whole pool to one client) refuses to start unless MCP_PROXY_ALLOW_UNSCOPED=1. Run the proxy as a service instead (see Singleton and Bridge Mode).
• A bridge refuses to start without a valid MCP_PROXY_AGENT.

Singleton and Bridge Mode

One primary instance owns the upstream connections and listens on MCP_PROXY_SINGLETON_PORT (default 9200). Run it as a service with MCP_PROXY_SERVICE_MODE=1 (HTTP only, no stdio). Any additional instance launched as a stdio MCP server detects the live primary through the lock file and becomes a bridge. A bridge forwards the client's stdio traffic to the primary on its own lane:

MCP_PROXY_AGENT=hope node dist/index.js    # bridge: forwards to http://127.0.0.1:9200/mcp/hope

The lock file lives in MCP_PROXY_LOCK_DIR, else $XDG_RUNTIME_DIR, else /run/user/ , else the temp dir. Hosts that launch the proxy with a minimal environment (for example the OpenClaw gateway) do not set XDG_RUNTIME_DIR, which is why the /run/user/ fallback exists. If an instance wins a lock but finds the port already served, it releases the lock and bridges instead of crashing.

Wiring agents in OpenClaw

OpenClaw has no per-agent MCP setting and does not tell a stdio server which agent launched it. Isolation therefore needs two layers:

1. One MCP server entry per agent, each passing its own lane through the environment. Use names that start with a letter, because OpenClaw exposes MCP tools as __ :

"mcp": {

"servers": { "tokens-hope": { "command": "/path/to/start-4q-tokens.sh", "env": { "MCP_PROXY_AGENT": "hope" } }, "tokens-clark": { "command": "/path/to/start-4q-tokens.sh", "env": { "MCP_PROXY_AGENT": "clark" } } } }

1. Each agent denies the other agents' entries using glob patterns in its tool policy, so it does not see them at all (deny always wins in OpenClaw's tool policy):

"agents": { "entries": { "hope": { "tools": { "deny": ["tokens-clark__*"] } } } }

The proxy lane is the enforcing boundary: whatever an agent does, a bridge bound to hope can only reach /mcp/hope. The OpenClaw deny list is defense in depth that keeps one agent from being handed another agent's entry.

Verifying isolation

• Proxy log: every session is logged with its lane, for example HTTP session created: ... [hope]. There should be no [open] sessions and no Refused unscoped lines in normal operation.
• From each agent, run mcp_search and confirm only that lane's providers appear.
• From an agent, call a ref from another lane. It must return Tool not found.

Running

Standalone (Stdio Transport)

node dist/index.js

The proxy connects vi