Log inGet started

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. After you approve the grant, the assistant can list sources, query a PostgreSQL or MySQL source, and start an HTTP session on an API source. It never receives the database password.

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

Session keys

When an assistant needs to query a database source, it uses source_schema, source_count_rows, source_query, and get_query_result. It never receives the password.

When an assistant needs to call an HTTPS origin, it starts a session. start_source_session returns the source's endpoint, a session key, and its expires_at. The key is a short-lived access token signed by swarmvia (sv_at_…). The assistant sends requests to that endpoint 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_sources and start_source_session return allowed / allowed_text so the assistant sees the grant list (GET *, then any extra method and its paths) even when the source 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 source (or all sources) on the consent screen. The assistant cannot grant itself more than you approved.

Keys default to a one-hour life. expires_in accepts 1h, 24h, or 7d; there is no key that never expires. The assistant reuses a key until it expires and does not need to end the session when the work finishes. It calls revoke_source_session only if the key leaked, for example into a file or a log.

Scripts and CI that call a source without MCP do not use session keys. They mint their own keys with a Control API token; see Refresh access tokens before they expire.

When a key expires, requests return 401 with access token expired. The assistant starts a new session for a fresh key. It does not need to ask you again: the grant you approved still covers the source.

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

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

Tools

Tool What it does
list_sources Call this when looking up an app, API, warehouse, or MCP server before adding another client for that app. Returns the sources this connector may use, each labeled with its backend (mcp, http, postgres, or mysql), plus purpose, groups, budget names, and concurrency. Optional group lists one group's sources.
find_sources The same source details, limited to sources whose name, purpose, or upstream host match a query.
list_groups Groups that sort this connector's sources by purpose, with each group's description and sources. Each source is labeled with its backend. Sources in no group are listed too. Listed only when the organization has groups.
create_source Admit an https origin, or an MCP server by its URL (mcp_url). Reuses a source that already fronts that host or server. Listed only when you tick This agent may create sources. 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 sources. Never takes a secret. The assistant POSTs the project's env key to intake_url, or gives you dashboard_url. Not for MCP sources, which own their credential: use connect_source.
start_source_session The source's endpoint, a short-lived session key (sv_at_…), and its expires_at. expires_in is 1h (default), 24h, or 7d.
revoke_source_session Revokes a session key at once. For a key that leaked, not for routine cleanup: keys expire on their own.
get_source_usage Requests, admitted share, and queue wait
search_source_logs A granted source's access-log entries, newest first, the same as its Logs tab: status, outcome, timing, caller IP, key or member, and the statement of a database query. Filters by time (from, to), outcome, status, request_kind, cache, and text (q). Pass cursor for older entries. Listed only when an owner or admin ticks This agent may read access logs, and only while they stay an owner or admin.
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 source_id attaches it and turns async on if that source is still sync. Listed only on a session grant.
set_source_webhooks Replace the destinations attached to a granted source. Empty list detaches all. Turns async on when at least one destination is attached. Listed only on a session grant.
connect_source Whether a source can reach its upstream for you, and the link to fix it when it cannot: connect an account, reconnect, or add a token. Listed on a session grant that reaches a managed source.

Database sources add these when the grant covers one:

Tool What it does
source_schema Tables and columns
source_count_rows How many rows a table (or filter) has
source_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

On an MCP source:

each of the server's tools is listed directly, named after the source: a source called linear turns the server's create_issue into linear_create_issue. Each keeps the server's own description, input schema and read-only or destructive hints, and takes a slot until the server answers.

When a source's tools cannot be listed directly (its account is not connected yet, or the connector's sources have more than 120 tools between them), that source is reached through two generic tools instead:

Tool What it does
source_list_tools The server's tools this connector may use, which are read-only, and input schemas on request
source_call_tool Call one of them. Takes a slot until the server answers.

All of these appear only on a session grant that reaches an MCP source. Which tools a connector may call is the source’s tool list, grouped into read and write on the source page. Checking a tool lets the connector call it, read or write. A read-only access key still calls only the checked tools the server marks read-only. Groups still decide which sources the connector can see. Changing the list does not require reconnecting the connector.

create_webhook and set_source_webhooks are owners and admins only. A session grant is enough. There is no extra consent checkbox. Access 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.

Connectors with Track work and memories also get the Work tools: issues, memories, handoffs and questions for you.

Assistants only see the tools their grant allows.

There is also a use_source 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. The migrate_mcp prompt moves the MCP servers in a harness config into MCP sources, one at a time, following Migrating MCP servers into swarmvia.

Related