Skip to main content
Beyond the built-in actions and first-party integrations, you can add any MCP server to OpenSwarm — either from the public MCP registry or by manually configuring a custom server.

​
The MCP Registry

OpenSwarm includes a built-in MCP registry browser that aggregates servers from two sources:
  • Community — the official Model Context Protocol registry, containing hundreds of community-contributed servers
  • Google — Google’s catalog of MCP servers for their Cloud and Workspace services
The registry is cached locally and refreshed every hour in the background. GitHub star counts are fetched and cached alongside each server entry.

​
Browsing the Registry

Open the registry from New Action → Browse MCP Registry in the Action Library. You can:
  • Search by name, title, description, or keywords
  • Filter by source (Community or Google)
  • Sort by name or GitHub stars
  • Load more results with pagination (20 servers per page)
Each server card shows its name, description, star count, source badge, and links to the repository/website.

​
Installing from the Registry

Click Install on any server to add it as an action. What happens next depends on the server type:
OpenSwarm automatically derives the MCP config from the repository URL (e.g., npx -y github:owner/repo) and installs it immediately. Tool discovery runs automatically after install.

​
Adding a Custom MCP Server

If your server isn’t in the registry, use New Action → Create Custom to add it manually. You need to provide:
  • Name — a display name for the action
  • Description — what the server does
  • Command — the shell command to run (for stdio servers)
After creation, you can edit the tool’s MCP config to set the full connection details.

​
MCP Config Structure

Every MCP action has an mcp_config that tells OpenSwarm how to connect. The three supported transport types:

​
stdio

The server runs as a local subprocess. OpenSwarm spawns it and communicates over stdin/stdout. 
{
  "type": "stdio",
  "command": "npx",
  "args": ["-y", "@checkra1n/xbird"],
  "env": {
    "SOME_API_KEY": "your-key"
  }
}
OpenSwarm resolves commands against PATH and common user-local bin directories — including ~/.bun/bin, ~/.cargo/bin, ~/.local/bin, ~/.volta/bin, nvm/fnm node versions, and /opt/homebrew/bin. You don’t need to specify absolute paths.

​
http (Streamable HTTP)

The server exposes a single HTTP endpoint that accepts JSON-RPC POST requests. 
{
  "type": "http",
  "url": "https://mcp.example.com/v1",
  "headers": {
    "Authorization": "Bearer your-token"
  }
}

​
sse (Server-Sent Events)

The legacy SSE transport — the server exposes a GET endpoint for event streams and a POST endpoint for messages. 
{
  "type": "sse",
  "url": "https://mcp.example.com/sse",
  "headers": {
    "Authorization": "Bearer your-token"
  }
}
When connecting to an http server, OpenSwarm tries Streamable HTTP first. If that fails, it automatically falls back to SSE transport.

​
Tool Discovery

After installing an MCP server, OpenSwarm runs tool discovery — it connects to the server, sends an initialize handshake, and calls tools/list to enumerate all available actions. Discovery does three things:
  1. Enumerates tools — gets the name, description, and input schema for every action the server supports
  2. Categorizes actions — automatically classifies each action as read or write based on its name prefix:
    • Read prefixes: get, list, read, search, fetch, find, query, browse, check, describe, show, download, analyze, explain
    • Write prefixes: create, write, delete, update, send, remove, modify, add, set, put, post, insert, move, copy, rename
  3. Groups by service — maps actions to logical services (e.g., Gmail, Calendar, Drive) and provider groups (e.g., Google, Twitter, Reddit) for organized permission management
You can re-run discovery at any time by clicking the refresh button on an installed action. This is useful after a server updates its available tools.

​
Credential Injection

OpenSwarm automatically injects credentials into MCP server connections based on transport type:
TransportAuth TypeHow Credentials Are Injected
stdioenv_varsCredentials are set as environment variables in the subprocess
stdiooauth2OAuth access token set as OAUTH_ACCESS_TOKEN env var. Refresh token, client ID, and client secret also injected.
http / sseenv_varsCredentials with key names like authorization or api_key are set as Authorization: Bearer headers
http / sseoauth2OAuth access token set as Authorization: Bearer header
For stdio servers, OpenSwarm also augments the PATH environment variable to include common package manager bin directories, ensuring commands like npx, bunx, and uvx resolve correctly even in packaged app environments.