Migrating MCP servers into swarmvia

A swarmvia MCP pool fronts one remote MCP server. The pool is the server's client: it holds the OAuth connection or token, and callers reach the tools through the swarmvia MCP server with pool_list_tools and pool_call_tool. The harness keeps one MCP entry, swarmvia, instead of one per server.

Move one server at a time. Report first, change nothing until the human agrees, and never move a secret through chat or an MCP argument.

1. Inventory

Read every config the harness uses. Project files override user files.

Harness	Files	Servers live under
Cursor	.cursor/mcp.json, ~/.cursor/mcp.json	mcpServers.<name>: url + headers, or command + args
Claude Code	.mcp.json, ~/.claude.json (top-level mcpServers, and projects["<path>"].mcpServers)	mcpServers.<name>: type http/sse + url + headers, or command
VS Code	.vscode/mcp.json, the user profile mcp.json	servers.<name>: type is required. Secrets come from inputs (${input:id})
Codex	.codex/config.toml, ~/.codex/config.toml	[mcp_servers.<name>]: url, bearer_token_env_var, http_headers, or command
Claude Desktop	claude_desktop_config.json (macOS ~/Library/Application Support/Claude/, Windows %APPDATA%\Claude\)	stdio only. Remote servers appear as npx mcp-remote <url>. Connectors added in Settings are not in the file: ask the human to list them
Windsurf	~/.codeium/windsurf/mcp_config.json	mcpServers.<name>.serverUrl
Gemini CLI	.gemini/settings.json, ~/.gemini/settings.json	mcpServers.<name>: httpUrl (streamable HTTP) or url (SSE)

For each server, note its name, the file, the URL, and how it authenticates: none, OAuth in the harness, or a static header. Write a header as Authorization (set). Never copy a token value into the report.

2. Verdicts

Verdict	When
Migrate	A public https:// MCP server. Includes a stdio mcp-remote https://… wrapper: migrate the URL inside it.
Migrate, token	Same, but it sends a static token header. The pool gets the token from the human on the pool page, not from you.
Keep local	A stdio server that runs a local process (filesystem, git, shell, browser, docker). Any localhost, 127.0.0.1, *.local, or private-network URL. A pool cannot reach them.
Skip	swarmvia itself. A server a granted pool already fronts: go straight to cut-over.

SSE-only servers (type: sse, Gemini url, a path ending in /sse) usually also serve streamable HTTP, often at /mcp on the same host. Try that URL. If create_pool says it did not answer an MCP initialize request, Keep.

For servers that act as a person (Linear, Notion, GitHub, Sentry), ask the human: one shared account for everyone, or each member connects their own? Each member is each_member_connects: true, and calls act as whoever calls.

Show the table and wait for the human to agree.

3. Move one server

1. Add the swarmvia MCP server if this session cannot call its tools. URL: https://swarmvia.com/mcp.
2. list_pools. A pool whose mcp_server.url matches is a reuse. Skip to step 4.
3. create_pool with mcp_url (and each_member_connects if chosen). It needs This agent may create pools and an owner or admin. It reuses a pool that already fronts the server. If it says the server needs an OAuth app (GitHub does), a team admin creates the pool in the dashboard (New pool → MCP server) with that app's client ID and secret. Wait, then list_pools again.
4. Authorize. Read the pool's auth block, or call connect_pool.
   • ready or not_needed: go on.
   • connect_required, reconnect_required, or needs_credential: give the human the url. They connect the account, or paste the server's token on that page. Call connect_pool again when they say done.
   • who_can_fix: a team admin: tell the human an admin has to do it. Never ask for the token, never read it out of the old config to send, and never pass one to adopt_connection. MCP pools own their credential, so adopt_connection refuses them.
5. Verify. pool_list_tools should show the tools the harness had. If some are missing, an admin trimmed the pool's tool list; say so. Call one read-only tool with pool_call_tool and show the result.

4. Cut over

Only after step 3 passes for that server.

1. Back up each file you touch next to it (mcp.json.bak). Show the diff. Remove only that server's entry. Leave the others and the swarmvia entry.
   • Claude Code: claude mcp remove <name> -s <scope> also works.
   • Codex: codex mcp remove <name>.
   • Claude Desktop connectors: the human removes them in Settings.
2. If a token for that server now lives only on the pool, tell the human they can delete the old one from .env or the harness inputs. Do not delete it for them.
3. Run the use_pool prompt for the pool and offer its lines for AGENTS.md (or CLAUDE.md, .cursor/rules). Future sessions then call pool_call_tool(pool_id, name, arguments) instead of the old tool names.
4. The harness reloads MCP config on restart. Say so.

To roll back, restore the backup. The pool can stay.

Limits

• Tools only. Resources and prompts from the server do not pass through.
• A tool call holds one of the pool's concurrency slots until the server answers, and fails with request_timeout past the pool's request timeout. Keep servers whose tools run for minutes local.
• Creating a pool uses a plan slot. Prefer reuse.