Skip to main content
Glama
szeeshan896

MCP Bridge

by szeeshan896
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

MCP Bridge

CI

Delegate work to another AI agent from inside the one you are already in.

claude mcp add mcpbridge -- npx -y mcpbridge

That is the whole setup. Now, while you are coding in Claude Code:

ask gemini through mcpbridge to review the caching layer in this module

Claude calls ask_agent, the bridge runs Gemini, and the answer comes back into your conversation. One call, work done. No mailbox to check, nothing to nudge.

No API keys

The bridge never calls a model API. It drives the agent CLIs already installed and signed in on your machine, so each one uses its own existing subscription — and it can talk to a model running locally in Ollama, which needs no account at all.

                                  ┌──→ claude -p "…"      your Claude subscription
Claude Code ──MCP──→  mcpbridge ──┼──→ codex exec "…"     your Codex subscription
Cursor      ──MCP──→              ├──→ gemini -p "…"      your Gemini subscription
                                  └──→ Ollama (localhost) no account, no network

It removes the key, not the quota: your subscription limits still apply.

Related MCP server: agent-hub

Tools

Tool

What it does

list_agents

who can be delegated to, and whether each is usable right now

ask_agent

hand one a task, wait, get the answer

start_task

same, but returns an id immediately for work that outlasts the request

get_task

check on a started task

ask_agent is the normal path. The agent you delegate to starts fresh: it cannot see your conversation or your files, so write a self-contained prompt and pass workingDirectory whenever the task is about code.

Check what you have

npx mcpbridge --agents
✓ claude     claude found on PATH
✗ codex      codex is not on PATH — install it or fix the command
✗ gemini     gemini is not on PATH — install it or fix the command
✓ ollama     Ollama at http://127.0.0.1:11434, using qwen3:latest

Nothing to configure to get here — the four agents above are built in, and anything not installed is simply reported, never silently broken.

Adding or fixing an agent

Write ~/.config/mcpbridge/config.json (or point MCPBRIDGE_CONFIG elsewhere). Entries replace the built-in one of the same name outright.

{
  "agents": {
    "gemini": {
      "command": ["gemini", "--prompt", "{prompt}"],
      "timeoutMs": 300000
    },
    "local": {
      "type": "ollama",
      "model": "qwen3:latest",
      "description": "Local model for anything that should not leave this machine"
    }
  }
}

Each tool's non-interactive flags change between releases, so if a built-in default does not match your version, override it here — --agents will confirm.

Why the command lives in configuration

This program runs other programs. If a tool call could choose the command, a prompt injected into the calling model would be remote code execution.

So commands come only from configuration. A call names an agent, that name is looked up in the configured set, and the prompt fills a {prompt} placeholder that reaches spawn as a single argument with no shell involved. A prompt full of ; and backticks arrives as text; there is a test that asserts exactly that, and that nothing in it executes.

stdio or HTTP

stdio is the default and what you want: the client starts the bridge itself, so there is no port, no daemon and no listening socket at all.

For one shared instance instead:

npx mcpbridge --http 8808        # http://127.0.0.1:8808/mcp

That mode binds loopback only, and rejects requests whose Host header is not 127.0.0.1/localhost — otherwise a web page you visit could make your browser POST to the port and run ask_agent on your machine. Loopback binding alone does not stop that.

On Windows

An agent whose command resolves to a .cmd or .bat shim — which is how npm-installed CLIs appear on Windows — is refused rather than run, because a batch file can only be invoked through a shell and putting a prompt through a shell is the one thing this program must not do. list_agents says so and names the fix: point the agent at the real executable.

{ "agents": { "claude": { "command": ["node", "C:\\Users\\you\\AppData\\Roaming\\npm\\node_modules\\@anthropic-ai\\claude-code\\cli.js", "-p", "{prompt}"] } } }

What it will not do

  • Long tasks hit a timeout. ask_agent is synchronous and the client has its own request deadline. Split big jobs, or use start_task and poll get_task.

  • Each call starts fresh. The delegated agent remembers nothing between calls.

  • It is local only. It drives CLIs signed in on this machine and reads this machine's files, so there is nothing to host and nothing to deploy.

Development

npm install
npm test          # typecheck + 32 tests
npm run build
npm start         # stdio, from source

Runtime

Node 22+

SDK

@modelcontextprotocol/sdk 1.32.2

Package size

~16 KB

src/agents/   cli.ts (spawns a command), ollama.ts (local model), registry.ts, types.ts
test/fixtures/agent.mjs  a Node stand-in for an agent CLI, so the suite runs on Windows
src/config.ts built-in defaults and the config file
src/tasks.ts  background tasks behind start_task / get_task
src/server.ts the four tools
src/index.ts  entry point and transport choice

A Java and Spring Boot implementation came first and is preserved in this repository's history at commit 498634f; it was ported here so the tool installs with one npx command and no JRE.

Roadmap

  • one-call delegation, Ollama agent, async tasks, allowlisted commands

  • follow-up calls that reuse an agent's session instead of starting fresh

  • streaming progress while a long delegation runs

Available Tools

4 tools
ask_agentDelegate a task and waitA

Hand a task to another AI agent and wait for its answer. One call does the whole thing. The agent starts fresh with no knowledge of this conversation and cannot see your files unless you point it at them, so make the prompt self-contained and pass workingDirectory when the task is about code in a project. If "succeeded" is false, read "diagnostics". For a job long enough to outlast this request, use start_task.

