Connect Gumloop to Claude: Build skills, sync files, and track audits

If you need to connect Gumloop to Claude to automate agent sessions, sync workflow artifacts, or audit organization activity, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and Gumloop's REST API. You can either build, host, and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting Gumloop to ChatGPT or explore our broader architectural overview on connecting Gumloop to AI Agents.

Giving a Large Language Model (LLM) read and write access to an automation platform like Gumloop is an engineering challenge. You are granting an AI model the ability to execute pipelines, upload skill packages, and extract potentially sensitive workflow artifacts. You have to handle dynamic input schemas, async polling, and complex multipart file uploads. Every time the integration breaks, your automated operations halt. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Gumloop, connect it natively to Claude Desktop, and execute complex workflows using natural language.

The Engineering Reality of the Gumloop API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against a specific vendor's API is painful. Gumloop is not a standard CRUD application - it is an orchestration engine.

If you decide to build a custom MCP server for Gumloop, you own the entire integration lifecycle. Here are the specific challenges you will face when mapping Gumloop to LLM tools:

Dynamic Workflow Schemas When you execute a saved automation flow in Gumloop, you cannot just pass a generic set of parameters. Every pipeline has a completely custom input schema defined by how the automation was configured in the UI. To execute a flow via API, you first have to call an endpoint just to retrieve the input_schema for that specific saved_item_id. You then have to parse that schema, map it to MCP tool parameters, and present it to Claude so the model knows what arguments to pass. Building this two-step dynamic discovery phase into a hardcoded MCP server requires extensive boilerplate.

Asynchronous Session State Management Agent sessions in Gumloop do not return synchronous results. When you call the session creation endpoint, Gumloop returns an HTTP 202 Accepted with a state of processing or queued. Your MCP server must either block and poll the session status endpoint until a terminal state is reached, or pass the session ID back to the LLM and rely on the model to call a status-checking tool repeatedly. Handling asynchronous orchestration logic via LLM tool calls frequently leads to token exhaustion if not designed properly.

Opaque Payloads and Multipart File Handling Gumloop workflows heavily rely on artifacts (files) and skills (code packages). Uploading a skill requires packaging markdown files into .skill or .zip archives with specific frontmatter, and uploading files requires multipart form encoding. Conversely, downloading a file returns an opaque binary or encoded payload whose structure depends entirely on the content type. LLMs are text-based engines. If you expose raw binary downloads to Claude, the model will fail. Your MCP server must act as a translation layer, generating signed URLs for downloads and handling multipart construction for uploads.

A Strict Note on Rate Limits Gumloop enforces rate limits to protect its orchestration engine. It is critical to understand how Truto handles these limits. Truto does not retry, throttle, or apply backoff on rate limit errors. When Gumloop returns an HTTP 429 Too Many Requests, Truto passes that error directly back to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. Your client - or the agent framework wrapping Claude - is strictly responsible for implementing retry and exponential backoff logic.

Instead of building dynamic schema resolution and multipart encoding logic from scratch, you can use Truto. Truto exposes Gumloop's endpoints as ready-to-use MCP tools, handling the underlying REST mechanics automatically.

How to Generate a Gumloop MCP Server

Truto dynamically derives MCP tools directly from your Gumloop integration's resource definitions. To get started, you need an active Gumloop connection in your Truto environment. Once the account is connected, you can generate the server URL via the Truto UI or the API.

Method 1: Via the Truto UI

For teams managing integrations manually, the Truto dashboard provides a point-and-click interface for generating secure server tokens.

1. Navigate to your Truto dashboard and click on Integrated Accounts.
2. Select your connected Gumloop account.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Configure the server name, tag filters, method filters, and expiration date (we will cover security filtering in detail below).
6. Click Create and copy the generated MCP server URL.

This URL contains a hashed cryptographic token. Do not commit it to version control.

Method 2: Via the Truto API

For platform engineers building scalable AI features, you can programmatically generate MCP servers for your users without manual intervention. You issue a POST request to the /mcp endpoint for the specific integrated account.

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Gumloop Pipeline Executor",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The Truto API will validate that tools exist, generate the secure token, and return a payload containing the url.

{
  "id": "mcp_b7x9a2...",
  "name": "Gumloop Pipeline Executor",
  "config": {
    "methods": ["read", "write", "custom"]
  },
  "url": "https://api.truto.one/mcp/8f72c1a9d4..."
}

How to Connect the MCP Server to Claude

