Capability Router

Capability Router exposes skills and MCP tools through one MCP tool named capability. The model receives one stable schema. It searches for a capability only when the task needs it.

The router supports independent personal, office, and project contexts. Each agent session can select its own context. Many sessions can use the same registry at the same time.

The runtime uses the Python standard library.

Install

Capability Router requires Python 3.10 or newer on Linux or macOS.

pipx install git+https://github.com/maybeabhinav/capability-router.git

You can also use uv:

uv tool install git+https://github.com/maybeabhinav/capability-router.git

Create and refresh a read-only configuration:

capability-router init
capability-router refresh --config ~/.config/capability-router/config.json

Related MCP server: Skill Shelf

Connect one context

Create a context and select it for a unique session ID:

capability-router context create personal \
  --config ~/.config/capability-router/personal/config.json \
  --source personal \
  --source shared

capability-router context use personal --session codex-personal

Connect Claude Code:

claude mcp add --scope user capability-router -- \
  capability-router serve \
  --registry ~/.config/capability-router/contexts.json \
  --session claude-personal

Connect Codex:

codex mcp add capability-router -- \
  capability-router serve \
  --registry ~/.config/capability-router/contexts.json \
  --session codex-personal

Codex can require approval for an MCP tool that routes both read and write operations. Add this key to the existing router table in ~/.codex/config.toml when the router is the approved trust boundary:

[mcp_servers.capability-router]
default_tools_approval_mode = "approve"

The router still applies its mode, context assignment, access class, schema, and environment rules before it starts a downstream tool.

Use a different session ID for each concurrent agent. One session can switch contexts without changing another session.

See Context management for context and account commands.

Agent flow

The MCP server exposes one tool. Its common actions are:

1. search returns a small metadata result.

2. load_skill loads one selected skill.

3. describe returns one selected MCP tool schema.

4. call validates and invokes one selected MCP tool.

5. context_current, context_list, and context_use manage the current agent session.

6. context_move, context_share, context_unassign, and context_undo change capability assignments.

Search for one need per call. Use a result limit from 1 through 5.

The reusable agent skill is in skills/capability-router/SKILL.md.

Add skills

Pass one or more skill roots during setup:

capability-router init --force \
  --skill-root personal=~/.agents/skills \
  --skill-root shared=~/agent-skills

Each direct child can contain one SKILL.md. Refresh the catalog after a skill changes.

Add MCP servers

Add a server to the context configuration. Then refresh that configuration and run context doctor.

A local stdio server:

{
  "transport": "stdio",
  "command": "example-mcp-server",
  "args": [],
  "cwd": ".",
  "inherit_environment": ["PATH"],
  "environment_from_parent": {
    "EXAMPLE_API_TOKEN": "EXAMPLE_API_TOKEN"
  },
  "default_access": "unknown",
  "access_overrides": {
    "search": "read"
  }
}

Use absolute runtime paths for servers installed through a version manager. Some clients start MCP servers with a reduced PATH. For a Node package, set command to the absolute Node binary and put the package entry script first in args. This avoids #!/usr/bin/env node startup failures.

A remote Streamable HTTP server:

{
  "transport": "http",
  "url": "https://mcp.example.com/mcp",
  "headers_from_parent": {
    "Authorization": "EXAMPLE_AUTHORIZATION"
  },
  "default_access": "unknown",
  "access_overrides": {
    "search": "read"
  }
}

HTTP redirects are rejected. Remote URLs must use HTTPS. Loopback HTTP is allowed for local development.

The current HTTP client supports JSON responses and SSE response frames. It supports tokens supplied through private environment files. Interactive OAuth login is not implemented yet.

Private context environments

Keep values outside repository files. Create a JSON file with mode 0600:

{
  "EXAMPLE_API_TOKEN": "value",
  "GH_CONFIG_DIR": "/home/user/.config/gh-personal",
  "AWS_PROFILE": "personal"
}

Attach the file when you create the context:

capability-router context create personal \
  --config ~/.config/capability-router/personal/config.json \
  --environment-file ~/.config/capability-router/personal/environment.json

The router passes only variables named by a server configuration. A context switch replaces the environment overlay for later calls.

Run a CLI with the same context:

capability-router context exec personal -- gh auth status
capability-router context exec office -- aws sts get-caller-identity

Access classes

Classify each tool as read, write, external_write, destructive, or unknown.

Read-only mode blocks every class except read before the downstream server starts. Use unrestricted mode only when the calling agent has authority for the requested operation.

Verify

python3 -m unittest discover -s tests -v
python3 tests/verify_sdist.py
python3 -m compileall -q capability_router tests

The tests use local fixtures. They do not need external accounts.

See Evaluation for concurrency and agent behavior results.

Scope

• Local stdio MCP servers

• Remote MCP Streamable HTTP servers with caller-supplied headers

• Local SKILL.md directories

• Per-session context selection

• Atomic context assignment revisions and undo

• Context-specific environment files

• Closed JSON Schema subsets for draft-07 and draft 2020-12

• MCP protocol versions 2024-11-05, 2025-06-18, and 2025-11-25

License

MIT