MCP Model Bridge

Runs an agent definition from .github/agents/ against a model you name, instead of the one the IDE session happens to use.

Copilot agent definitions carry no model field, so a subagent inherits the session model. This server closes that gap: it reads the agent file, uses its body as the system prompt, and executes a bounded tool loop against a chosen model.

Project-independent. Nothing here is tied to the repository it was developed in. Point it at any project and it picks up that project's agents and that project's model policy.

Status

MVP. Ships with a mock gateway so the wiring is testable without credentials. Point it at a real endpoint with two environment variables.

Related MCP server: act-mcp

Install

The bridge is a developer tool, not a runtime dependency. Install it once, use it everywhere.

# from a checkout
npm install
npm run build
npm link

# or straight from a git remote, once the package lives in its own repo
npm install -g git+https://github.com/<you>/mcp-model-bridge.git

# or from a registry, if you publish it
npm install -g @jurulabs/mcp-model-bridge

All three put mcp-model-bridge on the PATH.

Quick start

npm run smoke

The smoke test spawns the built server against a fixture project under test/fixture-workspace that has nothing to do with the surrounding repository. It asserts that the bridge discovers that project's agents and policy, and that the same agent reports different models on different tiers.

Point it at a real project instead:

node scripts/smoke-test.mjs C:\path\to\any\project

Configuration

In practice only BRIDGE_WORKSPACE_ROOT needs setting. Everything else is discovered.

With BRIDGE_GATEWAY_URL and BRIDGE_GATEWAY_TOKEN unset, the server runs the mock gateway and reports gateway: mock. A half-configured gateway also reports mock, which surfaces the missing variable instead of hiding it behind a confident label.

Where the gateway values come from

Not from GitHub Copilot. The Copilot subscription has no endpoint you can post arbitrary requests to, so it cannot serve as the gateway. The two values come from an inference provider you hold credentials with, billed separately from Copilot. That second cost centre is the price of choosing the model yourself.

The client speaks two request shapes, selected by BRIDGE_GATEWAY_SCHEMA:

A base URL that already ends in /v1 is not doubled, so whichever form the provider documents can be pasted as-is.

OpenRouter — one key, every model

The best fit for this bridge, because the tier idea only pays off when cheap, default and strong can point at different vendors behind a single credential.

OpenRouter is prepaid: top up credits, then spend per token. Model identifiers are vendor-prefixed, anthropic/…, openai/…, google/…. List the current ones and their prices before writing the policy:

