Skip to content
Truto
Back
AI & Agents

Connect Gumloop to Claude: Run AI skills and manage file artifacts

Learn how to connect Gumloop to claude using Truto. Step-by-step guide to tool calling, API quirks, and autonomous workflows.

Uday Gajavalli Uday Gajavalli · · 9 min read
Connect Gumloop to Claude: Run AI skills and manage file artifacts

If you need to connect Gumloop to Claude to trigger automated workflows, deploy AI skills, or manage file artifacts, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's native tool calls and Gumloop's REST APIs. You can either build 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 AI orchestration platform like Gumloop presents a unique recursive engineering challenge. You are essentially asking an AI agent to control other AI agents. To do this reliably, you have to handle complex asynchronous execution states, dynamic input schemas that change per pipeline, and opaque binary artifact payloads. Every time Gumloop updates its API or introduces a new skill execution parameter, you have to update your server code, redeploy, and test the integration.

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 AI orchestration 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 highly dynamic platform like Gumloop is painful. You are not just building CRUD endpoints - you are building an orchestration interface.

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

Asynchronous Session State Management Gumloop is designed for long-running workflows. When you trigger an agent via the /sessions endpoint, the API rarely returns immediate results. Instead, it returns an HTTP 202 Accepted with a session state of processing or queued. LLMs expect synchronous tool execution. If you expose this raw behavior to Claude, the model will either hallucinate the completion state or enter rapid infinite polling loops, burning through your context window. You have to build explicit status-polling tools and instruct the LLM on exactly how to wait and re-query the get_single_gumloop_session_by_id endpoint without exhausting token limits.

Highly Dynamic Input Schemas Unlike a CRM where a "Contact" always has a first_name and email, a Gumloop automation's input schema is completely defined by the user who built the pipeline. When fetching automation details, the API returns pipeline-specific field definitions. Translating these dynamic nested JSON structures into statically typed MCP tool schemas at runtime requires complex schema derivation logic. If you map this incorrectly, Claude will construct invalid payloads that fail schema validation on Gumloop's end.

Opaque Binary Artifacts Gumloop workflows frequently generate outputs as "artifacts" - CSVs, images, scraped data payloads, or raw text files. The API handles these as opaque binaries or returns signed download URLs. If an LLM calls a tool to retrieve an artifact, feeding raw binary data back into the MCP text response payload will crash the client. Your integration layer must intercept these payloads, evaluate the media_type, parse readable files into markdown, or safely discard non-text binaries while preserving metadata.

Strict Rate Limits and Normalization API quotas govern how many concurrent runs you can trigger. When Gumloop returns an HTTP 429 Too Many Requests, Truto does not intercept, retry, or apply exponential backoff. Instead, Truto passes that 429 error directly back to the calling LLM while normalizing the rate limit headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. Your MCP client or agent orchestrator is strictly responsible for managing retry logic. If you build this yourself, you must manually trap these headers and surface them in a way Claude understands so it knows to wait before retrying.

How to Generate a Gumloop MCP Server with Truto

Truto dynamically generates MCP tools from Gumloop's API documentation and OpenAPI schemas. Instead of writing tool definitions manually, you connect a Gumloop account and Truto provisions a dedicated, authenticated /mcp/:token endpoint.

You can generate this server either through the Truto UI or programmatically via the API.

Method 1: Generating the MCP Server via the Truto UI

  1. Log into your Truto dashboard and navigate to your connected Gumloop environment under Integrated Accounts.
  2. Click on the specific Gumloop account connection.
  3. Click the MCP Servers tab.
  4. Click Create MCP Server.
  5. Select your desired configuration (name, specific methods, tags, and expiration date if temporary access is required).
  6. Copy the generated MCP server URL. It will look like https://api.truto.one/mcp/a1b2c3d4e5f6...

Method 2: Generating the MCP Server via the API

For teams deploying internal tooling or multi-tenant agents, you can provision Gumloop MCP servers dynamically via the Truto API.

