Skip to main content
Swan doesn’t just connect out to other tools — it’s also an MCP server itself. Any MCP-capable agent (Claude, or anything else that speaks the Model Context Protocol) can connect to Swan and “talk” to it: send it work in plain language, wait for the result, and pick conversations back up later. Your agent becomes another way to use Swan, with the same account, permissions, and approval rules as chatting in the app. This is the other direction from custom MCP servers, where Swan is the client consuming your tools.

​
Connecting

Add Swan to your agent as a remote MCP server:
  • Endpoint: https://mcp.getswan.com/mcp
  • Auth: OAuth — your agent’s MCP client discovers Swan’s authorization server automatically and walks you through logging in as your Swan user. No API keys.
  • If you belong to more than one Swan org, an org-scoped endpoint pins the connection: https://mcp.getswan.com/mcp/org/<orgId>.
Two requirements: the MCP server must be enabled for your org (an Admin turns it on at Settings → MCP, off by default), and your role must allow the work — Viewers can connect and read conversations, but can’t send Swan messages.

​
What your agent can do

The server exposes four tools:
  • send-message — start a new Swan conversation or continue one. This is the workhorse: research, enrichment, CRM work, drafting or sending outreach, building sequences, managing triggers — anything you could ask Swan in chat.
  • get-conversation — fetch a conversation’s current state and any pending approvals. Swan’s latest message is included once the run has finished or is paused on an approval; while a run is still in progress this returns status only, without a message body.
  • list-conversations — find recent conversations to continue prior work, with a normalized phase for each conversation.
  • cancel-conversation — stop queued or running work. For running work, the tool waits up to 18 seconds for Swan to stop. If cancellation takes longer, it returns an aborting phase and continues asynchronously, so poll get-conversation until the phase is terminal. If the phase stays aborting with no new activity for 30 seconds, call cancel-conversation again to finalize the cancellation. The conversation itself is preserved — once terminal, your agent can continue it with send-message.
send-message waits for Swan to finish by default (up to 18 seconds). If the work takes longer, it returns a status instead — what phase the run is in, when to check back, and a short-lived status URL (valid 15 minutes) — and your agent polls or calls get-conversation for the final result. Swan’s runs can take minutes for substantial work; the tool descriptions your agent sees explain this flow, so well-behaved agents handle it without special setup. The updatedAt returned by get-conversation, list-conversations, and the status URL reflects the latest execution activity. While a conversation is in progress, it advances with the worker heartbeat (about every five seconds); queued and finished conversations use their persisted timestamp. List filters, ordering, and pagination continue to use persisted timestamps. If a running conversation’s updatedAt stops advancing for 30 seconds or more, the run may be stalled — all three read surfaces say so explicitly with a note, and the status URL’s pollAfterMs backs off to 30 seconds. Report the possible stall and keep polling at the slower pace — a stalled run may still recover. To stop or replace the stalled request instead, call cancel-conversation, wait for the conversation to reach a terminal phase, then continue it with send-message and the same conversation id.

​
Approvals still apply

If Swan hits an action that needs human sign-off — the same approval gates as anywhere else — the conversation pauses with pending tool approvals. Your agent reviews them via get-conversation and passes an explicit approve or reject decision for each back through send-message. An external agent never silently bypasses the confirmations you’d get in the app.

​
Limits

  • Up to 5 active conversations at a time per connection.
  • Requests are rate-limited (currently 250 per minute) — far above what a normal agent conversation generates.
  • Runs started this way follow the same run mechanics and consume credits exactly like chat.

​
Common questions

Is this Swan’s API? It’s the supported programmatic way to work with Swan — give it tasks and get results, agent-to-agent. It’s not a REST data API: for pushing Swan data into your systems, use your CRM sync (or an automation where the agent calls your API with a stored secret — see direct API access); for kicking off automations from your systems, use webhook triggers. Does my agent get its own Swan identity? No — it acts as you. It sees the conversations you can see, and everything it does runs under your user and role. Which agents can connect? Anything that supports remote MCP servers with OAuth — Claude (app and Code), and the growing set of MCP-capable clients. If your tool can add a remote MCP server by URL, it can connect to Swan. Can my agent read these docs to learn how Swan works? Yes — that’s a good pattern: point your agent at this documentation for concepts and mechanics, and at the MCP server to actually get things done.