# 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](/docs/agents). This page is what the
assistant can do after you approve the grant.

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 call an HTTP 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](/docs/credentials) 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, budget names, and concurrency |
| `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 |

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 |

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

- [Agents](/docs/agents) (the URL and how to connect)
- [Control API](/docs/api/control) (token auth for CI and scripts)
- [Access](/docs/pools/access) (pool keys and their method scopes)
- [Database pools](/docs/pools/database)