acctmux

Status: 0.1.0, experimental. Tested mainly on Linux and used by the author. It is not yet a mature, independently audited product. See known limitations.

The problem

Many MCP servers expose one account per process. Connect two Google accounts, two Notion workspaces, or several API keys in multiple coding-agent sessions, and the naive setup duplicates both processes and tool schemas.

Without acctmux                         With acctmux

Claude Code ── server: work             Claude Code ┐
Claude Code ── server: personal         OpenCode    ├── acctmux ── worker: work
OpenCode    ── server: work             Codex       ┘             └─ worker: personal
OpenCode    ── server: personal                       one shared tool list
... every session × every account                   account="work" or "personal"

With eight client sessions and four real Google accounts, the latest benchmark measured 4,938 MB PSS across 32 processes for stock stdio versus 778 MB across five processes with acctmux. That's 6.3× less aggregate PSS in this workload. See the 2026-10-26 four-account benchmark for the full comparison and methodology.

Related MCP server: mcp-router

Install in 30 seconds

Requires Node.js 22 or newer.

npm install -g acctmux
acctmux init --preset google-workspace
acctmux

The initializer writes a starter config and a bearer token (file mode 600), refuses to overwrite an existing config, and prints connection snippets for Claude Code, OpenCode, and Codex. The Google preset expects the upstream executable on your PATH:

npm install -g @dguido/google-workspace-mcp

Authenticate the Google account or profiles with the upstream package before calling their tools. For other presets, use acctmux init --preset notion, tavily, or github, then add the account credential files described by the initializer and preset docs.

Connect Claude Code

claude mcp add --transport http acctmux \
  'http://[::1]:18704/mcp' \
  --header "Authorization: Bearer $(cat ~/.config/acctmux/token)"

For OpenCode and Codex, use the snippets printed by acctmux init. The endpoint is local-only by default; do not publish the port to a network.

What the model sees

Each tool gets an optional account argument whose enum lists the configured accounts. For example:

You:    Compare Drive storage on my work and personal accounts.
Model:  get_storage_quota(account="work")
        get_storage_quota(account="personal")

For upstreams where silently choosing a default account would be risky, set requireAccount: true to reject calls that omit the selector.

Features

Account selection is explicit, not round-robin, unless you configure a pool. Separate accounts often mean separate data and permissions; they are not interchangeable identities.

Architecture

A request follows this path:

1. Discover the configured accounts and currently available upstream tools.

2. Publish a combined tool list with an account selector and any configured policy.

3. Validate and route the selected account, applying pool selection where configured.

4. Spawn or reuse that account's stdio worker, then forward the MCP call.

5. Return the result and stop the worker after it has been idle long enough.

The router opens its endpoint before all upstreams have finished loading. Requests wait for initial loading within a configured deadline; when no upstream is ready, the router returns a retryable service error rather than hanging startup indefinitely. When accounts or late-loading upstreams change the tool surface, clients using the supported change-subscription flow can be notified.

Configuration

The default config path is ~/.config/acctmux/config.json. Override it with ACCTMUX_CONFIG. A complete minimal example is in config.example.json, and the configuration reference documents every key.

A small custom upstream example:

{
  "auth": { "tokenFile": "~/.config/acctmux/token" },
  "upstreams": [
    {
      "name": "notion",
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "accounts": {
        "work": { "env": { "NOTION_TOKEN": "ntn_work_token_here" } },
        "personal": { "env": { "NOTION_TOKEN": "ntn_personal_token_here" } }
      },
      "defaultAccount": "work",
      "requireAccount": true,
      "policy": {
        "personal": {
          "deny": ["API-patch-page", "API-post-page", "API-patch-block-children"]
        }
      }
    }
  ]
}

Use credential files or your own secret-injection mechanism for real tokens; do not commit secrets into JSON config. The example above shows the config shape, not a recommendation to store live tokens there.

Presets and examples

Preset versions are pinned where applicable. Presets are starting points; review upstream permissions and each policy before using them with real accounts.

Run as a service

• Linux / systemd user service: systemd/acctmux.service

• Docker: packaging/Dockerfile. The image contains the router, not your upstream servers; configure and provide those separately. The checked path uses a non-root user and a Unix socket.

