# MCP server

## Introduction

The MCP server is `https://swarmvia.com/mcp`. How to add that URL in Cursor,
Claude, or another client is on [Agents](/docs/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-Swarmvia-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, groups, budget names, and concurrency. Optional `group` lists one group's pools. |
| `list_groups` | [Groups](/docs/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

- [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)