Account Pool MCP server

account-pool-mcp

An MCP server that hands out test accounts to agent sessions one at a time, so two sessions never end up logged into the same account.

The problem

When you run several agent sessions at once — say a few Claude sessions each driving their own Playwright browser — they all need to log in, and left alone they'll grab the same test account and step on each other. Two sessions on one account corrupt each other's state and your test results become meaningless. Picking a random account doesn't really help either: with 10 accounts and 5 sessions, a collision is already more likely than not.

The fix is to lease accounts. A session checks one out, uses it, and returns it. While it's checked out, no one else can be handed it.

How it works

The server keeps a pool of accounts in a small SQLite database and gives them out one at a time. Allocation happens inside a BEGIN IMMEDIATE transaction, so even if several sessions ask at the exact same moment, they can't be handed the same account. Each lease has a TTL, so if a session crashes without returning its account, it gets reclaimed automatically — there's nothing to clean up.

All of this happens in the background. The agent just asks for an account when it needs one; the broker decides which one it gets and guarantees no one else has it. There's no shared parent process — unrelated sessions coordinate purely through the database file.

Tools

lease_token. Hold it until you're done.

• lease_account(pool, holder?) — check out an account. Returns the account, its credentials, and a

• releaseaccount(leasetoken) — give it back. Idempotent.
• renewlease(leasetoken) — extend the lease if your work runs long (a heartbeat).
• pool_status(pool?) — what's leased vs. free. Never returns credential values.

There's also a small account-pool CLI (lease / release / renew / status) over the same database, for scripts and humans.

Setup

Want to see it first? bash examples/demo.sh runs a 60-second, no-install walkthrough — two sessions lease different accounts, a third is correctly refused, and the pool recovers on release.

It's on npm, so there's nothing to clone or build. Register it with your MCP client (e.g. .mcp.json) — npx fetches and caches it on first launch:

{
  "mcpServers": {
    "account-pool": {
      "command": "npx",
      "args": ["-y", "account-pool-mcp"],
      "env": {
        "APM_ACCOUNTS_FILE": "./accounts.json",
        "APM_DB_PATH": "./account-pool.db"
      }
    }
  }
}

Then define your pools in accounts.json (an id and a credentials blob per account):

{ "pools": { "realtor": [
  { "id": "realtor_01", "credentials": { "username": "qa01@example.com", "password": { "env": "REALTOR_01_PW" } } }
] } }

Want the CLI too? Run it ad-hoc with npx account-pool status, or install it on your PATH:

npm install -g account-pool-mcp     # adds `account-pool` (CLI) and `account-pool-mcp` (server)

Shortened. The full README is on GitHub.