# nthbouncer

> A concurrency governor for APIs with a hard limit. Admit N in flight.

## When to use nthbouncer

Use nthbouncer when an AI agent, script, or team needs shared access to an HTTPS API or PostgreSQL database **without** handing out the upstream credential, and the origin cannot take unlimited concurrent traffic.

Good fits:

- Claude, Cursor, or another MCP client that should call your warehouse, vendor API, or internal service through a pool
- CI jobs that mint pool keys and respect the same concurrency limit as humans
- NetSuite, Stripe, or any SaaS API where one account-wide concurrency cap must be shared fairly

Not a fit when you only need API documentation hosting, a generic HTTP cache, or a replacement for your identity provider.

## Get started (agents)

1. Sign up at https://nthbouncer.com/register — 250,000 free requests, no credit card.
2. Create a pool in the dashboard and point it at your origin.
3. Add the MCP server URL `https://nthbouncer.com/mcp` in Cursor or Claude (OAuth — no token to paste).
4. Or mint a Control API token under Organization settings and call `https://nthbouncer.com/api/v1/*`.

## Machine-readable surfaces

- [OpenAPI spec](https://nthbouncer.com/docs/api/openapi.json): Control API for pools, keys, budgets, and metrics
- [MCP manifest](https://nthbouncer.com/.well-known/mcp.json): Streamable HTTP MCP at `https://nthbouncer.com/mcp`
- [Sitemap](https://nthbouncer.com/sitemap.xml): Public pages and docs
- [Agents guide](https://nthbouncer.com/docs/agents.md): MCP setup for Cursor and Claude
- [CLI](https://www.npmjs.com/package/@nthbouncer/cli): `npx @nthbouncer/cli` for scripts

## Contact

- Email: sales@nthbouncer.com
- [Contact page](https://nthbouncer.com/contact)

## Docs

- [Welcome to nthbouncer](https://nthbouncer.com/docs/intro.md): A concurrency governor for APIs with a hard limit. Admit N in flight.
- [Quickstart](https://nthbouncer.com/docs/quickstart.md): Create a pool, mint a key, and proxy your first request.
- [Pools](https://nthbouncer.com/docs/pools.md): Dedicated proxy endpoints with a hard concurrency limit: hostnames, headers, and status codes.
- [Concurrency](https://nthbouncer.com/docs/pools/concurrency.md): Limits, queues, RPM, retries, and response cache.
- [Access](https://nthbouncer.com/docs/pools/access.md): Pool keys, inbound HMAC, origin verification, JWT, Cloudflare Access, and IP policies.
- [Logs](https://nthbouncer.com/docs/pools/logs.md): Access logs and request tags.
- [Metrics](https://nthbouncer.com/docs/pools/metrics.md): Admit, queue, and reject counts for a pool.
- [Settings](https://nthbouncer.com/docs/pools/settings.md): Origins, custody mode, and pool identity.
- [Async](https://nthbouncer.com/docs/pools/async.md): 202 admission, poll URLs, and modes under the same concurrency limit.
- [Database pools](https://nthbouncer.com/docs/pools/database.md): Governed SQL over HTTP: query a Postgres database through a pool, with no credential in anyone's hands.
- [Credentials](https://nthbouncer.com/docs/credentials.md): Managed upstream secrets encrypted at the edge.
- [Capacity](https://nthbouncer.com/docs/capacity.md): Named shared concurrency limits with member allocations. Attach existing pools.
- [Balancing](https://nthbouncer.com/docs/capacity/balancing.md): Fixed vs Auto: pinned reservations and borrowed float under one origin concurrency limit.
- [Agents](https://nthbouncer.com/docs/agents.md): Connect Claude or Cursor at https://nthbouncer.com/mcp. Approve pools, then disconnect from Settings.
- [MCP server](https://nthbouncer.com/docs/mcp.md): Tools, session keys, and what a connected assistant can reach after you approve the grant.
- [Domains](https://nthbouncer.com/docs/domains.md): Serve a pool on your own hostname with DNS and TLS.
- [IP Policies](https://nthbouncer.com/docs/ip-policies.md): Named caller IP allowlists attached to pools by reference.
- [Webhooks](https://nthbouncer.com/docs/webhooks.md): Signed outbound callbacks when async jobs finish.
- [Billing](https://nthbouncer.com/docs/billing.md): Plans, upgrades and downgrades, proration, overage, and spend caps.
- [API](https://nthbouncer.com/docs/api.md): Edge lock API and control-plane Control API (budgets, pools, keys, MCP).
- [Concurrency locks](https://nthbouncer.com/docs/api/locks.md): Acquire, renew, and release a pool concurrency slot on api.nthpool.cloud.
- [Control API](https://nthbouncer.com/docs/api/control.md): Token-authenticated budgets, pools, TTL pool keys, and Metrics for CI and scripts.
- [Knowledge base](https://nthbouncer.com/docs/knowledge-base.md): Cookbooks for NetSuite, Amazon SP-API, agents, Capacity, locks, cache, admission errors, waiting rooms, and 429 spikes.
- [nthbouncer vs API gateways](https://nthbouncer.com/docs/knowledge-base/vs-api-gateways.md): How a concurrency governor differs from Kong, AWS API Gateway, and similar gateways.
- [Configure Cloudflare Zero Trust](https://nthbouncer.com/docs/knowledge-base/cloudflare-zero-trust.md): Require Cloudflare Access JWTs on pool calls with team domain and application AUD.
- [Proxy NetSuite under a concurrency limit](https://nthbouncer.com/docs/knowledge-base/netsuite-rest.md): Pin NetSuite origins, attach TBA, and share one concurrency budget.
- [Front Amazon SP-API](https://nthbouncer.com/docs/knowledge-base/amazon-sp-api.md): One LWA app and refresh token, many pool keys, pinned to a regional SP-API host.
- [Reuse one pool across agent runs](https://nthbouncer.com/docs/knowledge-base/agent-pools.md): Reuse an existing pool, mint a short-lived key, and hand agents a skill.
- [Give a data team Claude access to Postgres](https://nthbouncer.com/docs/knowledge-base/claude-your-warehouse.md): Stand up a database pool: the read role, the connectivity check, the concurrency limit, and per-person revocation.
- [Long NetSuite writes without client timeouts](https://nthbouncer.com/docs/knowledge-base/async-netsuite-writes.md): Use async admission and signed webhooks for slow writes under the concurrency limit.
- [Share one origin across several pools](https://nthbouncer.com/docs/knowledge-base/capacity-auto.md): One origin concurrency limit, pinned reservations, and Auto so float follows load.
- [Why a pool borrowed slots](https://nthbouncer.com/docs/knowledge-base/capacity-borrow.md): Read pinned and borrowed slots on an Auto capacity budget.
- [Opt a GET into the response cache](https://nthbouncer.com/docs/knowledge-base/response-cache.md): Skip admission and upstream on repeated GETs with X-Nthpool-Cache-TTL.
- [Acquire a concurrency lock without proxying](https://nthbouncer.com/docs/knowledge-base/concurrency-lock.md): Use the lock API when your client must call the upstream itself.
- [Determine a request came from the proxy](https://nthbouncer.com/docs/knowledge-base/origin-verification.md): Verify outbound HMAC signatures so the origin rejects direct traffic.
- [Understand admission errors](https://nthbouncer.com/docs/knowledge-base/admission-errors.md): Decode 401, 429, 504, and other pool responses before the upstream runs.
- [Diagnose a 429 spike](https://nthbouncer.com/docs/knowledge-base/diagnose-429-spike.md): Use Metrics and Logs to find who burned the concurrency limit.
- [See admits, queues, and rejects without exporting logs](https://nthbouncer.com/docs/knowledge-base/capacity-proof.md): Use Metrics admit, queue, and reject series instead of NDJSON dumps.