MCP Server

The Swirls MCP (Model Context Protocol) server exposes Swirls as an HTTP MCP service. Connect Claude Desktop, Claude Code, or any MCP client that supports the Streamable HTTP transport to build, manage, and execute graphs using natural language.

Overview

Hosted service: Use Swirls’ MCP endpoint with your API key—no install required.
Authentication: Your API key is passed in the request URL (query or path).

Authentication

The MCP server authenticates using a Swirls API key. Session JWTs are not used for the HTTP service.

Creating an API Key

Log in to the Swirls web app
Open your profile → API Keys
Click Create API Key
Name it (e.g. “Claude Desktop MCP”)
Copy the secret immediately—it’s only shown once.

API keys look like ak_... and don’t expire unless you set an expiration.

Using the Hosted Service

Swirls runs an MCP HTTP server at https://swirls.ai/mcp. Include your API key in the URL when configuring your client.

Passing the API Key

The server accepts the API key as a query parameter:

Query parameter (recommended):
https://swirls.ai/mcp?apiKey=ak_your_secret_here

Use the same base URL for both the initial connection and any session/SSE URLs the client follows. The client must send the Mcp-Session-Id header on subsequent requests when the server returns one.

Claude Desktop

If your Claude Desktop build supports MCP over HTTP, add the Swirls server by URL:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "swirls": {
      "type": "http",
      "url": "https://swirls.ai/mcp?apiKey=ak_your_api_key_here",
      "headers": {}
    }
  }
}

Replace ak_your_api_key_here with your actual API key. Do not commit this file or share it.

Other MCP Clients

For Cursor, IDEs, or other tools that support an HTTP MCP endpoint:

Endpoint: https://swirls.ai/mcp
Authentication: Add ?apiKey=ak_your_api_key_here to the URL, or use the path form above.

Refer to your client’s docs for where to paste the full URL (including the API key).

Available Tools

The MCP server exposes 60+ tools for workflow orchestration:

Project Management

Tool	Description
`list_projects`	List all accessible projects
`get_project`	Get project details
`create_project`	Create a new project

Graph Management

Tool	Description
`list_graphs`	List graphs in a project
`get_graph`	Get a graph with all nodes and edges
`create_graph`	Create a new workflow graph
`update_graph`	Update a graph
`delete_graph`	Delete a graph
`sync_graph`	Sync complete graph structure in one operation

Node Management

Tool	Description
`create_node`	Create a node in a graph
`update_node`	Update a node
`delete_node`	Delete a node

Supported node types: ai, http, code, switch, document, email, graph, scrape, stream, wait, bucket.

Edge Management

Tool	Description
`create_edge`	Connect two nodes
`delete_edge`	Remove a connection

Execution

Tool	Description
`execute_graph`	Execute a graph with input data
`get_execution`	Get execution status and results
`list_executions`	List executions for a graph

Triggers, Forms, Webhooks & Schedules

Tool	Description
`list_triggers` / `create_trigger` / `update_trigger` / `delete_trigger` / `execute_triggers`	Triggers connecting resources to graphs
`list_forms` / `create_form` / `get_form` / `update_form` / `delete_form`	Forms
`list_webhooks` / `create_webhook` / `get_webhook` / `update_webhook` / `delete_webhook`	Webhooks
`list_schedules` / `create_schedule` / `get_schedule` / `update_schedule` / `delete_schedule`	Cron schedules

Other Resources

Tool	Description
`list_schemas` / `create_schema` / `get_schema` / `update_schema` / `delete_schema`	JSON Schema management
`list_documents` / `create_document` / `get_document` / `update_document` / `delete_document`	Document management
`list_streams` / `create_stream` / `get_stream` / `update_stream` / `delete_stream` / `query_stream`	Stream data
`list_agents` / `create_agent` / `get_agent` / `update_agent` / `delete_agent`	AI agents
`list_reviews` / `get_review` / `approve_review` / `reject_review`	Human-in-the-loop reviews
`list_folders` / `create_folder` / `update_folder` / `delete_folder`	Folder organization
`create_api_key` / `list_api_keys` / `revoke_api_key`	API key management

Example: Building a Workflow with Claude

You: Create a workflow that takes a topic, generates a blog post about it, and emails it to me.

Claude: I'll create that workflow for you. Let me:

List your projects: list_projects
Create a new graph: create_graph(projectId: "...", name: "Blog Generator")
Sync the workflow with an LLM node and an email node: sync_graph(graphId: "...", nodes: [...], edges: [...])
Create a form trigger: create_form(...), create_trigger(...)

Your workflow is ready. Submit topics through the form or run the graph directly.

Troubleshooting

"Missing apiKey parameter" or 401

Ensure the MCP URL includes the API key: ?apiKey=ak_... or /apiKey=ak_....
Check for typos, extra spaces, or missing characters in the key.

"Invalid API key"

Your API key may be:

Revoked — Create a new one in the web app.
Expired — If you set an expiration, create a new key.
Malformed — Copy the full key again (starts with ak_).

"Authentication required"

The key in the URL is invalid or not accepted. Try creating a new API key in the Swirls web app and updating the URL.

MCP server not appearing in Claude / client

Confirm your client supports MCP over HTTP (Streamable HTTP transport). Some clients only support STDIO.
Use the full URL including the API key in the client’s MCP/server configuration.
Restart the client after changing the config.
For Claude Desktop, fully quit the app (e.g. Cmd+Q / Quit from tray) so config changes load.

MCP Server

On this page