MCP server

Most of the REST API is exposed to AI agents over the Model Context Protocol. Generate an MCP key on the Access tokens page in Swarmhit (the MCP Server card), then connect any MCP client (Claude, ChatGPT, Clay, n8n, Make) to the Streamable HTTP endpoint:

https://app.swarmhit.com/mcp?key=swh_mcp_xxxxxxxxxxxxxxxxxxxxxxxx

The key

An MCP key starts with swh_mcp_ and is separate from REST API keys: neither works on the other's endpoint. A workspace has one MCP key. It stays visible in the settings, so you can copy the connection URL again, and generating a new one stops the old one at once. Most clients need only the URL; a client that can send headers may pass the key as Authorization: Bearer swh_mcp_… instead of ?key=. A missing or unknown key gets an HTTP 401.

Transport

The endpoint speaks JSON-RPC 2.0 and is stateless: each request is a POST answered with a plain JSON response, with no session and no server-sent event stream (a GET returns 405). It accepts batches, and protocol versions 2025-06-18, 2025-03-26 and 2024-11-05.

Tools

Each tool runs the same handler as its REST endpoint, so inputs are validated the same way and the same rules apply. tools/list returns every tool with its input schema. A tool result is a text item holding JSON, for most tools what the endpoint returns under data. A request the REST API would refuse with a 4xx comes back as a result with isError: true and the error message as its text, so the agent can correct it.

Webhooks and hosted connect links have no tools, and neither do a few reads and deletes (for example deleting a campaign, a lead or a list, or renaming a list): use the REST API for those.

In hosts that render tool widgets (Claude, ChatGPT), the tools that list or show leads, lists, campaigns, sender accounts and stats also return an interactive widget. The JSON stays the first content item, so other clients are not affected.

Acting as a workspace in your organization

An organization's MCP key (one generated in the organization workspace) can act on any workspace inside it by appending &workspaceId=<workspaceId> to the connection URL, one connection per workspace. A workspaceId that is not one of the organization's workspaces gets a 401 on every request. See Authentication for how workspace scoping works, and Organization for the list_workspaces, get_workspace, create_workspace, update_workspace, delete_workspace, invite_workspace_member, update_workspace_member and remove_workspace_member tools. They always manage the key's organization, whatever workspace the connection acts on.

get_workspace_info is the odd one out: it returns the workspace the connection resolves to, not one looked up by id.