Once you have the Truto MCP URL, you need to register it with Claude so the model can read the tool descriptions and begin calling Gumloop endpoints.

Method 1: Via the Claude Desktop UI

If you are using the consumer-facing Claude Desktop app, Anthropic provides a native UI for adding remote MCP servers.

1. Open Claude Desktop.
2. Navigate to Settings -> Integrations -> Add MCP Server.
3. Provide a name (e.g., "Gumloop Agent Orchestration").
4. Paste the Truto MCP URL you generated in the previous step.
5. Click Add.

Claude will immediately perform a handshake with Truto, pull down the available tools, and make them available in your current workspace context.

Method 2: Via the Manual Configuration File

If you are running Claude Desktop in a developer environment or orchestrating custom agent setups, you can define the remote server explicitly in your claude_desktop_config.json file. Truto relies on Server-Sent Events (SSE) for its transport layer.

Locate your configuration file:

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

Add the Truto server using the @modelcontextprotocol/server-sse package:

{
  "mcpServers": {
    "gumloop": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/8f72c1a9d4..."
      ]
    }
  }
}

Restart Claude Desktop. A hammer icon will appear in the input bar indicating that the Gumloop tools are loaded and ready to use.

Hero Tools for Gumloop Workflows

Truto automatically maps the Gumloop API into standardized MCP tools. Do not dump the entire tool schema into Claude's context window. Instead, here are the highest-leverage tools for controlling Gumloop workflows.

Create a Gumloop Session

Tool name: create_a_gumloop_session

This tool initiates a new agent session. Because Gumloop handles sessions asynchronously, providing an input parameter immediately starts the agent processing and returns a processing or queued state (HTTP 202). If you omit the input, you generate an idle stub session (HTTP 201). This requires the agent_id parameter.

"Start a new session for the Lead Enrichment Agent (agent_id: ag_12345). Provide the input data outlining the target company list, and tell me the session ID returned."

Get Automation Input Schema

Tool name: get_single_gumloop_automation_by_id

This is a critical discovery tool. Before Claude can execute a custom pipeline, it must retrieve the specific input schema defined by the creator in Gumloop. This tool returns the exact field definitions required to trigger the automation.

"Look up the input schema for the Weekly Report Generator automation (saved_item_id: flow_8899). Tell me what fields are required to run this pipeline."

Trigger a Flow Run

Tool name: create_a_gumloop_flow_run

Once Claude knows the input schema, it uses this tool to trigger the start_pipeline endpoint. The model passes the required inputs, and Gumloop begins executing the automation. This tool returns a 204 success, meaning the flow has been handed off to the orchestration engine.

"Trigger the Weekly Report Generator pipeline. Map the required inputs based on the schema you just retrieved, setting the date range to the last 7 days."

List Artifacts

Tool name: list_all_gumloop_artifacts

Workflows in Gumloop often produce files (artifacts). This tool allows Claude to retrieve a collection of artifact records produced by a specific agent, returning the id, filename, media_type, and size. You can optionally scope the search to a specific session or filename.

"List all the artifacts generated by the Data Scraper agent (agent_id: ag_5544) over the last 24 hours. I am looking for a CSV file containing the scraped pricing data."

Manage Agent Skills

Tool name: create_a_gumloop_skill

Gumloop allows you to upload custom skills (code or prompt packages) to enhance agent capabilities. This tool uploads a skill package. The file must include name and description frontmatter. Truto handles the necessary multipart encoding behind the scenes.

"Take this markdown documentation outlining our new API structure, format it with the required frontmatter, and upload it as a new skill to Gumloop."

Audit Organization Logs

Tool name: list_all_gumloop_audit_logs

For enterprise administration, Claude can audit activity across the organization. This tool lists audit logs for all users, returning the user_id, action, and timestamp for recorded events over a specified time period.

"Pull the audit logs for the last 48 hours. Summarize any changes made to permission groups or deleted workflows, and list the user IDs responsible."

Multiplexed Chat Completions

Tool name: create_a_gumloop_chat_completion

Gumloop provides a unique OpenAI-compatible chat completion endpoint multiplexed across Anthropic, OpenAI, Google Gemini, and OpenRouter models. This tool allows Claude to dispatch tasks to other models via Gumloop's routing layer, including image-generation models like DALL-E or Gemini Image Preview.

"Use the Gumloop chat completion tool to generate a concept image for our new landing page. Route the request to the dall-e-3 model."