(Invoke-RestMethod https://openrouter.ai/api/v1/models).data |
  Select-Object id, @{n='in';e={$_.pricing.prompt}}, @{n='out';e={$_.pricing.completion}} |
  Sort-Object in

Two caveats worth knowing up front. OpenRouter may route a model across several upstream providers with differing context limits and latency — pin one with the :nitro or provider-routing suffixes if that matters. And the bridge's text tool protocol is unaffected either way, since it never relies on native tool calling.

Anthropic directly

Needs a paid Anthropic account with credit; the key is shown once at creation.

A corporate or self-hosted gateway

Confirm in the gateway's own documentation which schema it speaks and which model identifiers it accepts.

A translating proxy

Run LiteLLM locally and it fronts OpenAI, Azure OpenAI, Bedrock or Vertex behind either schema. BRIDGE_GATEWAY_URL = http://localhost:4000, token = the master key you set in the proxy config, auth bearer. The upstream provider key then lives in the proxy config, not in this bridge.

Model identifiers are the usual trip-hazard

The bundled policy names Copilot picker labels such as claude-sonnet-5. No provider API recognises those. Replace them with the identifiers your gateway accepts, in the host project's .github/model-policy.json. For OpenRouter that means vendor-prefixed ids:

{
  "tiers": {
    "cheap": "<vendor>/<small model>",
    "default": "<vendor>/<mid model>",
    "strong": "<vendor>/<large model>"
  },
  "allowedModels": ["<vendor>/<small model>", "<vendor>/<mid model>", "<vendor>/<large model>"]
}

A model outside the allow-list is refused, so a stale identifier fails at once rather than after a billed call.

Supplying the values

Per session:

$env:BRIDGE_GATEWAY_URL = 'https://openrouter.ai/api/v1'
$env:BRIDGE_GATEWAY_TOKEN = '<key>'
$env:BRIDGE_GATEWAY_SCHEMA = 'openai-chat'

Persistently for your user account:

[Environment]::SetEnvironmentVariable('BRIDGE_GATEWAY_TOKEN', '<key>', 'User')

Never in the repository, never in the agent file, never in the policy file.

Proving the gateway answers

The smoke test only exercises the mock. One real call, costing one short completion:

npm run gateway:check -- <model-id>

It prints the resolved endpoint, schema and auth scheme, then the model's own reply. The three things that can only fail live — credentials, schema, model identifier — all surface here rather than mid-session.

Inside the IDE, list_agents reports the same resolution without ever echoing the token:

gateway: http (https://openrouter.ai/api/v1/chat/completions, schema: openai-chat, auth: bearer)

gateway: mock means one of the two required variables did not reach the process.

Model policy

The policy file holds the tier map and the allow-list:

{
  "tiers": { "cheap": "gpt-5.6-luna", "default": "claude-sonnet-5", "strong": "claude-opus-5" },
  "allowedModels": ["gpt-5.6-luna", "claude-sonnet-5", "claude-opus-5"]
}

It is looked up in this order:

1. BRIDGE_MODEL_POLICY, if set

2. <workspaceRoot>/.github/model-policy.json — the host project's own policy

3. the bundled model-policy.json — so a fresh project needs no setup

list_agents reports which one won, as source: explicit | workspace | bundled.

A model outside allowedModels is refused with an explicit error. Silent fallback to an expensive model is the failure mode that costs money without anyone noticing, so it is not offered.

Tools

run_agent

Returns the agent's output followed by a provenance block:

agent: Explorer
model used: gpt-5.6-luna (tier: cheap)
rounds: 2, tool calls: 1
stopped: completed

The provenance block is the point of the exercise. A bridge that runs but reports the session model has failed at the only thing it exists to do.

list_agents

Reports the agents the host project defines, the agents directory, the active policy file and where it came from, the tier map, the allow-list, and whether the gateway is live or mocked.

agents directory: C:\some\project\.github\agents
agents: Explorer, Reviewer, ShopifyApi, Tester
model policy: C:\some\project\.github\model-policy.json (source: workspace)
tiers: cheap -> gpt-5.6-luna, default -> claude-sonnet-5, strong -> claude-opus-5
allowed models: gpt-5.6-luna, claude-sonnet-5, claude-opus-5
gateway: mock

A project with no agents directory reports agents: (none found) rather than failing, so the tool can still explain the rest of the configuration.

Registering in JetBrains

Settings → Tools → GitHub Copilot → Model Context Protocol (MCP)

{
  "servers": {
    "model-bridge": {
      "command": "mcp-model-bridge",
      "env": {
        "BRIDGE_WORKSPACE_ROOT": "C:\\path\\to\\the\\project\\you\\are\\working\\in"
      }
    }
  }
}

If you did not link the binary onto the PATH, call the entry point directly instead:

{
  "command": "node",
  "args": ["C:\\path\\to\\mcp-model-bridge\\dist\\index.js"]
}

Run npm run build first — the entry point is the compiled dist/index.js.

Safety

• Read-only toolset. read_file and grep_search only; a cheap model driving these tools cannot edit anything.

• Path confinement. Every requested path resolves against the workspace root; traversal is refused.

• Round ceiling. The loop cannot run away, so it cannot spend without limit.

• Credentials from the environment. Never from the agent file or the policy file.

• Separate billing. Gateway calls are charged outside the Copilot subscription. Two cost centres exist; only one appears in the IDE.

Architecture

The full design, including the variants considered and why this scope was chosen, lives in the global ai-automation skill:

~/.agents/skills/ai-automation/MCP-BRIDGE.md

To move this package into its own repository, see EXTRACTION.md.

Known limits

• Agent bodies written for richer toolsets degrade here. An agent that relies on semantic_search falls back to grep_search.

• Two upstream schemas are implemented, Anthropic Messages and OpenAI Chat Completions. A third shape is a one-file change in src/gateway-client.ts, or a translating proxy in front of it.

• Tool calls travel as fenced ```tool blocks rather than a native tool-calling API, which keeps the bridge portable at the cost of some reliability on weaker models.

• Publishing under the @jurulabs scope requires owning that scope on the target registry. Git and npm link installs need no registry at all.