NameRequiredDescriptionDefault
agentYesWhich agent to use, exactly as list_agents names it, e.g. "gemini".
promptYesThe full self-contained task or question for that agent.
workingDirectoryNoAbsolute path to run the agent in, so it can read the project files.

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does most of it: it discloses that the remote agent starts with no conversational context and no filesystem visibility unless pointed at a path, and that failure surfaces as "succeeded": false with a "diagnostics" field. It leaves out timeout behavior, cost/latency implications, and concurrency, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Five short sentences, front-loaded with what the tool does and the blocking behavior, then constraints, then the failure path, then the sibling escape hatch. Nothing is redundant with the title or schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, yet the description tells the agent how to interpret the result (check "succeeded", read "diagnostics") and how the delegated agent's isolated context must be compensated for. For a 3-parameter tool with full schema coverage, nothing operationally necessary is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema does the baseline work and 3 would be acceptable. The description still adds real semantics the schema lacks: why the prompt must be self-contained (the remote agent is context-free) and when to supply workingDirectory (code work in a project).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource — hand a task to another AI agent — plus the key behavioral fact that the call blocks and waits for the answer. This contrasts cleanly with the sibling start_task, which is fire-and-forget, so an agent can choose between them without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit routing rule: use this for the synchronous case, use start_task "for a job long enough to outlast this request." It also gives a conditional instruction for workingDirectory (pass it when the task concerns code in a project), so both the choice of tool and the choice of parameters are guided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_taskCheck a delegated taskA

Look up a task started with start_task. While "status" is "running" the agent is still working — wait before asking again rather than polling in a tight loop. Once it is "finished", "result" holds the same shape ask_agent returns.

NameRequiredDescriptionDefault
idYesThe task id returned by start_task.

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does meaningful work: it discloses the running/finished state machine, tells the agent to back off polling, and specifies that "result" matches ask_agent's return shape. It omits error/failure states, timeouts, and whether completed tasks persist or can be re-read, so it is strong but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no filler, and the ordering is well front-loaded: identity/linkage first, then the polling-avoidance behavior an agent most needs before it calls.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must explain returns, and it does cover the two salient fields and the relationship to ask_agent's payload. A single-parameter lookup needs little more, though a note about terminal failure states would close the remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single "id" parameter is already documented in the schema as "The task id returned by start_task." The description adds no syntax, format, or validation detail beyond that, so the baseline 3 for fully-covered schemas applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("look up a task") and anchors it to the sibling that creates it ("started with start_task"), which cleanly separates it from start_task, ask_agent, and list_agents. It also names the two response fields ("status", "result") an agent will act on, so the purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete calling guidance: use it after start_task, and while status is "running" wait rather than polling in a tight loop. It stops short of explicit exclusions (e.g., when to use ask_agent instead, or what to do on a failed task), so it falls just short of the top tier.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_agentsList delegable agentsA

List the AI agents this bridge can delegate to, and whether each one is usable right now. Check this before delegating: "available": false carries the reason, such as a CLI that is not installed or an Ollama that is not running.

NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden, and it does useful work: it discloses that availability is reported per agent and that "available": false carries a reason such as a missing CLI or a stopped Ollama. It's a read-only listing with no side effects, so the main remaining gap is the rest of the response shape.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste. The purpose comes first and the pre-delegation guidance follows, which is the right order for an agent scanning for whether to call it.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description supplies the one return detail that matters, the meaning of "available": false. A fuller field list would help, but the essentials for calling and interpreting this zero-param tool are present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so the baseline of 4 applies. Nothing in the description is needed to disambiguate inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (List) and a precise resource (the AI agents this bridge can delegate to), and adds the per-agent usability status, which distinguishes it cleanly from ask_agent, start_task, and get_task.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Check this before delegating" gives an explicit when-to-use condition tied to the delegation workflow. It doesn't name the sibling tools as alternatives, but there is little ambiguity here anyway.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_taskDelegate without waitingA

Start a delegated task and return its id immediately, for work that would outlast this request. Poll get_task with the id. Prefer ask_agent for anything that finishes in a minute or two — it is one call instead of several.

NameRequiredDescriptionDefault
agentYesWhich agent to use, exactly as list_agents names it.
promptYesThe full self-contained task for that agent.
workingDirectoryNoAbsolute path to run the agent in.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the burden and delivers the critical non-obvious behavior: the call is asynchronous, returns an id immediately, and requires polling. It leaves out failure modes, timeouts, and whether the delegated work can be canceled, which keeps it below a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences, front-loaded with the async contract, then the alternative. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so it matters that the description says an id is returned immediately — it does. A brief note on errors or what happens if the task fails would make it fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so agent, prompt, and workingDirectory are all documented in the schema itself. The description implies the prompt is a delegated task but adds no format or constraint detail beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (start) and resource (delegated task) plus the key return (task id) and the async intent ('work that would outlast this request'). This makes it trivially distinguishable from ask_agent and get_task.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the alternative ('Prefer ask_agent for anything that finishes in a minute or two') with the selecting condition, and tells the agent the follow-up path ('Poll get_task with the id'). No inference needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv0.1.0
    • First observedask_agent
    • First observedget_task
    • First observedlist_agents
    • First observedstart_task
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.4/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a distinct role: list_agents discovers targets, ask_agent is synchronous delegation, start_task is asynchronous delegation, and get_task polls an async task. The descriptions explicitly disambiguate the one risky pair (ask_agent vs. start_task) with concrete guidance about which to prefer.

Naming Consistency5/5

All four tools follow a consistent snake_case verb_noun pattern (list_agents, ask_agent, start_task, get_task) with matching singular/plural conventions. No mixed styles or vague verbs.

Tool Count5/5

Four tools is a tight, well-scoped surface for a delegation bridge: discovery, sync call, async start, and poll. Nothing feels redundant or padded.

Completeness3/5

The core sync and async delegation lifecycle is covered, but there is no cancel/abort operation for a task started with start_task, leaving an agent stuck polling a runaway task with no exit. A cancel_task tool is an obvious gap for an async workflow.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers