Connect Maia to Claude: Automate Agent Tasks and Project Workflows

If your team needs to connect Maia to Claude to automate AI agent tasks, orchestrate pipeline executions, or manage environment configurations, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's natural language tool calls and Maia's complex 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 Maia to ChatGPT or explore our broader architectural overview on connecting Maia to AI Agents.

Giving a Large Language Model (LLM) read and write access to an enterprise automation and AI runner platform like Maia is an engineering challenge. You have to handle API authentication, map deeply nested JSON schemas to MCP tool definitions, and deal with Maia's asynchronous task architecture. Every time Maia updates an endpoint or introduces a new resource, you have to update your custom server code, redeploy, and test the integration.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for Maia, connect it natively to Claude Desktop, and execute complex project workflows using natural language.

The Engineering Reality of the Maia 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 over JSON-RPC, the reality of implementing it against Maia's APIs requires significant domain knowledge. Maia is designed to orchestrate complex data pipelines, streaming workflows, and autonomous AI agents. Its API reflects that complexity.

If you decide to build a custom MCP server for Maia, here are the specific integration challenges your engineering team will face:

Asynchronous Agent Tasks and Human-in-the-Loop Polling Maia AI agent tasks do not resolve synchronously. When you call the endpoint to create an agent task, the API returns a task ID while the agent runs in the background. If the agent requires human intervention (e.g., asking for permission to proceed or requesting additional data), the task enters a pending state. Your MCP server must expose polling mechanisms so Claude can repeatedly check the task status, retrieve the pending decisions, and submit approvals. LLMs struggle with unstructured polling loops, meaning you have to carefully design the MCP tool schemas to instruct the model on exactly how and when to check task statuses.

Complex Environment Overrides and Connection Resolution Maia utilizes a highly modular project structure where connections (like database credentials or SaaS tokens) are defined at the project level but can be overridden at the environment level. When executing a pipeline, Maia resolves the connection dynamically. If an LLM needs to update a connection, it must understand whether it is updating the base project connection or creating a specific environment override. Building tools that flatten this complexity without losing precision is a tedious schema-mapping exercise.

Strict SCIM Schema Requirements Managing users and groups in Maia relies on SCIM (System for Cross-domain Identity Management) directory standards. The SCIM endpoints require highly specific, standardized payloads with nested attributes (e.g., urn:ietf:params:scim:schemas:core:2.0:User). An LLM attempting to create a user will often hallucinate flat JSON objects instead of the required SCIM extensions. Your integration layer must enforce these schemas strictly before passing payloads to Maia.

How Truto's Managed MCP Server Works

Instead of hardcoding integration logic, Truto derives MCP tool definitions dynamically from Maia's API documentation and endpoint schemas.

When you connect a Maia account to Truto, the platform queries the available resources and derives a set of MCP tools. A tool only appears if it has a corresponding documentation record defining its description, query parameters, and body schema. This acts as a quality gate, ensuring Claude only sees endpoints that are fully documented and AI-ready.

When Claude invokes a tool, Truto validates the payload, applies the authenticated Maia token, translates the request into the exact shape required by Maia's proxy API handlers, and returns the normalized response.

Step 1: Generating the Maia MCP Server

To bridge Claude and Maia, you need to generate an MCP server URL scoped to your specific Maia environment. You can do this through the Truto UI for one-off configurations, or programmatically via the API to scale across multiple tenants.

Method A: Via the Truto UI

If you are setting up an internal tool or prototyping a workflow, the UI is the fastest path:

1. Log into your Truto dashboard and connect a Maia account.
2. Navigate to the Integrated Accounts page and select your Maia connection.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Configure the server. You can name it, optionally restrict it to specific operations (e.g., only read methods), and set an expiration date if you want temporary access.
6. Click Create and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method B: Via the Truto API

For teams building platforms that deploy AI agents automatically, you can generate MCP servers programmatically. This ensures that every tenant gets a secure, isolated server URL tailored to their own Maia instance.

Make a POST request to the Truto API using the Integrated Account ID:

const response = await fetch('https://api.truto.one/integrated-account/{integrated_account_id}/mcp', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${TRUTO_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Maia Project Automation Server",
    config: {
      methods: ["read", "write", "custom"], // Expose all curated tools
      tags: ["pipelines", "agents", "projects"] // Scope tools to specific resource categories
    },
    expires_at: "2026-12-31T23:59:59Z" // Optional automatic cleanup
  })
});
 
