open-agent-connector
Summary: open-agent-connector is a zero-dependency MCP server that lets Claude delegate chores (search, page reading, drafting, image generation) to cheaper OpenAI-compatible helper models, keeping Claude in charge while saving its tokens.
ask_agent— hand a self-contained text task (summarising, drafting, translating, brainstorming) to a helper; useautofor failover,allto run every text model in parallel, or an exact model id.web_search— get a short grounded answer plus source URLs for docs, errors, versions or news; falls back to clearly labelled⚠️ NOT A LIVE SEARCHmodel knowledge when no live search is available.web_fetch— read a URL; passquestionand a helper reads the full page and returns only the answer, otherwise you get capped cleaned page text.generate_images— generate images across configured image models (fallback to first success, or all in parallel in judge mode), save candidates to disk, and review them viapaths,judge(vision model pre-ranks), orinline.list_helper_models— inspect configured role/model ids and what the backend advertises.Cross-cutting: any OpenAI-compatible endpoint behind a gateway, token savings via digests and
OAC_MAX_RESULT_CHARScapping, adoctorsmoke-test command, andinitwiring that adds a delegation policy toCLAUDE.md— with helpers never touching your repo.
Connects to a local Ollama instance through its OpenAI-compatible endpoint to serve as the helper model backend for text tasks (e.g. ask_agent, page digests, drafting).
Connects to OpenAI's API (or any OpenAI-compatible endpoint) to delegate work to helper models: chat completions for text tasks and page digests, image generation via /images/generations, web search via the Responses API web_search tool, and model listing via /models. Used for tasks like drafting text, reading web pages, running searches, and generating/ranking candidate images.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@open-agent-connector search the web for the latest Node.js LTS version and summarize it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
open-agent-connector
Keep Claude as the lead engineer and hand the chores to cheaper models, to cut Claude Code token costs.
open-agent-connector is a zero-dependency MCP server. It gives
Claude (Claude Code, Claude Desktop) a small set of tools that hand work to helper models behind
any OpenAI-compatible endpoint: web search, page reading, text drafting and image generation.
Claude decides when to delegate, checks what comes back, and makes every final call. The helpers
spend their tokens and Claude saves its own.
┌──────────────────────────────────────┐
You ──▶ │ Claude (lead: plans, decides, codes) │
└───────────────────┬──────────────────┘
│ MCP over stdio (Claude chooses when to call)
┌───────────────────▼──────────────────┐
│ open-agent-connector (this repo) │ Node.js, zero dependencies
└───────────────────┬──────────────────┘
│ HTTPS + Bearer key, OpenAI-compatible API
┌───────────────────▼──────────────────┐
│ Any gateway / provider │ 9router · LiteLLM · OpenRouter ·
│ /chat/completions /images/... │ OpenAI · Ollama · …
└──────────────────────────────────────┘Why
Claude stays in charge. If you point Claude Code's base URL at another model, Claude is gone. With an MCP server, Claude keeps the controls and only calls helpers when it decides to.
Fewer Claude tokens. Helpers read the long pages, search results and drafts. Claude only gets a short digest, capped by
OAC_MAX_RESULT_CHARS.Image models with fallback or competition. By default the image models are tried in order and the first success is used. Turn on judge mode and they all draw in parallel while a cheap vision model ranks the results.
Not tied to a backend. It talks standard OpenAI endpoints. Models are plain ids from your config, so you can mix vendors behind one gateway.
Nothing to install. Run it with
npx -y github:HTB95/open-agent-connector. It has no dependencies and no build step.
Related MCP server: Houtini LM
Tools exposed to Claude
Tool | What it does | Backend calls |
| Hands a self-contained text task to a helper. |
|
| Runs a live search and returns a short answer with source URLs. | Native search endpoint (opt-in) → Responses API |
| Reads a URL. If you pass | Native fetch endpoint (opt-in), otherwise a local fetch, then |
| Generates images and saves them to disk. Default: tries |
|
| Shows the configured roles and the model ids the backend advertises. |
|
The review option of generate_images controls how Claude sees the candidates:
paths(default in fallback mode): you get file paths, and Claude opens the ones it wants with its Read tool.judge(default in judge mode): a vision-capable helper scores the candidates first, so Claude reads a short ranking.inline: the images are embedded in the tool result. This uses the most tokens.
Quick start
Requirements: Node.js ≥ 18.17, git, and an OpenAI-compatible endpoint with an API key.
Let Claude do it. Set OAC_BASE_URL and OAC_API_KEY yourself (never paste the key into the
chat), then tell Claude Code:
Set up open-agent-connector in this project by following https://github.com/HTB95/open-agent-connector/blob/main/docs/AGENT_SETUP.md
Claude runs init, lets doctor suggest model ids from your backend, smoke-tests and commits.
Or by hand:
# 1. Point the connector at your backend (example: OpenAI directly)
export OAC_BASE_URL="https://api.openai.com/v1"
export OAC_API_KEY="sk-..."
export OAC_TEXT_MODELS="gpt-5-mini"
export OAC_IMAGE_MODELS="gpt-image-1"
export OAC_SEARCH_MODEL="gpt-5-mini"
# 2. Smoke-test the backend outside Claude (costs no Claude tokens).
# With only BASE_URL and API_KEY set, doctor prints suggested OAC_TEXT_MODELS / OAC_IMAGE_MODELS.
npx -y github:HTB95/open-agent-connector doctor --text --search --fetch --image
# 3. Wire a project (writes .mcp.json, .claude/settings.json, CLAUDE.md, .gitignore)
cd your-project
npx -y github:HTB95/open-agent-connector init
git add -A && git commit -m "Wire Claude helpers"Restart Claude Code and run /mcp. You should see helpers · connected. Then try:
Create a hero image for a coffee-shop landing page with the helpers and copy it to
public/hero.png.
For per-user install, Claude Code on the web (cloud), Claude Desktop and troubleshooting, see docs/SETUP.md.
Configuration
All settings are environment variables. init writes a .mcp.json that forwards them with
${VAR:-} expansion, so the file never contains a secret.
Variable | Default | Description |
| required | OpenAI-compatible base URL, including |
| (empty) | Sent as |
| auto-pick | Comma-separated chat model ids. |
| (empty) | Comma-separated image model ids, in fallback order. |
|
|
|
| first text model | Vision-capable chat model used by |
| (empty) | Provider ids for a native search endpoint ( |
|
| Path of that native search endpoint. |
| (empty) | A model that supports the OpenAI Responses API |
| (empty) | Provider ids for a native fetch endpoint ( |
|
| Path of that native fetch endpoint. |
|
| Where candidate images are saved. |
|
| Maximum characters any tool returns to Claude. |
|
| Larger images are never inlined. |
|
| HTTP timeouts. |
Notes:
The image parameters
quality,backgroundandoutput_formatare sent only to OpenAI-style image models: ids containinggpt-image,gpt-…-imageordall-e. Other models getprompt,sizeandn.response_format: "b64_json"is left out forgpt-image-*models, because OpenAI documents it as unsupported there.Claude Code gives MCP tools a limited time to run. Image generation can take 30–120 s, so set
MCP_TOOL_TIMEOUT=300000in the environment that launches Claude Code.
Backend examples
These are example settings. Check yours with doctor before you rely on them.
OAC_BASE_URL=http://localhost:4000/v1
OAC_API_KEY=sk-litellm-master-or-virtual-key
OAC_TEXT_MODELS=gemini-flash,gpt-mini # model_name values from your config.yaml
OAC_IMAGE_MODELS=gpt-image,imagen
OAC_SEARCH_MODEL=gpt-mini # only if that deployment supports Responses web_searchOAC_BASE_URL=http://localhost:20128/v1 # use the port your dashboard shows
OAC_API_KEY=sk-...
OAC_TEXT_MODELS=ag/gemini-3.5-flash-medium,cx/gpt-5.5
OAC_IMAGE_MODELS=cx/gpt-image-2.5,ag/gemini-3.1-flash-image
OAC_SEARCH_PROVIDERS=antigravity # 9router POST /v1/search
OAC_SEARCH_MODEL=cx/gpt-5.5 # fallback: Responses web_search
OAC_FETCH_PROVIDERS=jina-reader # optional, only if connected in 9routerOAC_BASE_URL=https://api.openai.com/v1
OAC_API_KEY=sk-...
OAC_TEXT_MODELS=gpt-5-mini
OAC_IMAGE_MODELS=gpt-image-1
OAC_SEARCH_MODEL=gpt-5-miniOAC_BASE_URL=https://openrouter.ai/api/v1
OAC_API_KEY=sk-or-...
OAC_TEXT_MODELS=google/gemini-2.5-flash,openai/gpt-5-minigenerate_images needs an OpenAI-style /images/generations endpoint. Leave OAC_IMAGE_MODELS
empty here unless your gateway provides one.
OAC_BASE_URL=http://localhost:11434/v1
OAC_TEXT_MODELS=qwen3:8bIf you use a gateway that pools consumer subscriptions, it is up to you to follow each provider's terms of service.
How the token savings work
Digest, don't dump.
web_searchandweb_fetchwithquestionreturn a short answer, not the raw page.Hard cap. Every tool result is cut at
OAC_MAX_RESULT_CHARS, with a note that it was cut.One image by default, cheap judging when asked. Fallback mode pays for one generation per request. In judge mode,
review: "judge"turns N images into a few lines of text, so Claude doesn't have to view each image.A delegation policy.
initadds a short policy toCLAUDE.mdtelling Claude when to delegate. Without one, Claude rarely calls helper tools on its own.Small tool surface. Five tools with short schemas, because tool definitions are re-sent on every turn.
Who does what
The policy splits work by kind, not by size:
Helpers (information gathering, production) | Claude (code and reasoning) |
Web search, finding and reading docs | Reading and writing code |
Summarising long pages, changelogs, search results | Debugging, design, architecture |
Translating, drafting prose, test-data boilerplate | Reviewing and deciding what to keep |
Generating images | Anything that needs the repo's context |
Delegating still has a cost: Claude writes the prompt and reads the answer. So the one exception is work where the prompt costs more than the job, such as a fact Claude already knows.
No measured before/after numbers are published yet. When the backend reports usage, ask_agent
prints each helper's token in/out next to its answer, so you can compare a delegated task against
doing it in Claude. If you measure real savings, a PR with the numbers and the method is welcome.
How it compares
There are other MCP servers that let Claude ask another model for an opinion, and routers that swap the model behind Claude Code. This project focuses on chores rather than second opinions:
Image generation with model fallback, or several models in parallel with a judge model so Claude only opens the top one or two images.
web_fetchwith aquestion: the helper reads the page and Claude only gets the answer.Model ids per role (
text,image,judge,search) on any OpenAI-compatible gateway.A ready delegation policy that
initwrites intoCLAUDE.md, plus a one-command setup that works the same locally and in Claude Code cloud sessions.
Security
Don't commit keys. Keys belong in your shell profile or in the cloud environment settings.
.mcp.jsononly holds${VAR}references.If your gateway is reachable from the internet, put it behind HTTPS and require an API key. Without TLS, the bearer key travels as plain text.
Helpers never touch your repository. They only see what Claude puts in a prompt, and the delegation policy tells Claude never to put secrets or
.envcontents there.See SECURITY.md to report a vulnerability.
Limitations
Only the stdio transport is supported. The claude.ai web chat (remote MCP connectors) is not. A remote MCP version (for example on a serverless platform) is an idea under consideration and has not been tried. It would keep keys on the server and skip the
npxdownload per session, butgenerate_imageswould have to return image URLs (for example from object storage) instead of local file paths.The automated tests run against a mock gateway (
test/mock-router.mjs), not real providers. Usedoctorto check your own backend.Native search and fetch endpoints are not part of the OpenAI API. They follow the request and response shape used by 9router, and the paths can be changed.
Development
git clone https://github.com/HTB95/open-agent-connector.git
cd open-agent-connector
npm test # node:test, no install needed
npm run doctor -- --text # live probe using your OAC_* envProject layout:
bin/server.mjs CLI entry: MCP server (default), `init`, `doctor`
src/mcp-server.mjs hand-rolled MCP JSON-RPC over stdio
src/router-client.mjs OpenAI-compatible HTTP client (JSON + SSE tolerant)
src/models.mjs role resolution / text-model auto-pick
src/tools/*.mjs ask_agent, web_search, web_fetch, generate_images, list_helper_models
src/init.mjs project wiring for Claude Code
examples/ delegation policy + sample .mcp.json
test/ node:test suites + mock gatewayContributions are welcome. Read CONTRIBUTING.md first.
License
Available Tools
5 toolsask_agentA
Delegate a self-contained chore to a cheaper helper model to save Claude tokens: summarising docs/logs, drafting boilerplate, translating, brainstorming, explaining an API. Give full context in prompt (helpers cannot see the repo). You remain responsible for verifying the answer.
Inputs: prompt (required), model, system, max_tokens.
generate_imagesA
Generate images with every configured image model in parallel (OAC_IMAGE_MODELS), save candidates to disk, and return them for you (Claude) to choose the best. review: "paths" (default; open chosen files with Read), "judge" (a helper vision model pre-ranks — cheapest), "inline" (images embedded in this result). Copy the winner into the project yourself afterwards.
Inputs: prompt (required), size, models, review, +6 more.
list_helper_modelsB
Show which helper model ids are configured for each role and which ids the backend advertises.
Inputs: no named parameters.
web_fetchA
Read a web page. With question, a helper model reads the full page and returns only the answer — far cheaper than loading the page into Claude. Without it, returns cleaned page text (capped).
Inputs: url (required), question.
web_searchA
Live web search done by helpers. Returns a short grounded answer + source URLs instead of raw pages, saving Claude tokens. Use for docs, error messages, versions, news. If the result starts with "NOT A LIVE SEARCH", treat it as possibly outdated.
Inputs: query (required), focus, max_results.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct primary role: ask_agent delegates text chores, web_search returns grounded search answers, web_fetch extracts page content, generate_images handles image generation, and list_helper_models introspects configuration. There is minor overlap between ask_agent and web_search for documentation/error queries, but the descriptions clarify when to use each.
All tool names use consistent snake_case, which makes them easy to scan. The pattern is mostly verb_noun (ask_agent, generate_images, list_helper_models) but web_search and web_fetch use noun_verb, a minor deviation from full consistency.
Five tools are well-scoped for a connector that delegates to helper models and performs web/image operations. Each tool covers a distinct capability without redundancy or bloat.
The surface covers delegation, live web search, page fetching, image generation, and helper model introspection. Minor gaps exist, such as no explicit local file-reading tool or helper configuration tool, but the core workflows are supported.
Maintenance
Related MCP Connectors
Agent personas for Claude. 16 tools, 13 personas, 3 workflows. Zero extra API cost. Free.
Build agents to automate any background task. Works with your ChatGPT/Claude subscription.
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
Remote streamable-HTTP MCP server running on a single Cloudflare Worker. Your assistant gets live Airbnb, Amazon, Booking.com, Google Flights, Maps and Reddit data, social search on X, Instagram and TikTok, the Meta Ad Library, and image/video generation without any keys. Connect your own accounts to let it send WhatsApp or Telegram messages, work an IMAP inbox, manage Meta Ads campaigns and publish to X and LinkedIn. OAuth 2.1 with PKCE; stored credentials are AES-256-GCM encrypted.
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables Claude Code and Claude Desktop to delegate bounded, disposable tasks to local or cheap cloud models, with model scoring, guardrails, and cost-saved tracking.53MIT
- FlicenseNot gradedqualityAmaintenanceEnables Claude Code and other MCP clients to hand bounded work such as code review, boilerplate generation, commit messages, format conversion and embeddings to a local GPU model, LiteLLM router, OpenRouter, or cheaper cloud API like OpenAI, DeepSeek, Groq or Cerebras. Keeps the orchestrating model as architect and reviewer, cutting token spend and providing a second opinion on code.-
- FlicenseNot gradedqualityAmaintenanceEnables MCP clients like Claude Code to delegate bounded work—code review, boilerplate, commit messages, format conversion, embeddings—to local or cloud OpenAI-compatible models, keeping large files out of the main model's context to cut token costs and provide a second opinion. It routes and profiles the target model automatically, while the orchestrating client retains planning and quality checks.-
- AlicenseNot gradedqualityAmaintenanceEnables MCP clients such as Claude Code to delegate bounded tasks like code review, boilerplate generation, commit messages, format conversion, and embeddings to local or cloud OpenAI-compatible LLMs, reducing token costs while keeping the main model in control.MIT