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.

Related MCP server: Files MCP Server

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_account(pool, holder?) — check out an account. Returns the account, its credentials, and a lease_token. Hold it until you're done.

• release_account(lease_token) — give it back. Idempotent.

• renew_lease(lease_token) — 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

cp examples/accounts.example.json accounts.json     # define your pools
# then register the server with your MCP client — see examples/claude-mcp-config.json

Point every session's APM_DB_PATH at the same file — that shared file is how they coordinate.

A credential value can be { "env": "VAR_NAME" } instead of a literal, so real secrets stay in the environment and out of the accounts file.

Security

These are test accounts, not a secrets vault. Credential values are never logged or returned by pool_status — a redacting logger masks them, and all logs go to stderr so they can't corrupt the MCP stream. Keep accounts.json and *.db out of git (only the .example files are committed). The stdio server trusts whoever runs it locally, so don't point it at production credentials.

Limitations

Single host for now: coordination is through one SQLite file, so all sessions have to share a filesystem. The storage layer is isolated behind one module, so a Postgres or Redis backend could swap in later for multi-host coordination without changing the tools.