nthbouncer
Log inGet started

MCP server

Introduction

The MCP server is https://nthbouncer.com/mcp. How to add that URL in Cursor, Claude, or another client is on Agents. After you approve the grant, the assistant can list pools, query PostgreSQL or MySQL through the pool, and start an HTTP session when a pool fronts an API. It never receives the database password.

MCP never admits traffic on the proxy, and pool keys never call MCP tools. They are separate credentials with separate jobs.

Session keys

When an assistant needs to query a database pool, it uses pool_schema, pool_count_rows, pool_query, and get_query_result. It never receives the password.

When an assistant needs to call an HTTPS origin, it starts a session. That returns the pool's base URL, a key, and an expiry. It sends requests to that base URL with the key in X-Nthpool-Key, keeping the path and query it would have used against the origin.

Session keys default to read-only. list_pools and start_pool_session return allowed / allowed_text so the assistant sees the grant list (GET *, then any extra method and its paths) even when the pool description does not mention it. Anything else is refused with 403 before the request leaves our edge. If the work genuinely writes, check Allow writes for that pool (or all pools) on the consent screen. The assistant cannot grant itself more than you approved.

Keys default to a one-hour life. Call end_pool_session when the work finishes so the key stops working immediately.

On a managed pool, the assistant never receives your origin's credential. It goes to the pool URL with the session key, and the upstream credential is added at our edge.

On a pass-through pool there is nothing to hide. The caller supplies the upstream credential itself, so assistants working with pass-through pools still need it.

Tools

Tool What it does
list_pools Pools this connector may use, their purpose, groups, budget names, and concurrency. Optional group lists one group's pools.
list_groups Groups that sort this connector's pools by purpose, with each group's description and pools. Listed only when the organization has groups.
create_pool Admit an https origin. Reuses a pool that already fronts that host. Listed only when you tick This agent may create pools. Never takes a secret.
adopt_connection Prepare managed auth and return a one-shot intake. Listed only when you tick This agent may move origin keys onto pools. Never takes a secret. The assistant POSTs the project's env key to intake_url, or gives you dashboard_url.
start_pool_session Pool base URL, a short-lived key, and an expiry
end_pool_session Revokes that key early
get_pool_usage Requests, admitted share, and queue wait
list_webhooks Destinations in this organization. No signing secrets. Listed only on a session grant.
create_webhook Create an https destination. Returns the signing secret once (whsec_…). Optional pool_id attaches it and turns async on if that pool is still sync. Listed only on a session grant.
set_pool_webhooks Replace the destinations attached to a granted pool. Empty list detaches all. Turns async on when at least one destination is attached. Listed only on a session grant.

Database pools add these when the grant covers one:

Tool What it does
pool_schema Tables and columns
pool_count_rows How many rows a table (or filter) has
pool_query Run a read-only query. Slow queries can return a handle instead of rows.
get_query_result Page a query that returned a handle

create_webhook and set_pool_webhooks are owners and admins only. A session grant is enough. There is no extra consent checkbox. Pool keys cannot call these tools.

Store the signing secret on the receiver when create_webhook returns it. It is shown once. Do not ask the user to paste an origin secret.

Assistants only see the tools their grant allows.

There is also a use_pool prompt, which writes the few lines to add to a repo's AGENTS.md or CLAUDE.md so later sessions skip discovery. Ask for it once per project and commit the result.

Related