# Agents

## Introduction

Agents work from your real tables and columns for more accurate results, and
they never receive the database password.

The MCP URL is:

```text
https://swarmvia.com/mcp
```

There is no token to paste. You can copy the same URL from **Settings →
Connected agents**, which also walks through each client. Self-hosted
installs use `/mcp` on your own host.

You need a swarmvia account. You do not need a pool first. On the
authorization screen, check **All pools** so the assistant can use pools you
create later. **This agent may create pools** and **This agent may move
origin keys onto pools** are on for owners and admins unless you untick
them. Create admits an origin URL. Onboard lets the assistant POST a key
the project already has, or give you a paste page. It will never ask you
to type the secret in chat.

## Pick your agent

### Cursor

Create `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every
project:

```json
{
  "mcpServers": {
    "swarmvia": {
      "type": "http",
      "url": "https://swarmvia.com/mcp"
    }
  }
}
```

Save the file. Cursor opens a browser for authorization. Do not add a token or
an `Authorization` header.

You can also paste the URL under **Cursor Settings → Tools & MCP**.

### Claude Code

```bash
claude mcp add --transport http swarmvia https://swarmvia.com/mcp
```

The first tool call opens the authorization screen.

### Visual Studio Code

Create `.vscode/mcp.json` in the workspace. VS Code uses `servers`, not
`mcpServers`:

```json
{
  "servers": {
    "swarmvia": {
      "type": "http",
      "url": "https://swarmvia.com/mcp"
    }
  }
}
```

Save, then start the server from the CodeLens and finish authorization in
the browser.

### Codex

```bash
codex mcp add swarmvia --url https://swarmvia.com/mcp
```

The first tool call opens the authorization screen.

### Other clients

Add a custom connector (Claude.ai) or a remote MCP server and paste
`https://swarmvia.com/mcp`. Any client that speaks streamable HTTP MCP and
OAuth 2.1 will work.

## Approve the grant

Your browser opens swarmvia. Choose:

- **All pools.** Every current and future pool in this organization. On HTTP
  pools, check **Allow writes** if the assistant may send methods other than
  `GET`, `HEAD`, and `OPTIONS`. You can approve this with no pools yet.
- **Specific pools.** Only the pools you pick. The write opt-in appears per
  HTTP pool.
- **This agent may create pools.** Owners and admins only. On by default.
  Untick it to refuse. Creates a durable HTTP pool that uses a plan slot,
  then onboards the origin key. The assistant passes the origin URL it
  already calls. It is never asked to type the secret in chat.
- **This agent may move origin keys onto pools.** Owners and admins only.
  On by default with create. Untick it to refuse origin-key write. The
  assistant may POST a key the project already has, or give you a paste
  page. It will never ask you to type the secret in chat.

A session grant can also create webhook destinations and attach them to a
granted pool (and turn async on if that pool is still sync). That uses the
same owner or admin permission as the dashboard. There is no extra checkbox.

Database pools have no separate write gate. Writes stay blocked on HTTP unless
you allow them. Prefer leaving writes off unless the work must change data at
the origin.

Click **Allow access**. Review or disconnect later under **Settings → Connected
agents**. Disconnecting takes effect immediately.

One connector authorizes one organization. To connect a second organization,
add the URL as a second connector. Re-adding a connector always shows the
consent screen, so you can widen or narrow the grant without disconnecting
first.

## After you connect

The assistant can list the pools you granted, start and end session keys on
them, and (on a database pool) run the query tools those keys allow. If you
ticked create, it can also admit an origin with `create_pool`. If you ticked
adopt, it can prepare managed auth with `adopt_connection` and POST the
project's existing key to a one-shot intake — never as an MCP argument.
Session keys default to one hour and to read-only methods.

Try: list the pools I granted, reuse one if it fits, start a session, and
call through the pool URL instead of the origin.

On a [managed](/docs/credentials) pool, the origin credential is attached at
our edge. The assistant gets a URL and a timer, never the secret. Prefer
managed custody for anything an assistant touches.

See [MCP server](/docs/mcp) for the tools and how session keys work.

If a script or a committed skill should call a pool without MCP, mint a
[pool key](/docs/pools/access) and see
[Reuse one pool across agent runs](/docs/knowledge-base/agent-pools).

## Next steps

- [MCP server](/docs/mcp)
- [Database pools](/docs/pools/database)
- [Give a data team Claude access to Postgres](/docs/knowledge-base/claude-your-warehouse)
- [Reuse one pool across agent runs](/docs/knowledge-base/agent-pools)
- [Control API](/docs/api/control) (CI and scripts, not assistants)