For the complete inventory of available endpoints and their JSON schemas, refer to the Gumloop integration page.

Workflows in Action

Tools on their own are just endpoints. The real power of MCP is how Claude chains these tools together to execute multi-step operations without human intervention. Here is how that looks in practice.

Workflow 1: Dynamic Pipeline Execution and Artifact Retrieval

Imagine a scenario where a user needs to run a complex data extraction job and review the output. Because Gumloop pipelines require dynamic schemas, the LLM must perform discovery before execution.

"Find the 'Competitor Pricing Scraper' automation, check what inputs it requires, run it for 'Competitor X', and get the resulting artifact download link."

1. Claude calls list_all_gumloop_flows to find the saved_item_id for the Competitor Pricing Scraper.
2. Claude calls get_single_gumloop_automation_by_id using the ID to read the custom input schema.
3. Claude parses the schema, identifies the required target variable, and calls create_a_gumloop_flow_run, mapping 'Competitor X' to the required field.
4. After waiting a designated time, Claude calls list_all_gumloop_artifacts filtered by the target agent to find the generated CSV.
5. Claude calls get_single_gumloop_artifact_by_id to retrieve the signed download URL.

Result: The user receives a brief summary stating the flow was executed successfully, along with a direct, signed link to download the final CSV artifact.

sequenceDiagram
  participant Claude as Claude Desktop
  participant Truto as Truto MCP Server
  participant Gumloop as Gumloop API
  Claude->>Truto: tools/call (get_single_gumloop_automation_by_id)
  Truto->>Gumloop: GET /saved_items/{id}/schema
  Gumloop-->>Truto: { "inputs": ["target_company"] }
  Truto-->>Claude: Schema payload
  Claude->>Truto: tools/call (create_a_gumloop_flow_run)
  Truto->>Gumloop: POST /pipelines/start
  Gumloop-->>Truto: 204 No Content
  Truto-->>Claude: Success confirmation

Workflow 2: Triaging Sessions and Updating Skills

If an agent is failing to process a specific type of request, an administrator can use Claude to kill the rogue session, draft a new instruction package, and deploy it as a skill.

"Check the active sessions for the Support Triage Agent. If session ses_998 is stuck in a loop, cancel it. Then, take my notes on handling refund requests, upload them as a new skill package for that agent, and start a fresh session."

1. Claude calls get_single_gumloop_session_by_id to check the status of ses_998.
2. Seeing an issue, Claude calls delete_a_gumloop_session_by_id, which transitions the stream to failed and aborts the run.
3. Claude formats the user's notes into the required markdown package with name and description frontmatter.
4. Claude calls create_a_gumloop_skill, uploading the file via Truto's multipart handler.
5. Claude calls create_a_gumloop_session to initialize a new processing queue with the updated skill context.

Result: The user gets confirmation that the stuck session was killed, a new skill ID for the uploaded package, and a new session ID for the restarted agent.

Security and Access Control

Giving an AI agent administrative access to an orchestration engine requires strict operational boundaries. Truto provides four mechanisms to scope your MCP server tokens securely:

• Method Filtering: Restrict the server to specific HTTP methods. Passing methods: ["read"] ensures the LLM can only list flows or view logs, completely preventing it from triggering runs (create) or cancelling sessions (delete).
• Tag Filtering: Limit access by functional domain. Passing tags: ["auditing"] restricts the toolset to only endpoints related to logs and users, blocking access to pipeline execution endpoints entirely.
• Require API Token Auth: By default, possessing the MCP URL grants access. Setting require_api_token_auth: true forces the client to also pass a valid Truto API token in the Authorization header, adding a required layer of human identity verification.
• Automatic Expiration: Set expires_at to an ISO datetime to create short-lived servers. This is ideal for generating temporary credentials for a contractor or a specific automated script. Once the timestamp passes, the token is destroyed from Truto's distributed KV store immediately.

Building Agentic Integrations That Do Not Break

Connecting Claude to Gumloop unlocks entirely new orchestration capabilities. Instead of forcing human operators to click through the Gumloop UI to manage complex asynchronous pipelines or compile artifact reports, you can delegate the execution loop directly to the LLM.

The bottleneck is no longer the model's intelligence - it is the integration layer. Hand-rolling custom MCP servers for platforms with dynamic schemas and complex file handling is an engineering sinkhole. By using Truto to generate managed MCP servers, you offload the REST mechanics, pagination schemas, and multipart encoding boilerplate to infrastructure built for scale.