Send a POST request to /integrated-account/:id/mcp. You can pass specific configurations to restrict the server to read-only operations or target specific integration tags.

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

The API validates the available Gumloop documentation, provisions the token in distributed KV storage, and returns the ready-to-use URL:

{
  "id": "mcp-789-xyz",
  "name": "Gumloop Production Orchestrator",
  "config": { "methods": ["read", "write", "custom"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to Claude

Once you have your Truto MCP URL, you need to register it with your Claude client. Because Truto's MCP servers are self-contained and authenticate via the cryptographic token in the URL, configuration is straightforward.

Method A: Via the Claude UI (Claude for Work or ChatGPT)

If you are using Claude for Work (Enterprise/Team) or ChatGPT Plus/Enterprise, you can add the server directly via the interface.

  1. In Claude: Navigate to Settings -> Integrations (or Connectors) -> Add MCP Server.
  2. Paste your Truto MCP URL.
  3. Click Add. Claude will immediately handshake with the Truto router via the initialize JSON-RPC method and list the available Gumloop tools.

(Note: For ChatGPT, the path is Settings -> Apps -> Advanced settings -> Enable Developer mode -> Add Custom Connector).

Method B: Via the Claude Desktop Config File

For local development with Claude Desktop, you add the server by modifying your claude_desktop_config.json file. Because Claude Desktop natively expects MCP servers to communicate over stdio (standard input/output) but Truto hosts remote HTTP/SSE endpoints, you must use the official MCP Server-Sent Events (SSE) wrapper tool.

Open your configuration file (usually located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add the following:

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

Restart Claude Desktop. The application will execute the wrapper, which connects to the Truto MCP URL over HTTP and translates the JSON-RPC traffic back to stdio for Claude.

Gumloop Hero Tools for Claude

Truto exposes the entirety of the Gumloop API as normalized tools. Below are the highest-leverage hero tools for orchestrating workflows and managing AI resources.

create_a_gumloop_session

Creates a new agent session to trigger a pipeline. When you provide input data, the agent immediately begins processing. Claude uses this to kick off backend automation flows.

"Trigger the Lead Enrichment agent (ID: agt_8829) with the input parameter 'company_domain' set to 'acme.com'."

get_single_gumloop_run_by_id

Retrieves the detailed execution state of a specific pipeline run. Because Gumloop workflows are asynchronous, Claude must use this tool to poll the run_id until the state changes to a terminal status, retrieving the final outputs from the nodes.

"Check the status of run ID run_4499. If it is still processing, wait and do not hallucinate outputs. If it is complete, extract the 'enriched_data' object from the final outputs."

list_all_gumloop_artifacts

Lists the file outputs (artifacts) generated by a specific agent. This returns the id, filename, media_type, and size for each file, which is critical for verifying that an automation successfully produced its intended deliverable.

"List all the artifacts produced by the monthly reporting agent (ID: agt_9910). Find the most recent CSV file and tell me its artifact ID and size."

create_a_gumloop_skill

Uploads a new skill package to the platform, making it available for agents to use. Claude can draft custom markdown-based skills (SKILL.md) with required frontmatter and use this tool to deploy them directly into the Gumloop environment.

"Deploy this new Python execution script as a skill. Set the name to 'Data Sanitizer' and upload the raw markdown file content I just generated."

create_a_gumloop_chat_completion

Bypasses standard pipeline logic to trigger a multiplexed, OpenAI-compatible chat completion directly through Gumloop's model routing. Claude can use this to farm out specific reasoning sub-tasks to other models (like Gemini or OpenAI) while maintaining its orchestrator role.

"Take this unstructured customer text and send a chat completion request via Gumloop using the 'gpt-4o' model. Ask the model to extract the sentiment and top three keywords."

list_all_gumloop_mcp_servers

Retrieves all nested MCP servers currently registered inside the Gumloop environment itself (including hosted, Gumstack, and custom servers). This allows Claude to audit exactly which external tools the Gumloop agents are currently permitted to invoke.

"Audit our Gumloop instance and list all registered MCP servers. Tell me the connection state of the 'Salesforce Proxy' server and what tool call IDs it allows."

To view the complete inventory of available operations - including endpoints for team management, automation definitions, and data exports - refer to the Gumloop integration page.

Workflows in Action

Once the MCP server is registered, Claude gains autonomous read/write capabilities across your Gumloop pipelines. Here is how specialized technical personas utilize this connection.

Scenario 1: Debugging a Stalled Automation Run

An AI Operations Administrator notices an anomaly in downstream data and asks Claude to investigate the underlying Gumloop pipeline.

"Look up the most recent automation runs for user usr_772. Find the one that failed yesterday and retrieve its final output state and error messages."

  1. Claude calls list_all_gumloop_automation_runs with user_id: "usr_772" to retrieve the 10 most recent runs.
  2. Claude parses the list, identifies the run ID that has a state matching failed or an anomaly from yesterday.
  3. Claude executes get_single_gumloop_run_by_id, passing the identified run_id to pull the deeply nested output object.
  4. Claude analyzes the node logs within the JSON payload and summarizes exactly which step in the pipeline caused the failure.
sequenceDiagram
    participant Claude
    participant Truto as Truto MCP Router
    participant Upstream as "Gumloop API"

    Claude->>Truto: list_all_gumloop_automation_runs<br>(user_id: "usr_772")
    Truto->>Upstream: GET /automation_runs?user_id=usr_772
    Upstream-->>Truto: JSON Array (10 recent runs)
    Truto-->>Claude: Normalized MCP Tool Result
    
    Claude->>Truto: get_single_gumloop_run_by_id<br>(run_id: "run_abc123")
    Truto->>Upstream: GET /runs/run_abc123
    Upstream-->>Truto: JSON (Node states & outputs)
    Truto-->>Claude: Detailed execution graph

Scenario 2: Deploying a Skill and Generating Artifacts

A DevOps Engineer needs to roll out a new AI capability, test it, and verify the generated output.

"Deploy the new 'Log Parser' skill I wrote into Gumloop. Once deployed, trigger a session for the agent agt_900 using this skill, wait for it to finish, and list the generated artifacts."

  1. Claude calls create_a_gumloop_skill and passes the generated SKILL.md content via multipart form encoding translated by the tool schema.
  2. Claude calls create_a_gumloop_session with agent_id: "agt_900", passing the input payload. It receives an HTTP 202 and a session ID in processing state.
  3. Claude intelligently waits, then calls get_single_gumloop_session_by_id to poll the state until it resolves to completed.
  4. Claude calls list_all_gumloop_artifacts using the agent_id to retrieve the array of files generated by the run, confirming the artifact's metadata and file size to the user.

Security and Access Control

Granting an LLM autonomous execution rights over your automation platform requires strict boundaries. Truto provides four distinct configuration layers to enforce security at the MCP server level:

  • Method Filtering: By specifying config.methods: ["read"] during server creation, you can physically block Claude from invoking any create, update, or delete tools (like triggering runs or deleting skills). The tools simply won't generate.
  • Tag Filtering: If your integration configures specific tags, you can isolate access. Passing config.tags: ["reporting"] ensures the MCP server only exposes tools related to reports, keeping core administrative endpoints out of the LLM's context window.
  • Time-to-Live (TTL): The expires_at parameter allows you to provision short-lived MCP servers. Once the ISO datetime is reached, Truto's Durable Object alarms hard-delete the token from KV storage, immediately severing the LLM's access to Gumloop.
  • API Token Authorization: Setting require_api_token_auth: true forces a two-layer security model. Even if a user possesses the correct MCP server URL, they must also inject a valid Truto API token into the HTTP headers to successfully call tools, preventing unauthorized usage if a URL leaks in local logs.

By leveraging these controls, you ensure your agents have exactly enough access to perform their intended tasks without putting your broader orchestration architecture at risk.

More from our Blog