const mcpServer = await response.json();
console.log("Your MCP Server URL:", mcpServer.url);

The returned URL contains a cryptographically hashed token that securely identifies the connection and its configuration.

Step 2: Connecting the MCP Server to Claude

Once you have the URL, you must configure your AI client to communicate with it. The MCP protocol standardizes this handshake.

Method A: Via the Claude Desktop UI (or ChatGPT)

If your organization uses enterprise AI clients with interface-based connector management, you can add the URL directly.

• For ChatGPT (Enterprise/Pro): Navigate to Settings > Apps > Advanced settings. Enable Developer mode. Under MCP servers, add a new server, name it "Maia", and paste the Truto URL.
• For Claude (Web/Enterprise): Navigate to Settings > Integrations > Add MCP Server. Paste the URL and click Add.

Method B: Via the Claude Desktop Config File

For local development or custom deployments of Claude Desktop, you can update the configuration file manually. This uses the official Server-Sent Events (SSE) transport adapter provided by the MCP project.

Locate your Claude config file:

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

Add the Maia server configuration:

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

Restart Claude Desktop. The client will initialize the connection, call the tools/list RPC method, and populate its context window with the available Maia capabilities.

Maia Hero Tools for Claude

When Claude connects to the MCP server, Truto exposes a curated set of proxy tools. These tools flatten Maia's complex payloads into documented, callable schemas. Here are six high-leverage tools your agent can use immediately.

1. List Available Maia Agents

Tool: list_all_maia_agents

Before assigning workloads, Claude needs to know which AI runners are deployed, their current operational status, and what environments they exist in. This tool retrieves the active fleet of agents.

"Check our Maia account and list all active streaming agents. Tell me if any are currently paused or pending updates."

2. Initiate an AI Agent Task

Tool: create_a_maia_agents_task

This is the core execution tool for AI workloads. It triggers an asynchronous agent task by passing a natural language objective and the required agent configuration block.

"Start a new Maia agent task assigned to the 'Data-Analyzer-01' agent. Instruct it to process the latest transaction logs in the staging environment. Let me know the Task ID so we can track it."

3. Track Agent Task Progress

Tool: get_single_maia_agents_task_by_id

Because agent tasks run asynchronously, Claude uses this tool to poll the status. It returns the current state, runtime logs, and critically, any pendingDecisions that require human approval to continue.

"Check the status of task ID 'tsk_987654321'. If it is waiting on a human decision, tell me what it is asking for so I can approve it."

4. Execute a Project Pipeline

Tool: create_a_maia_project_pipeline_execution

Maia orchestrates data through published pipelines. This tool allows Claude to trigger a specific pipeline execution within a designated environment and project context.

"Run the 'nightly_etl.orch.yaml' pipeline in the 'production' environment for project ID 'prj_123abc'."

5. Inspect Pipeline Execution Steps

Tool: list_all_maia_pipeline_execution_steps

When a pipeline fails, an LLM needs granular context to diagnose the issue. This tool fetches the step-by-step telemetry of a specific execution, revealing exactly which child process or transformation step threw the error.

"The pipeline execution 'exec_456' failed. Fetch the execution steps and analyze the logs to tell me exactly which step caused the failure and why."

6. Provision a SCIM User

Tool: create_a_maia_scim_user

Automate onboarding by creating new directory-integrated users. Truto's schema ensures Claude provides the strict SCIM-compliant payload required by Maia's identity systems.

"Provision a new Maia user for jane.doe@example.com with the display name 'Jane Doe'. Ensure she is set to active."

For the complete inventory of available Maia tools and exact schema specifications, view the Maia integration page.

Workflows in Action

Exposing tools is only half the battle. The real power of MCP is enabling Claude to chain these operations together autonomously to resolve complex technical requests.

Workflow 1: Pipeline Orchestration and Debugging

Data engineers often rely on LLMs to debug failing ETL jobs. With MCP, Claude can trigger the run, monitor it, and diagnose the failure without leaving the chat interface.

