{
  "markdown": "# account-pool-mcp\n\n[![npm version](https://img.shields.io/npm/v/account-pool-mcp.svg)](https://www.npmjs.com/package/account-pool-mcp)\n[![npm downloads](https://img.shields.io/npm/dw/account-pool-mcp.svg)](https://www.npmjs.com/package/account-pool-mcp)\n[![CI](https://github.com/ankitsxchdeva/account-pool-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ankitsxchdeva/account-pool-mcp/actions/workflows/ci.yml)\n[![license](https://img.shields.io/npm/l/account-pool-mcp.svg)](./LICENSE)\n[![Model Context Protocol](https://img.shields.io/badge/MCP-server-blue.svg)](https://modelcontextprotocol.io)\n[![Glama score](https://glama.ai/mcp/servers/ankitsxchdeva/account-pool-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ankitsxchdeva/account-pool-mcp)\n\nAn MCP server that hands out test accounts to agent sessions one at a time, so two sessions never\nend up logged into the same account.\n\n![account-pool-mcp demo: two sessions lease different accounts, a third is refused, the pool recovers on release](https://raw.githubusercontent.com/ankitsxchdeva/account-pool-mcp/main/docs/demo.gif)\n\n## The problem\n\nWhen you run several agent sessions at once — say a few Claude sessions each driving their own\nPlaywright browser — they all need to log in, and left alone they'll grab the same test account and\nstep on each other. Two sessions on one account corrupt each other's state and your test results\nbecome meaningless. Picking a random account doesn't really help either: with 10 accounts and 5\nsessions, a collision is already more likely than not.\n\nThe fix is to lease accounts. A session checks one out, uses it, and returns it. While it's checked\nout, no one else can be handed it.\n\n## How it works\n\nThe server keeps a pool of accounts in a small SQLite database and gives them out one at a time.\nAllocation happens inside a `BEGIN IMMEDIATE` transaction, so even if several sessions ask at the\nexact same moment, they can't be handed the same account. Each lease has a TTL, so if a session\ncrashes without returning its account, it gets reclaimed automatically — there's nothing to clean up.\n\nAll of this happens in the background. The agent just asks for an account when it needs one; the\nbroker decides which one it gets and guarantees no one else has it. There's no shared parent process\n— unrelated sessions coordinate purely through the database file.\n\n## Tools\n\n- `lease_account(pool, holder?)` — check out an account. Returns the account, its credentials, and a\n  `lease_token`. Hold it until you're done.\n- `release_account(lease_token)` — give it back. Idempotent.\n- `renew_lease(lease_token)` — extend the lease if your work runs long (a heartbeat).\n- `pool_status(pool?)` — what's leased vs. free. Never returns credential values.\n\nThere's also a small `account-pool` CLI (`lease` / `release` / `renew` / `status`) over the same\ndatabase, for scripts and humans.\n\n## Setup\n\nWant to see it first? `bash examples/demo.sh` runs a 60-second, no-install walkthrough — two sessions\nlease different accounts, a third is correctly refused, and the pool recovers on release.\n\nIt's on [npm](https://www.npmjs.com/package/account-pool-mcp), so there's nothing to clone or build.\nRegister it with your MCP client (e.g. `.mcp.json`) — `npx` fetches and caches it on first launch:\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"account-pool\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"account-pool-mcp\"],\n      \"env\": {\n        \"APM_ACCOUNTS_FILE\": \"./accounts.json\",\n        \"APM_DB_PATH\": \"./account-pool.db\"\n      }\n    }\n  }\n}\n```\n\nThen define your pools in `accounts.json` (an `id` and a credentials blob per account):\n\n```json\n{ \"pools\": { \"realtor\": [\n  { \"id\": \"realtor_01\", \"credentials\": { \"username\": \"qa01@example.com\", \"password\": { \"env\": \"REALTOR_01_PW\" } } }\n] } }\n```\n\nWant the CLI too? Run it ad-hoc with `npx account-pool status`, or install it on your PATH:\n\n```bash\nnpm install -g account-pool-mcp     # adds `account-pool` (CLI) and `account-pool-mcp` (server)\n```\n\nPoint every session's `APM_DB_PATH` at the same file — that shared file is how they coordinate.\n\n| Env var | Default | What it does |\n|---|---|---|\n| `APM_ACCOUNTS_FILE` | `./accounts.json` | Pools + accounts to load on startup. |\n| `APM_DB_PATH` | `./account-pool.db` | The SQLite file. Same path for every session. |\n| `APM_DEFAULT_TTL_SECONDS` | `1800` | How long a lease lasts before it's reclaimable. |\n| `APM_LEASE_WAIT_MS` | `0` | `0` = fail fast when the pool is empty; `>0` = wait this long for one to free up. |\n\nA credential value can be `{ \"env\": \"VAR_NAME\" }` instead of a literal, so real secrets stay in the\nenvironment and out of the accounts file.\n\n## Making your agent reach for it automatically\n\nThe server ships **agent instructions** in the MCP handshake — clients like Claude Code, Cursor, and\nWindsurf inject them into context, so the agent knows to call `lease_account` before logging in\nwithout being told each time. The tool descriptions reinforce it (lease is exclusive; you *must*\nrelease).\n\nFor the most reliable pickup, also add a line to your project's own rules file\n(`CLAUDE.md`, `.cursor/rules/`, `.windsurfrules`) so the agent's instructions and the server's\ninstructions agree:\n\n```md\n## Test accounts\nThis repo has account-pool-mcp configured. Before logging into any test account in a QA or\nPlaywright run, call `lease_account` to check one out, and `release_account` when done.\nNever hard-code, guess, or reuse an account — one account per session at a time.\n```\n\n## Security\n\nThese are test accounts, not a secrets vault. Credential values are never logged or returned by\n`pool_status` — a redacting logger masks them, and all logs go to stderr so they can't corrupt the\nMCP stream. Keep `accounts.json` and `*.db` out of git (only the `.example` files are committed). The\nstdio server trusts whoever runs it locally, so don't point it at production credentials.\n\n## Limitations\n\nSingle host for now: coordination is through one SQLite file, so all sessions have to share a\nfilesystem. The storage layer is isolated behind one module, so a Postgres or Redis backend could\nswap in later for multi-host coordination without changing the tools.\n",
  "bytes": 6179,
  "sha": "b00bfd70ce7649c17a788aba703c147b51bd5a82ac36508b69de6567bddc2db2",
  "repo_slug": "ankitsxchdeva/account-pool-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ankitsxchdeva_account_pool_mcp_789845cf/readme"
}