Modes (Router vs Direct)

mcp-bridge supports two exposure modes:

router (default): one mcp meta-tool for all servers
direct: each backend tool is registered as its own MCP tool

Token footprint comparison

Concrete example from a realistic setup:

10 configured servers
~200 total tools across those servers
Router mode with schema compression enabled

Mode	Tools exposed to the model	Approx prompt tokens for tool definitions
`router`	1 (`mcp`) with compressed descriptions	~120
`direct`	~200 individual tools	~12,000

This is roughly a 99% reduction in tool-definition tokens for router mode, aligned with the README claim of ~99% token reduction for meta-tool routing.

When to use router mode

Use router when you want token efficiency and a scalable setup (especially 3+ servers).

Single mcp entry point
Works best with intent routing, batch calls, schema compression, caching, and multi-server resolution
Lower context overhead as tool count grows

Router config example

{
  "mode": "router",
  "schemaCompression": {
    "enabled": true,
    "maxDescriptionLength": 80
  },
  "maxBatchSize": 10,
  "servers": {
    "todoist": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-todoist"],
      "env": { "TODOIST_API_TOKEN": "${TODOIST_API_TOKEN}" },
      "description": "Task management"
    },
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" },
      "description": "Repos, issues, pull requests"
    }
  }
}

Typical flow:

mcp(server="todoist", action="list")
mcp(server="todoist", action="call", tool="find-tasks", params={...})

When to use direct mode

Use direct when you have a small tool surface and want explicit tool names exposed to the agent.

Tools are registered individually (for example todoist_find_tasks, github_list_repos)
Easier for simple agents that do not use router actions
Higher token cost as server/tool count increases

Direct config example

{
  "mode": "direct",
  "toolPrefix": true,
  "servers": {
    "todoist": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-todoist"],
      "env": { "TODOIST_API_TOKEN": "${TODOIST_API_TOKEN}" },
      "description": "Task management"
    },
    "github": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" },
      "description": "Repos, issues, pull requests"
    }
  }
}