aimux

Multiplexed AI tools gateway. Expose cherry-picked tool sets from MCP, HTTP, and CLI to isolated AI agents over MCP, HTTP, and CLI, using a single local daemon.

Why

AI harnesses (Claude Code, Codex, Cursor, etc.) load every configured MCP server into context, flooding agents with hundreds of irrelevant tools. This causes context window bloat, wasted token, and tool-selection confusion. aimux solves this by acting as a local multiplexing gateway: You define tool sources, assign cherry-picked subsets to named consumers, and each consumer gets its own isolated endpoint.

Install

npm install -g aimuxtool

Requires Node.js >= 24.0.0.

Quick start

1. Create a config file at ~/.aimux/aimux.config.json: See example in config/demo-config.json

2. Start the daemon:

aimux up

3. Connect your AI harness to the consumer endpoint:

   • MCP: http://127.0.0.1:2020/my-agent/mcp
   • HTTP: http://127.0.0.1:2020/my-agent/http/
   • CLI: aimux tool my-agent <tool-name>

4. Add more sources. Add more consumers. aimux will multiplex the cherrypicked tools from each source for each consumer, across all 3 protocols. Each consumer can be any tool that speaks these protocols, and can dynamically switch the cherrypicked set at run time.

Configuration

Config is loaded from ~/.aimux/aimux.config.json by default. Override with the AIMUX_CONFIG env var or --config flag.

Source types

| Type | Description | Required fields | |--------|-------------|-----------------| | mcp | MCP server via stdio subprocess | command, args (optional) | | http | Pre-running HTTP server with OpenAPI spec | url | | cli | Shell commands exposed as tools | commands (map of tool name to { command, args }) |

Consumer

Each consumer defines a cherryPick array of tool references (format: sourceId.toolName) and optional cherryPickSets -- named presets that can be hot-swapped at runtime.

Full schema

{
  "port": 2020,
  "sources": {
    "<source-id>": {
      "type": "mcp|http|cli",
      "command": "...",
      "url": "...",
      "args": ["..."]
    }
  },
  "consumers": {
    "<consumer-id>": {
      "cherryPick": ["sourceId.toolName"],
      "cherryPickSets": {
        "<set-name>": ["sourceId.toolName"]
      }
    }
  }
}

CLI commands

Daemon lifecycle

aimux up [--config <path>]     # Start the daemon
aimux down                      # Stop the daemon

Tool execution

All available tools, no matter their input source protocol, can be consumed as outputs across all protocols.

CLI tool execution

aimux tool <consumerId> <toolRef> '{"<param>":"<value>"}'   # Execute a tool
aimux tool <consumerId> <toolRef> --params              # Show input schema

Tool inputs are always JSON. CLI source tools convert JSON keys to flags automatically.

HTTP tool execution

Using curl:

curl -X 'POST' \
  'http://localhost:2020/<consumerId>/http/<toolRef>' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{"<param>":"<value>"}'

Using interactive docs (OpenAPI/SwaggerUI):

• Visit http://127.0.0.1:2020//http/docs
• Open the section named
• Press the "try it out" button
• Enter {"<param>":"<value>"} into request body
• Press the "execute" button

MCP tool execution

Using curl

curl -X POST http://127.0.0.1:2020/<consumerId>/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"<toolRef>","arguments":{"<param>":"<value>"}}}'

Using mcp-cli

mcp-cli call <consumerId> <toolRef> '{"<param>":"<value>"}'

Hot-swap cherry-pick sets

aimux cherrypick <consumer-id> <set-name>

Applies a named preset from cherryPickSets to the consumer. The daemon hot-reloads: MCP tool lists refresh, OpenAPI specs regenerate, and CLI subcommands update, without downtime.

Add/remove sources and tools

aimux add source <source-id> mcp --command "npx" --args '["-y","@modelcontextprotocol/server-filesystem","/tmp"]'
aimux add source <source-id> http --url "http://127.0.0.1:8080/openapi.json"
aimux add source <source-id> cli --commands '{"status":{"command":"git status","args":{}}}'
aimux rm source <source-id>

aimux add tool <consumer-id> <sourceId.toolName>
aimux rm tool <consumer-id> <sourceId.toolName>

Logs

aimux logs [consumer-id] [-n <lines>]

Per-consumer logs are written to .aimux/logs/<consumer-id>.log with format [timestamp] [level] [sourceId] message.

Development

Testing

npm test

You may also wish to explore ./demo/ for artefacts useful for manual or E2E testing.

HTTP endpoints

• Tool execution: http://127.0.0.1:2020/<consumer-id>/http/<sourceId.toolName> POST with JSON body for tool arguments
• OpenAPI spec: http://127.0.0.1:2020/<consumer-id>/http/openapi.json
• Interactive docs (SwaggerUI): http://127.0.0.1:2020/<consumer-id>/http/docs (SwaggerUI)
• SSE events: http://127.0.0.1:2020/<consumer-id>/http/events (pushes spec-changed on cherrypick, internal use only)

Admin endpoints

• POST /admin/reload - Re-reads runtime config and re-registers all consumers
• POST /admin/source-removed - Closes connections for a removed source

Architecture

• Daemon: Local background process (binds to 127.0.0.1 only)
• Runtime config: ~/.aimux/aimux.runtime.json - shared state between daemon and CLI commands
• Isolation: Each consumer is a separate sub-app, and has separate logs; crashed sources are automatically deregistered
• Performance: Proxy overhead < 5ms (excluding downstream execution)

Author

Brendan Graetz

Licence

MIT