"Trigger the 'customer_sync.tran.yaml' pipeline in our staging project. Monitor it, and if it fails, pull the execution steps and tell me what went wrong."

Execution Steps:

1. Claude calls create_a_maia_project_pipeline_execution with the project ID and pipeline name, receiving a pipelineExecutionId.
2. Claude pauses, then periodically calls get_single_maia_project_pipeline_execution_by_id to poll the status.
3. The status returns as FAILED.
4. Claude immediately calls list_all_maia_pipeline_execution_steps using the execution ID.
5. Claude parses the step array, identifies the failed node (e.g., a database connection timeout), and summarizes the root cause for the engineer.

sequenceDiagram
  participant Claude as Claude Desktop
  participant Truto as Truto MCP Server
  participant Maia as Maia API
  Claude->>Truto: Call "create_a_maia_project_pipeline_execution"
  Truto->>Maia: POST /api/projects/prj_123/pipeline-executions
  Maia-->>Truto: 201 Created (pipelineExecutionId)
  Truto-->>Claude: JSON-RPC Result
  Claude->>Truto: Call "list_all_maia_pipeline_execution_steps"
  Truto->>Maia: GET /api/projects/prj_123/pipeline-executions/exec_456/steps
  Maia-->>Truto: Steps array containing error trace
  Truto-->>Claude: JSON-RPC Result

Workflow 2: Asynchronous Agent Task Resolution

AI operations teams frequently manage fleets of subordinate agents that halt for safety validations. Claude can act as an orchestrator, checking on tasks and formatting decisions for human review.

"Check on agent task 'tsk_alpha_99'. If it needs approval to modify the production database, let me know. If it's done, summarize the output."

Execution Steps:

1. Claude calls get_single_maia_agents_task_by_id to retrieve the current state.
2. The payload reveals status: "AWAITING_DECISION" and a pendingDecisions object containing a request to drop a staging table.
3. Claude stops execution and prints a clear message to the user: "The agent is requesting permission to drop the staging_users table. Do you approve?"
4. The user replies "Yes, proceed."
5. Claude calls create_a_maia_task_decision, formatting the JSON payload to send the approval flag to Maia, allowing the background agent to resume.

Security and Access Control

Granting an LLM direct access to an automation platform like Maia requires strict security guardrails. Truto provides built-in mechanisms to lock down your MCP servers:

• Method Filtering: Configure the MCP token with config.methods: ["read"] to strictly prevent Claude from creating, updating, or deleting Maia resources, effectively creating a read-only observability agent.
• Tag Filtering: Limit the server to specific domains. Using config.tags: ["reporting"], the server will only expose analytics and reporting tools, hiding destructive pipeline configurations.
• Secondary Authentication: By enabling require_api_token_auth, possessing the MCP server URL is not enough. The client must also append a valid Truto API token to every request, ensuring only authenticated developers can utilize the tools.
• Time-to-Live (TTL): Set an expires_at timestamp. Truto utilizes durable state scheduling to automatically revoke the token and clean up the server infrastructure at the exact expiration time, ideal for temporary contractor access.

Handling Rate Limits and State in Production

When executing high-frequency polling loops or bulk operations, you will inevitably encounter API rate limits. It is critical to understand the architectural boundary between the MCP server and the client.

Truto operates as a stateless proxy layer to ensure zero data retention. Truto does not queue, retry, or apply backoff logic to rate limit errors. If the upstream Maia API rejects a request with an HTTP 429 status code, Truto immediately passes that error back to the caller.

To aid in building resilient agents, Truto normalizes the upstream rate limit data into standard IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). Your AI client or orchestration framework (like LangGraph or your custom application logic) is fully responsible for reading these headers, pausing execution, and implementing exponential backoff before attempting the tool call again.

Moving from Manual Tasks to Autonomous Orchestration

Connecting Maia to Claude via MCP fundamentally changes how you interact with your automation infrastructure. Instead of clicking through dashboards to check pipeline statuses or manually constructing SCIM payloads to provision users, your engineering team can instruct an AI agent to execute, monitor, and debug these workflows autonomously.

By leveraging a managed MCP architecture, you eliminate the technical debt of building custom server code, managing OAuth state, and mapping complex schemas. You get secure, documented tools out of the box, allowing you to focus on writing better prompts and building more resilient multi-agent systems.