• macOS / launchd: packaging/dev.acctmux.plist. The plist is linted in CI, but loading it under launchd is not yet tested.

Environment variables:

Benchmarks

These numbers are measurements, not performance promises. The full reports explain the environment, methodology, repeated runs, and limitations.

Aggregate process-tree memory

Eight client sessions, four real Google accounts, Google Workspace MCP upstream. The latest report is 2026-10-26:

These memory figures come from the 2026-10-26 run with four real, logged-in Google accounts. They are not directly comparable with the credential-free 2026-10-25 re-run, where upstream workers did not instantiate Google API clients. The native HTTP workspace-mcp implementation exposes 38 tools rather than the Google Workspace upstream's 54, so its feature surface differs. The workspace-mcp behind acctmux row measures that alternate upstream behind the router.

Latency and tool surface

The 2026-10-26 four-account live run measured session start at 2.3 ms for acctmux versus 767 ms for stock stdio. Warm calls were 386 ms versus 388 ms, respectively. Google API latency dominates the warm-call time, so the main difference is process reuse and tool-surface size rather than faster upstream API execution.

• Latest benchmark: 2026-10-26, four real Google accounts

• Benchmark report: 2026-10-23, original live-account run

• Benchmark report: 2026-10-25, credential-free re-run

• Reproduce with node scripts/bench.mjs; see the report for setup and exact commands.

Tested with

The first two have dedicated benchmark/interop evidence; the final three are the author's deployment examples, not a claim of broad production validation. Other upstreams may work, but are untested.

Security

• acctmux init creates a bearer token by default. The token file is mode 600; group/world-readable token files are refused.

• Requests without a valid token are rejected before the body is read. Token comparison uses constant time.

• TCP binds to loopback only (::1 by default, or 127.0.0.1 when configured). An optional Unix socket can be used instead or as well; its directory and socket permissions matter.

• Requests with an Origin header, a non-loopback Host, or a content type other than application/json are rejected.

• Request bodies are capped at 32 MiB by default.

• Child processes receive an allowlisted environment, with configured account and service variables added.

• The router does not read upstream credential stores. It does read its own bearer-token file and, for usage-aware pools, configured key files used only for the configured usage URL.

• Per-account allow/deny policy is a useful guardrail, not a replacement for upstream credentials, least privilege, or client-side review.

Generate a token manually if needed:

install -d -m 700 ~/.config/acctmux
openssl rand -hex 32 > ~/.config/acctmux/token
chmod 600 ~/.config/acctmux/token

See SECURITY.md for reporting vulnerabilities and Architecture: trust boundaries for implementation details.

Related projects

The MCP ecosystem moves quickly, and the projects below solve overlapping but different problems. This is a short orientation, not a leaderboard.

• Claude Code and OpenCode are coding agents that can connect to MCP servers; acctmux sits behind the client as a local server router.

• mohanagy/miftah is a multi-account credential broker with profile management and credential-handling features. Its profile-selection model differs from acctmux's per-call selector.

• mcp-account-router focuses on failover across ordered profiles and a limited read-only tool set.

• supergateway and mcp-proxy bridge or proxy MCP transports; their process and tool-surface trade-offs are included in the benchmark reports.

• Model Context Protocol is the protocol acctmux routes.

Choose the tool that fits the trust model and deployment. If native multi-account support in an upstream already solves your use case, a second router may not be necessary.

Development

Clone the repository and install dependencies:

git clone https://github.com/AmanKRoy/acctmux.git
cd acctmux
npm ci
npm test
npm run lint

The test suite uses a fake upstream and does not require Google, Notion, GitHub, or Tavily credentials. CI covers Node.js 22 and 24, and runs on macOS as well as Linux-specific checks where available.

Contributions and bug reports are welcome. Read CONTRIBUTING.md first. For security issues, use private vulnerability reporting as described in SECURITY.md, not a public issue.

Documentation

• Configuration reference

• Architecture and design decisions

• Known limitations and alternatives

• Benchmarks and methodology

• Setup guide for AI agents

• Review log

• Roadmap

• Changelog

License

Apache-2.0. See LICENSE and NOTICE.