Log inGet started

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:

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 source first. On the authorization screen, check All sources so the assistant can use sources you create later. This agent may create sources and This agent may move origin keys onto sources 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:

{
  "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

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:

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

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

Codex

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 sources. Every current and future source in this organization. On API sources, check Allow writes if the assistant may send methods other than GET, HEAD, and OPTIONS. You can approve this with no sources yet.
  • Specific sources. Only the sources you pick. The write opt-in appears per API source.
  • This agent may create sources. Owners and admins only. On by default. Untick it to refuse. Creates a durable API source 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 sources. 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.
  • This agent may read access logs. Owners and admins only. On by default. Untick it to refuse. The assistant can search the same entries as each granted source's Logs tab, including caller IPs and database statements. It stops working if you are no longer an owner or admin.

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

Database sources 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.

MCP sources have no write checkbox on this screen. On the source page, tools are grouped into read and write, and the checkboxes are the limit. Connectors you already installed follow that list, including sources they reach through a group. You do not reinstall the connector to change it.

Click Allow access. Change any of these later under Settings → Connected agents → Edit permissions, or disconnect there. Both take effect on the connector's next request, without reconnecting. Some assistants keep the tool list from the start of a chat, so newly allowed tools may only appear in a new one.

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 sources you granted, start sessions on them, and (on a database source) run the query tools those keys allow. If you ticked create, it can also admit an origin with create_source. 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. A session can last up to 7 days. When a key expires, the assistant starts a new session; it does not need you to approve anything again.

Try: list the sources I granted, reuse one if it fits, start a session, and call the source's endpoint instead of the origin.

On a managed source, 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 for the tools and how session keys work.

If a script or a committed skill should call a source without MCP, give it a Control API token so it mints its own short-lived access keys. See Refresh access tokens before they expire and Reuse one source across agent runs.

MCP servers through swarmvia

An MCP source puts a remote MCP server behind the swarmvia MCP server your agent already has, so there is one connection to add and one grant to review. The agent looks for that source with list_sources or find_sources before adding the server as its own client. The server's tools then appear in the agent's tool list under the source's name, such as linear_create_issue, each with the server's own read and write hints. If create_source is allowed, the agent can add a server itself by passing its URL as mcp_url.

Every source list_sources returns reports whether it can reach its upstream for you. When a source needs someone to connect an account, reconnect, or add a token, the agent gets a link to give you and calls connect_source to check once you have. The link opens swarmvia and needs you signed in; it never asks the agent for a token or password.

Next steps