# How to integrate Celigo MCP with Mastra AI

```json
{
  "title": "How to integrate Celigo MCP with Mastra AI",
  "toolkit": "Celigo",
  "toolkit_slug": "celigo",
  "framework": "Mastra AI",
  "framework_slug": "mastra-ai",
  "url": "https://composio.dev/toolkits/celigo/framework/mastra-ai",
  "markdown_url": "https://composio.dev/toolkits/celigo/framework/mastra-ai.md",
  "updated_at": "2026-06-18T09:19:03.455Z"
}
```

## Introduction

This guide walks you through connecting Celigo to Mastra AI using the Composio tool router. By the end, you'll have a working Celigo agent that can list failed celigo flows today, restart failed netsuite shopify syncs, check recent celigo job errors through natural language commands.
This guide will help you understand how to give your Mastra AI agent real control over a Celigo account through Composio's Celigo MCP server.
Before we dive in, let's take a quick look at the key ideas and tools involved.

## Also integrate Celigo with

- [OpenAI Agents SDK](https://composio.dev/toolkits/celigo/framework/open-ai-agents-sdk)
- [Claude Agent SDK](https://composio.dev/toolkits/celigo/framework/claude-agents-sdk)
- [Claude Code](https://composio.dev/toolkits/celigo/framework/claude-code)
- [Claude Cowork](https://composio.dev/toolkits/celigo/framework/claude-cowork)
- [Codex](https://composio.dev/toolkits/celigo/framework/codex)
- [OpenClaw](https://composio.dev/toolkits/celigo/framework/openclaw)
- [Hermes](https://composio.dev/toolkits/celigo/framework/hermes-agent)
- [CLI](https://composio.dev/toolkits/celigo/framework/cli)
- [Google ADK](https://composio.dev/toolkits/celigo/framework/google-adk)
- [LangChain](https://composio.dev/toolkits/celigo/framework/langchain)
- [Vercel AI SDK](https://composio.dev/toolkits/celigo/framework/ai-sdk)
- [LlamaIndex](https://composio.dev/toolkits/celigo/framework/llama-index)
- [CrewAI](https://composio.dev/toolkits/celigo/framework/crew-ai)

## TL;DR

Here's what you'll learn:
- Set up your environment so Mastra, OpenAI, and Composio work together
- Create a Tool Router session in Composio that exposes Celigo tools
- Connect Mastra's MCP client to the Composio generated MCP URL
- Fetch Celigo tool definitions and attach them as a toolset
- Build a Mastra agent that can reason, call tools, and return structured results
- Run an interactive CLI where you can chat with your Celigo agent

## What is Mastra AI?

Mastra AI is a TypeScript framework for building AI agents with tool support. It provides a clean API for creating agents that can use external services through MCP.
Key features include:
- MCP Client: Built-in support for Model Context Protocol servers
- Toolsets: Organize tools into logical groups
- Step Callbacks: Monitor and debug agent execution
- OpenAI Integration: Works with OpenAI models via @ai-sdk/openai

## What is the Celigo MCP server, and what's possible with it?

The Celigo MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Celigo account. It provides structured and secure access so your agent can perform Celigo operations on your behalf.

## Supported Tools

| Tool slug | Name | Description |
|---|---|---|
| `CELIGO_ASSIGN_EXPORT_ERROR` | Assign Export Error | Tool to assign an export error to a user in Celigo. Use when you need to assign responsibility for fixing or reviewing integration errors to a specific team member. |
| `CELIGO_CLONE_EXPORT` | Clone Export | Tool to clone a specific export to create a copy. Use when you need to duplicate an existing export configuration with new or same connection mappings. |
| `CELIGO_CLONE_FLOW` | Clone Flow | Tool to clone a specific flow to create a copy. Use when you need to duplicate an existing flow configuration to a different integration. |
| `CELIGO_CLONE_IMPORT` | Clone Import | Tool to clone a specific import to create a copy with remapped connections. Use when you need to duplicate an existing import configuration with different connection IDs. |
| `CELIGO_CLONE_INTEGRATION` | Clone Integration | Tool to clone a specific integration to create a copy. Use when you need to duplicate an existing integration and all its flows. |
| `CELIGO_CREATE_CONNECTION` | Create Connection | Tool to create a new connection in Celigo to store credentials and application access information. Use when you need to set up a new API connection, configure authentication, or establish integration endpoints. Supports multiple connection types including REST, FTP, Salesforce, and NetSuite. |
| `CELIGO_CREATE_EXPORT` | Create Export | Tool to create a new export in Celigo for extracting data from an application. Use when you need to set up a new data export configuration, such as webhook exports, delta exports, or test exports. |
| `CELIGO_CREATE_FILE_DEFINITION` | Create File Definition | Tool to create a file definition in Celigo for defining data file structure and format. Use when you need to specify how data files should be structured for import or export operations. Supports both fixed-width and delimited (CSV-style) file formats. |
| `CELIGO_CREATE_FLOW` | Create Flow | Tool to create a new flow in Celigo that composes export and import components together. Use when you need to establish a data integration pipeline between systems. A flow connects a source (export) to a destination (import) and can be scheduled or triggered on-demand. |
| `CELIGO_CREATE_I_CLIENT` | Create iClient | Tool to create a new iClient for SmartConnector authentication in Celigo. Use when you need to set up authentication credentials for connecting to external APIs. iClients store provider-specific authentication data required for API integrations. |
| `CELIGO_CREATE_IMPORT` | Create Import | Tool to create a new import for inserting data into an application. Use when you need to set up a data import configuration with HTTP endpoint details. |
| `CELIGO_CREATE_INTEGRATION` | Create Integration | Tool to create a new integration in Celigo to group flows together. Use when you need to organize related flows under a single integration container for better management and structure. |
| `CELIGO_CREATE_INTEGRATION_REVISION` | Create Integration Revision | Tool to create a snapshot revision of a specific integration. Use when you need to capture the current state of an integration for version control or backup purposes. |
| `CELIGO_CREATE_SCRIPT` | Create Script | Tool to create a new custom JavaScript script in Celigo for data transformation operations. Use when you need to add a script for custom data processing, validation, or transformation logic. |
| `CELIGO_CREATE_TAG` | Create Tag | Tool to create a new tag in Celigo for organizing and categorizing resources. Use when you need to create a tag that can be applied to integrations, flows, or other Celigo resources. |
| `CELIGO_DELETE_ALL_RESOURCE_STATE` | Delete All Resource State | Tool to delete all state keys and values stored under a specific resource. Use when you need to clear all state data for a resource. This is a destructive operation - be careful! |
| `CELIGO_DELETE_ALL_STATE` | Delete All State | Tool to delete all global state keys and values in Celigo. Use when you need to clear all stored state data. WARNING: This operation is destructive and irreversible - it removes ALL global state keys and values from the account. |
| `CELIGO_DELETE_CONNECTION` | Delete Connection | Tool to delete a specific connection in Celigo. Use when you need to permanently remove a connection from your integration. Returns success status on completion. |
| `CELIGO_DELETE_EXPORT` | Delete Export | Tool to delete a specific export from Celigo. Use when you need to permanently remove an export by its ID. Returns a success confirmation. |
| `CELIGO_DELETE_FLOW` | Delete Flow | Tool to delete a specific flow from Celigo. Use when you need to permanently remove a flow. This operation is destructive and cannot be undone. |
| `CELIGO_DELETE_ICLIENT` | Delete iClient | Tool to delete a specific iClient from Celigo. Use when you need to permanently remove an iClient by its ID. Returns a success confirmation. |
| `CELIGO_DELETE_IMPORT` | Delete Import | Tool to delete a specific import from Celigo integrator.io. Use when you need to remove an import configuration. This operation is destructive and cannot be undone. |
| `CELIGO_DELETE_INTEGRATION` | Delete Integration | Tool to delete a specific integration from Celigo integrator.io. Use when you need to permanently remove an integration. This operation is destructive and cannot be undone. |
| `CELIGO_DELETE_RESOLVED_ERRORS` | Delete Resolved Errors | Tool to delete resolved errors for a specific export in Celigo. Use when you need to clear resolved errors from an export's error log. |
| `CELIGO_DELETE_RESOURCE_STATE_VALUE` | Delete Resource State Value | Tool to delete the resource-specific key and value from state. Use when you need to remove state data for a specific resource like imports, exports, flows, or connections. |
| `CELIGO_DELETE_SCRIPT` | Delete Script | Tool to delete a specific script from Celigo. Use when you need to permanently remove a script configuration. This operation is destructive and cannot be undone. |
| `CELIGO_DELETE_STATE_VALUE` | Delete State Value | Tool to delete the specified state key and its value. Use when you need to remove state data from the Celigo Integrator platform. This operation is destructive and cannot be undone. |
| `CELIGO_DELETE_TAG` | Delete Tag | Tool to delete a specific tag from Celigo integrator.io. Use when you need to permanently remove a tag. This operation is destructive and cannot be undone. |
| `CELIGO_DELETE_USER` | Delete User | Tool to delete a specific user from your Celigo account. Use when you need to remove a user (account share) from the account. |
| `CELIGO_EVALUATE_VIRTUAL_IMPORT_MAP` | Evaluate Virtual Import Map | Evaluate the mapping step of a virtual import and return post-mapped records. Use when you need to test field mapping transformations without executing the full import process. |
| `CELIGO_EXECUTE_VIRTUAL_EXPORT` | Execute Virtual Export | Execute a virtual export using a connection by posting the export model. Use when you need to trigger an export operation for a specific connection with custom configuration (HTTP, NetSuite, or Salesforce). |
| `CELIGO_EXECUTE_VIRTUAL_IMPORT` | Execute Virtual Import | Tool to execute a virtual import by posting import configuration and data to a connection. Use when you need to send data to an external API through a Celigo connection with field mapping transformations. |
| `CELIGO_EXPORT_VIRTUAL_PAGED` | Virtual Export with Paging | Tool to execute a virtual export with paging support for Celigo connections. Use when you need to retrieve data from external systems in paginated chunks. For subsequent pages, include the pagedExportState from the previous response. |
| `CELIGO_GENERATE_STRUCTURED_FILE` | Generate Structured File | Tool to generate sample EDI data or structured files from input data. Use when you need to convert JSON data into a delimited or fixed-width file format based on defined rules. |
| `CELIGO_GET_CONNECTION` | Get Connection by ID | Tool to get a specific connection by its ID. Use when you need to retrieve connection details including configuration, authentication settings, and type information. |
| `CELIGO_GET_CONNECTION_AUDIT` | Get Connection Audit Logs | Tool to retrieve audit logs for a specific connection. Use when you need to track changes, view history, or investigate modifications made to a connection. |
| `CELIGO_GET_CONNECTION_DEBUG_LOGS` | Get Connection Debug Logs | Tool to retrieve debug logs for a connection by its ID. Use optional resource_id parameter to filter logs by a specific import or export. |
| `CELIGO_GET_CONNECTION_DEPENDENCIES` | Get Connection Dependencies | Tool to retrieve all resources using or used by a specific connection. Use when you need to understand the dependencies of a Celigo connection, including imports, flows, and integrations that rely on it. |
| `CELIGO_GET_EDI_PROFILES` | Get EDI Profiles | Tool to retrieve all EDI profiles for the account. Use when you need to list Electronic Data Interchange (EDI) and B2B configurations. Returns empty array if no profiles are configured (HTTP 204). |
| `CELIGO_GET_EXPORT` | Get Export | Tool to retrieve a specific export by its ID from Celigo Integrator.io. Use when you need to fetch export configuration details including lifecycle hooks and provider settings. |
| `CELIGO_GET_EXPORT_AUDIT` | Get Export Audit Log | Tool to retrieve audit logs for a specific export in Celigo. Use when you need to track changes, modifications, or events related to an export resource. Returns a detailed history of field changes, events, timestamps, and user information. |
| `CELIGO_GET_EXPORT_ERRORS` | Get Export Errors | Tool to retrieve all open errors for a specific export within a flow. Use when you need to monitor export health, debug issues, or identify failed operations that require attention. |
| `CELIGO_GET_FILE_DEFINITION` | Get File Definition | Tool to retrieve a specific file definition by its ID from Celigo Integrator.io. Use when you need to fetch file definition details including name, type, and configuration. |
| `CELIGO_GET_FILE_DEFINITIONS` | Get File Definitions | Tool to retrieve all file definitions from Celigo. Use when you need to list file format definitions used for data transformation in integrations. |
| `CELIGO_GET_FLOW` | Get Flow by ID | Tool to retrieve a specific Celigo flow by its ID. Use when you need to fetch flow details, configuration, or metadata. Returns complete flow information including name, status, scheduling, and orchestration settings. |
| `CELIGO_GET_FLOW_AUDIT` | Get Flow Audit Logs | Tool to retrieve audit logs for a specific flow. Use when you need to track changes, events, and modifications made to a flow resource over time. Returns detailed history including field changes, timestamps, and user information. |
| `CELIGO_GET_FLOW_DEPENDENCIES` | Get Flow Dependencies | Tool to retrieve all resources using or used by a specific flow. Use when you need to understand the dependency graph of a Celigo flow, including imports, exports, connections, and other flows or integrations that reference it. |
| `CELIGO_GET_FLOW_DESCENDANTS` | Get Flow Descendants | Tool to retrieve all descendant resources of a specific flow. Use when you need to identify imports and exports that are children of a flow. |
| `CELIGO_GET_FLOW_LAST_EXPORT_DATETIME` | Get Flow Last Export Datetime | Tool to retrieve the last export datetime for a specific Celigo flow. Use when you need to check when a flow last exported data. Returns the timestamp or null if no export has occurred yet. |
| `CELIGO_GET_FLOW_LATEST_JOBS` | Get Flow Latest Jobs | Tool to retrieve the latest job executions for a specific flow. Use when you need to check recent flow run history, monitor job status, or review execution statistics and errors. |
| `CELIGO_GET_FLOW_TEMPLATE` | Get Flow Template | Tool to download a Celigo flow as a template. Use when you need to export a flow configuration as a downloadable template file. Returns a signed S3 URL that can be used to download the flow template as a zip file. |
| `CELIGO_GET_I_CLIENT` | Get iClient by ID | Tool to get a specific iClient by its ID. Use when you need to retrieve OAuth or provider-specific credential configurations for integrations. |
| `CELIGO_GET_IMPORT` | Get Import | Tool to retrieve a specific import by its ID from the Celigo Integrator API. Use when you need to fetch detailed configuration and settings for a particular import. |
| `CELIGO_GET_IMPORT_AUDIT` | Get Import Audit Logs | Tool to retrieve audit logs for a specific import. Use when you need to track changes, events, and modifications made to an import resource over time. Returns detailed history including field changes, timestamps, and user information. |
| `CELIGO_GET_IMPORT_DEPENDENCIES` | Get Import Dependencies | Tool to retrieve all resources using or used by a specific import. Use when you need to understand the dependency graph of an import, including flows and integrations that reference it. |
| `CELIGO_GET_INTEGRATION_AUDIT` | Get Integration Audit Logs | Tool to retrieve audit logs for a specific integration. Use when you need to track changes, modifications, or actions performed on an integration and its resources. |
| `CELIGO_GET_INTEGRATION_CONNECTIONS` | Get Integration Connections | Tool to retrieve all connections associated with a specific integration. Use when you need to list connections that are registered to or used by a particular integration. |
| `CELIGO_GET_INTEGRATION_DEPENDENCIES` | Get Integration Dependencies | Tool to retrieve all resources using or used by a specific integration. Use when you need to understand the dependency graph of a Celigo integration, including flows and other integrations that reference it. |
| `CELIGO_GET_INTEGRATION_ERRORS` | Get Integration Errors | Tool to retrieve all open errors for a specific integration in Celigo. Use when you need to monitor integration health, debug issues, or identify failed operations that require attention. |
| `CELIGO_GET_INTEGRATION_EXPORTS` | Get Integration Exports | Tool to retrieve all exports associated with a specific integration. Use when you need to list all exports configured within an integration, including their configurations and webhook settings. |
| `CELIGO_GET_INTEGRATION_FLOWS` | Get Integration Flows | Tool to retrieve all flows associated with a specific integration. Use when you need to list all data workflows configured within an integration, including their configuration, schedules, and status. |
| `CELIGO_GET_INTEGRATION_IMPORTS` | Get Integration Imports | Tool to retrieve all imports associated with a specific integration. Use when you need to list import configurations that are registered to or used by a particular integration. |
| `CELIGO_GET_INTEGRATION_TEMPLATE` | Get Integration Template | Tool to download a Celigo integration as a template. Use when you need to export an integration configuration as a downloadable template file. Returns a signed S3 URL that can be used to download the integration template as a zip file. |
| `CELIGO_GET_INTEGRATION_USERS` | Get Integration Users | Tool to retrieve users associated with a specific integration. Use when you need to list all users who have access to or are shared with a particular integration. |
| `CELIGO_GET_JOB_ERRORS` | Get Job Errors | Tool to retrieve errors for a specific job in Celigo. Supports pagination via page_size and page parameters to handle jobs with large numbers of errors. |
| `CELIGO_GET_RESOLVED_ERRORS` | Get Resolved Errors | Tool to retrieve resolved errors for a specific export within a flow in Celigo. Use when you need to review previously resolved errors, audit error resolution history, or track error patterns over time. |
| `CELIGO_GET_RESOURCE_STATE_VALUE` | Get Resource State Value | Tool to get the resource-specific value associated with a state key. Use when you need to retrieve state data for a specific resource (import, export, flow, or connection) in the Celigo Integrator platform. |
| `CELIGO_GET_SCRIPT` | Get Script | Tool to retrieve a specific script by its ID from Celigo. Use when you need to view script details, including code content, configuration, and metadata. |
| `CELIGO_GET_SCRIPT_LOGS` | Get Script Logs | Tool to retrieve logs for a specific Celigo script by its ID. Use when you need to view script execution logs, debug script behavior, or monitor script activity. |
| `CELIGO_GET_STATE_VALUE` | Get State Value | Tool to get the value associated with a specified state key. Use when you need to retrieve state data stored in the Celigo Integrator platform. |
| `CELIGO_GET_TAG` | Get Tag | Tool to retrieve a specific tag by its ID from Celigo Integrator.io. Use when you need to fetch tag details including tag name and tag identifier. |
| `CELIGO_GET_TAGS` | Get Tags | Tool to retrieve all tags from Celigo. Use when you need to list available tags for categorizing or organizing resources. |
| `CELIGO_GET_TOKEN_INFO` | Get Token Info | Tool to retrieve information about the current API token. Use when you need to validate the API token or get the user ID associated with it. |
| `CELIGO_GET_USER` | Get User Share | Tool to retrieve a specific user share (ashare) by its ID. Use when you need to fetch user access details including integration-level permissions and sharing information. |
| `CELIGO_GET_USERS` | Get All Users | Tool to retrieve all users from your Celigo account. Use when you need to list all users (account shares) across the account. |
| `CELIGO_INVITE_MULTIPLE_USERS` | Invite Multiple Users | Tool to invite multiple users to a Celigo account with specified access levels. Use when you need to grant multiple users access to your account or specific integrations. |
| `CELIGO_INVITE_USER` | Invite User | Tool to invite a user to a Celigo account with specified access levels. Use when you need to grant access to a new user via email. Either integration-level or account-level access must be specified. |
| `CELIGO_INVOKE_IMPORT` | Invoke Import | Tool to trigger/invoke a Celigo import by its ID. Use when you need to manually start an import process that has been configured in Celigo. |
| `CELIGO_LIST_AUDIT_LOGS` | List Audit Logs | Tool to retrieve all audit logs for resource changes. Use when you need to track changes, view history, or investigate modifications across all resources in the account. |
| `CELIGO_LIST_CONNECTIONS` | List Connections | Tool to retrieve all connections in Celigo. Use when you need to list stored credentials and configuration for integrated applications. Connections store authentication details and other information needed to access external systems. |
| `CELIGO_LIST_EXPORTS` | List Exports | Tool to retrieve all exports from Celigo integrator.io. Exports are used to extract data from an application. Use when you need to view available exports, monitor export configurations, or identify exports for further operations. |
| `CELIGO_LIST_FLOWS` | List Flows | Tool to retrieve all flows from Celigo. Flows compose exports and imports for data workflows between applications. |
| `CELIGO_LIST_I_CLIENTS` | List iClients | Tool to retrieve all iClients in Celigo. Use when you need to list authentication credentials used by SmartConnectors to access external APIs. iClients store the authentication data required for API connections. |
| `CELIGO_LIST_IMPORTS` | List Imports | Tool to retrieve all imports from Celigo integrator.io. Imports are used to insert data into an application. Use when you need to view all configured imports in the account. |
| `CELIGO_LIST_INTEGRATIONS` | List Integrations | Tool to retrieve all integrations from Celigo. Use when you need to list integrations that group flows with shared permissions and lifecycle. |
| `CELIGO_LIST_JOBS` | List Jobs | Fetches one page of jobs from Celigo with optional filters. Jobs track flow execution state while running and final statistics when finished. ONE Celigo API call is made per invocation; pagination is caller-driven via the `created_at_lte` parameter (Celigo's keyset-by-`createdAt` cursor) and the `next_cursor` field in the response. |
| `CELIGO_LIST_LICENSES` | List Licenses | Tool to retrieve all SmartConnector licenses in Celigo. Use when you need to list platform-level licensing information including connector editions, add-on licenses, expiration dates, and associated users. |
| `CELIGO_LIST_RESOURCE_STATE` | List Resource State | Tool to retrieve all state keys for a specific resource in Celigo. Use when you need to list keys that store execution context and tracking information for imports, exports, flows, or integrations. |
| `CELIGO_LIST_STATE_KEYS` | List State Keys | Tool to retrieve all global state keys from Celigo. Use when you need to list available keys for storing arbitrary JSON data. State keys are used to store execution context and tracking information for flows. |
| `CELIGO_PARSE_CSV_TO_JSON` | Parse CSV to JSON | Tool to convert CSV data to JSON format using Celigo's CSV parser. Use when you need to parse CSV strings into structured JSON objects for further processing or integration workflows. |
| `CELIGO_PARSE_STRUCTURED_FILE` | Parse Structured File | Tool to convert EDI or structured file data (delimited or fixed-width) to JSON format. Use when you need to parse structured file content with specific field definitions and delimiters. |
| `CELIGO_PARSE_XML_TO_JSON` | Parse XML to JSON | Tool to convert XML data to JSON format using Celigo's XML parser processor. Use when you need to transform XML strings into structured JSON objects for easier data manipulation and integration. |
| `CELIGO_PATCH_CONNECTION` | Patch Connection | Tool to update part of a connection using JSON Patch operations (RFC 6902). Use when you need to modify specific fields of an existing connection without replacing the entire resource. |
| `CELIGO_PATCH_EXPORT` | Patch Export | Tool to update specific fields of an export using JSON Patch operations. Use when you need to modify export properties without replacing the entire configuration. Note: Only certain fields are whitelisted for patching (e.g., /aiDescription/summary). |
| `CELIGO_PATCH_FLOW` | Patch Flow | Tool to update part of a specific flow using JSON Patch operations (RFC 6902). Use when you need to modify specific fields of a flow without replacing the entire resource, such as enabling/disabling a flow or updating its name. |
| `CELIGO_PATCH_ICLIENT` | Patch iClient | Tool to update part of an iClient using JSON Patch operations (RFC 6902). Use when you need to modify specific fields of an existing iClient without replacing the entire resource. Note: the iClient PATCH endpoint has very restrictive field whitelisting. |
| `CELIGO_PATCH_IMPORT` | Patch Import | Tool to update specific fields of an import using JSON Patch operations. Use when you need to modify import properties without replacing the entire configuration. Note: Only certain fields are whitelisted for patching - many common fields cannot be modified via PATCH. |
| `CELIGO_PATCH_INTEGRATION` | Patch Integration | Tool to update part of an integration using JSON Patch operations (RFC 6902). Use when you need to modify specific fields of an existing integration without replacing the entire resource. |
| `CELIGO_PING_CONNECTION` | Ping Connection | Test that a specific Celigo connection is operational by pinging it. Use this to verify that connection credentials and configuration are valid and the external application is reachable. |
| `CELIGO_REGISTER_CONNECTION` | Register Connection | Tool to register a connection to an integration in Celigo. Use when you need to link a connection resource to a specific integration. |
| `CELIGO_REGISTER_CONNECTIONS_BULK` | Register Connections Bulk | Tool to register multiple connections to an integration in Celigo at once. Use when you need to associate multiple connections with an integration. Note: This operation replaces all previously registered connections with the provided list. |
| `CELIGO_RESOLVE_ERRORS` | Resolve Errors | Tool to resolve specified errors for an export in Celigo. Use when you need to mark errors as resolved for a specific export within a flow. |
| `CELIGO_RETRY_ERRORS` | Retry Errors | Tool to retry specified errors for an export in Celigo. Use when you need to re-process failed records or operations in a flow export. |
| `CELIGO_TEST_VIRTUAL_CONNECTION` | Test Virtual Connection | Test a virtual connection where all details are submitted in the POST body but not saved. Use when you need to validate connection settings before creating a permanent connection. |
| `CELIGO_UNREGISTER_CONNECTION` | Unregister Connection from Integration | Tool to unregister a connection from an integration in Celigo. Use when you need to remove a connection from an integration's registered connections list. Returns success status on completion. |
| `CELIGO_UPDATE_CONNECTION` | Update Connection | Tool to update a connection's configuration or credentials in Celigo. Use when you need to modify connection settings, update credentials, or change connection properties. Note: PUT requests replace the entire connection object, so the 'type' field is mandatory. |
| `CELIGO_UPDATE_EXPORT` | Update Export | Tool to update an existing export configuration in Celigo. Use when you need to modify export settings such as name, connection, type, page size, or adaptor-specific configurations like NetSuite restlets or webhook providers. |
| `CELIGO_UPDATE_FLOW` | Update Flow | Tool to update a specific flow's configuration in Celigo. Use when you need to modify flow settings such as name, enabled/disabled state, schedule, routers, or other flow configuration properties. The API performs a full replacement of the flow configuration, so ensure all required fields are provided. |
| `CELIGO_UPDATE_FLOW_ERROR_TAGS` | Update Flow Error Tags | Tool to update error tags for a specific flow export in Celigo. Use when you need to assign tags to errors for categorization, or remove existing tags by providing an empty array. Maximum 3 tags can be assigned per operation. |
| `CELIGO_UPDATE_I_CLIENT` | Update iClient | Tool to update a specific iClient's configuration in Celigo. Use when you need to modify iClient settings such as name, provider, published state, JWT settings, or form type. |
| `CELIGO_UPDATE_IMPORT` | Update Import | Tool to update a specific import's configuration in Celigo. Use when modifying existing import settings, connection details, file configurations, or HTTP settings. |
| `CELIGO_UPDATE_INTEGRATION` | Update Integration | Tool to update a specific integration's configuration in Celigo. Use when you need to modify integration settings such as name, version, installation steps, or flow groupings. |
| `CELIGO_UPDATE_RESOURCE_STATE_VALUE` | Update Resource State Value | Tool to create or update the resource-specific state value for any Celigo resource type. Use when you need to store or modify state data associated with a specific resource (import, export, flow, connection, etc.). |
| `CELIGO_UPDATE_SCRIPT` | Update Script | Tool to update a specific script's code or configuration in Celigo. Use when you need to modify script content, change script settings, or update sandbox mode. |
| `CELIGO_UPDATE_STATE_VALUE` | Update State Value | Tool to create or update the value associated with a specified state key. Use when you need to store or modify state data in the Celigo Integrator platform. |
| `CELIGO_UPDATE_TAG` | Update Tag | Tool to update a tag's name in Celigo. Use when you need to rename an existing tag. |
| `CELIGO_UPDATE_USER` | Update User | Tool to update a specific user's account in Celigo. Use when you need to modify a user's integration access levels or permissions. The API returns HTTP 204 No Content on successful update. |

## Supported Triggers

None listed.

## Creating MCP Server - Stand-alone vs Composio SDK

The Celigo MCP server is an implementation of the Model Context Protocol that connects your AI agent to Celigo. It provides structured and secure access so your agent can perform Celigo operations on your behalf through a secure, permission-based interface.
With Composio's managed implementation, you don't have to create your own developer app. For production, if you're building an end product, we recommend using your own credentials. The managed server helps you prototype fast and go from 0-1 faster.

## Step-by-step Guide

### 1. Prerequisites

Before starting, make sure you have:
- Node.js 18 or higher
- A Composio account with an active API key
- An OpenAI API key
- Basic familiarity with TypeScript

### 1. Getting API Keys for OpenAI and Composio

OpenAI API Key
- Go to the [OpenAI dashboard](https://platform.openai.com/settings/organization/api-keys) and create an API key.
- You need credits or a connected billing setup to use the models.
- Store the key somewhere safe.
Composio API Key
- Log in to the [Composio dashboard](https://dashboard.composio.dev?utm_source=toolkits&utm_medium=framework_docs).
- Go to Settings and copy your API key.
- This key lets your Mastra agent talk to Composio and reach Celigo through MCP.

### 2. Install dependencies

Install the required packages.
What's happening:
- @composio/core is the Composio SDK for creating MCP sessions
- @mastra/core provides the Agent class
- @mastra/mcp is Mastra's MCP client
- @ai-sdk/openai is the model wrapper for OpenAI
- dotenv loads environment variables from .env
```bash
npm install @composio/core @mastra/core @mastra/mcp @ai-sdk/openai dotenv
```

### 3. Set up environment variables

Create a .env file in your project root.
What's happening:
- COMPOSIO_API_KEY authenticates your requests to Composio
- COMPOSIO_USER_ID tells Composio which user this session belongs to
- OPENAI_API_KEY lets the Mastra agent call OpenAI models
```bash
COMPOSIO_API_KEY=your_composio_api_key_here
COMPOSIO_USER_ID=your_user_id_here
OPENAI_API_KEY=your_openai_api_key_here
```

### 4. Import libraries and validate environment

What's happening:
- dotenv/config auto loads your .env so process.env.* is available
- openai gives you a Mastra compatible model wrapper
- Agent is the Mastra agent that will call tools and produce answers
- MCPClient connects Mastra to your Composio MCP server
- Composio is used to create a Tool Router session
```typescript
import "dotenv/config";
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { MCPClient } from "@mastra/mcp";
import { Composio } from "@composio/core";
import * as readline from "readline";

import type { AiMessageType } from "@mastra/core/agent";

const openaiAPIKey = process.env.OPENAI_API_KEY;
const composioAPIKey = process.env.COMPOSIO_API_KEY;
const composioUserID = process.env.COMPOSIO_USER_ID;

if (!openaiAPIKey) throw new Error("OPENAI_API_KEY is not set");
if (!composioAPIKey) throw new Error("COMPOSIO_API_KEY is not set");
if (!composioUserID) throw new Error("COMPOSIO_USER_ID is not set");

const composio = new Composio({
  apiKey: composioAPIKey as string,
});
```

### 5. Create a Tool Router session for Celigo

What's happening:
- create spins up a short-lived MCP HTTP endpoint for this user
- The toolkits array contains "celigo" for Celigo access
- session.mcp.url is the MCP URL that Mastra's MCPClient will connect to
```typescript
async function main() {
  const session = await composio.create(
    composioUserID as string,
    {
      toolkits: ["celigo"],
    },
  );

  const composioMCPUrl = session.mcp.url;
  console.log("Celigo MCP URL:", composioMCPUrl);
```

### 6. Configure Mastra MCP client and fetch tools

What's happening:
- MCPClient takes an id for this client and a list of MCP servers
- The headers property includes the x-api-key for authentication
- getTools fetches the tool definitions exposed by the Celigo toolkit
```typescript
const mcpClient = new MCPClient({
    id: composioUserID as string,
    servers: {
      nasdaq: {
        url: new URL(composioMCPUrl),
        requestInit: {
          headers: session.mcp.headers,
        },
      },
    },
    timeout: 30_000,
  });

console.log("Fetching MCP tools from Composio...");
const composioTools = await mcpClient.getTools();
console.log("Number of tools:", Object.keys(composioTools).length);
```

### 7. Create the Mastra agent

What's happening:
- Agent is the core Mastra agent
- name is just an identifier for logging and debugging
- instructions guide the agent to use tools instead of only answering in natural language
- model uses openai("gpt-5") to configure the underlying LLM
```typescript
const agent = new Agent({
    name: "celigo-mastra-agent",
    instructions: "You are an AI agent with Celigo tools via Composio.",
    model: "openai/gpt-5",
  });
```

### 8. Set up interactive chat interface

What's happening:
- messages keeps the full conversation history in Mastra's expected format
- agent.generate runs the agent with conversation history and Celigo toolsets
- maxSteps limits how many tool calls the agent can take in a single run
- onStepFinish is a hook that prints intermediate steps for debugging
```typescript
let messages: AiMessageType[] = [];

console.log("Chat started! Type 'exit' or 'quit' to end.\n");

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  prompt: "> ",
});

rl.prompt();

rl.on("line", async (userInput: string) => {
  const trimmedInput = userInput.trim();

  if (["exit", "quit", "bye"].includes(trimmedInput.toLowerCase())) {
    console.log("\nGoodbye!");
    rl.close();
    process.exit(0);
  }

  if (!trimmedInput) {
    rl.prompt();
    return;
  }

  messages.push({
    id: crypto.randomUUID(),
    role: "user",
    content: trimmedInput,
  });

  console.log("\nAgent is thinking...\n");

  try {
    const response = await agent.generate(messages, {
      toolsets: {
        celigo: composioTools,
      },
      maxSteps: 8,
    });

    const { text } = response;

    if (text && text.trim().length > 0) {
      console.log(`Agent: ${text}\n`);
        messages.push({
          id: crypto.randomUUID(),
          role: "assistant",
          content: text,
        });
      }
    } catch (error) {
      console.error("\nError:", error);
    }

    rl.prompt();
  });

  rl.on("close", async () => {
    console.log("\nSession ended.");
    await mcpClient.disconnect();
    process.exit(0);
  });
}

main().catch((err) => {
  console.error("Fatal error:", err);
  process.exit(1);
});
```

## Complete Code

```typescript
import "dotenv/config";
import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { MCPClient } from "@mastra/mcp";
import { Composio } from "@composio/core";
import * as readline from "readline";

import type { AiMessageType } from "@mastra/core/agent";

const openaiAPIKey = process.env.OPENAI_API_KEY;
const composioAPIKey = process.env.COMPOSIO_API_KEY;
const composioUserID = process.env.COMPOSIO_USER_ID;

if (!openaiAPIKey) throw new Error("OPENAI_API_KEY is not set");
if (!composioAPIKey) throw new Error("COMPOSIO_API_KEY is not set");
if (!composioUserID) throw new Error("COMPOSIO_USER_ID is not set");

const composio = new Composio({ apiKey: composioAPIKey as string });

async function main() {
  const session = await composio.create(composioUserID as string, {
    toolkits: ["celigo"],
  });

  const composioMCPUrl = session.mcp.url;

  const mcpClient = new MCPClient({
    id: composioUserID as string,
    servers: {
      celigo: {
        url: new URL(composioMCPUrl),
        requestInit: {
          headers: session.mcp.headers,
        },
      },
    },
    timeout: 30_000,
  });

  const composioTools = await mcpClient.getTools();

  const agent = new Agent({
    name: "celigo-mastra-agent",
    instructions: "You are an AI agent with Celigo tools via Composio.",
    model: "openai/gpt-5",
  });

  let messages: AiMessageType[] = [];

  const rl = readline.createInterface({
    input: process.stdin,
    output: process.stdout,
    prompt: "> ",
  });

  rl.prompt();

  rl.on("line", async (input: string) => {
    const trimmed = input.trim();
    if (["exit", "quit"].includes(trimmed.toLowerCase())) {
      rl.close();
      return;
    }

    messages.push({ id: crypto.randomUUID(), role: "user", content: trimmed });

    const { text } = await agent.generate(messages, {
      toolsets: { celigo: composioTools },
      maxSteps: 8,
    });

    if (text) {
      console.log(`Agent: ${text}\n`);
      messages.push({ id: crypto.randomUUID(), role: "assistant", content: text });
    }

    rl.prompt();
  });

  rl.on("close", async () => {
    await mcpClient.disconnect();
    process.exit(0);
  });
}

main();
```

## Conclusion

You've built a Mastra AI agent that can interact with Celigo through Composio's Tool Router.
You can extend this further by:
- Adding other toolkits like Gmail, Slack, or GitHub
- Building a web-based chat interface around this agent
- Using multiple MCP endpoints to enable cross-app workflows

## How to build Celigo MCP Agent with another framework

- [OpenAI Agents SDK](https://composio.dev/toolkits/celigo/framework/open-ai-agents-sdk)
- [Claude Agent SDK](https://composio.dev/toolkits/celigo/framework/claude-agents-sdk)
- [Claude Code](https://composio.dev/toolkits/celigo/framework/claude-code)
- [Claude Cowork](https://composio.dev/toolkits/celigo/framework/claude-cowork)
- [Codex](https://composio.dev/toolkits/celigo/framework/codex)
- [OpenClaw](https://composio.dev/toolkits/celigo/framework/openclaw)
- [Hermes](https://composio.dev/toolkits/celigo/framework/hermes-agent)
- [CLI](https://composio.dev/toolkits/celigo/framework/cli)
- [Google ADK](https://composio.dev/toolkits/celigo/framework/google-adk)
- [LangChain](https://composio.dev/toolkits/celigo/framework/langchain)
- [Vercel AI SDK](https://composio.dev/toolkits/celigo/framework/ai-sdk)
- [LlamaIndex](https://composio.dev/toolkits/celigo/framework/llama-index)
- [CrewAI](https://composio.dev/toolkits/celigo/framework/crew-ai)

## Related Toolkits

- [Apify MCP](https://composio.dev/toolkits/apify_mcp) - Apify MCP is the official MCP server for Apify's web scraping and browser automation platform. Use it to run actors, collect structured web data, and automate crawling workflows.
- [Apilio](https://composio.dev/toolkits/apilio) - Apilio is a home automation platform that lets you connect and control smart devices from different brands. It helps you build flexible automations with complex conditions, schedules, and integrations.
- [Basin](https://composio.dev/toolkits/basin) - Basin is a no-code form backend for quickly setting up reliable contact forms. It lets you collect and manage form submissions without writing any server-side code.
- [Bouncer](https://composio.dev/toolkits/bouncer) - Bouncer is an email validation platform that verifies the authenticity of email addresses in real-time and batch. It helps boost deliverability and reduce bounce rates for your communications.
- [Conveyor](https://composio.dev/toolkits/conveyor) - Conveyor is a platform that automates security reviews with a Trust Center and AI-driven questionnaire automation. It streamlines compliance and vendor security processes for faster, hassle-free reviews.
- [Crowdin](https://composio.dev/toolkits/crowdin) - Crowdin is a localization management platform that streamlines translation workflows and collaboration. It helps teams centralize multilingual content, boost productivity, and automate translation processes.
- [Databox](https://composio.dev/toolkits/databox) - Databox is a business analytics platform that connects your data from any tool and device. It helps you track KPIs, build dashboards, and discover actionable insights.
- [Detrack](https://composio.dev/toolkits/detrack) - Detrack is a delivery management platform for real-time tracking and proof of delivery. It helps businesses automate notifications and keep customers updated every step of the way.
- [Dnsfilter](https://composio.dev/toolkits/dnsfilter) - Dnsfilter is a cloud-based DNS security and content filtering solution. It helps organizations block online threats and manage safe internet access with ease.
- [Faraday](https://composio.dev/toolkits/faraday) - Faraday lets you embed AI in workflows across your stack for smarter automation. It boosts your favorite tools with actionable intelligence and seamless integration.
- [Feathery](https://composio.dev/toolkits/feathery) - Feathery is an AI-powered platform for building dynamic data intake forms with advanced logic. It helps teams automate complex workflows and collect structured data with ease.
- [Fillout forms](https://composio.dev/toolkits/fillout_forms) - Fillout forms is an online platform for building and managing forms with a flexible API. It lets you create, distribute, and collect responses from forms with ease.
- [Formdesk](https://composio.dev/toolkits/formdesk) - Formdesk is an online form builder for creating and managing professional forms. It's perfect for collecting data, automating workflows, and integrating form submissions with your favorite services.
- [Formsite](https://composio.dev/toolkits/formsite) - Formsite lets you build online forms and surveys with drag-and-drop simplicity. Capture, manage, and integrate form responses securely for streamlined workflows.
- [Graphhopper](https://composio.dev/toolkits/graphhopper) - GraphHopper is an enterprise-grade Directions API for routing, optimization, and geocoding across multiple vehicle types. It enables fast, reliable route planning and logistics automation for businesses.
- [Hyperbrowser](https://composio.dev/toolkits/hyperbrowser) - Hyperbrowser is a next-generation platform for scalable browser automation. It empowers AI agents to interact with web apps, automate workflows, and handle browser sessions at scale.
- [La Growth Machine](https://composio.dev/toolkits/lagrowthmachine) - La Growth Machine automates multi-channel sales outreach and routine tasks for sales teams. Streamline your workflow and focus on closing more deals.
- [Leverly](https://composio.dev/toolkits/leverly) - Leverly is a workflow automation platform that connects and coordinates actions across your apps. It streamlines repetitive processes so your business runs smoother, faster, and with fewer manual steps.
- [Maintainx](https://composio.dev/toolkits/maintainx) - Maintainx is a cloud-based CMMS for centralizing maintenance data, communication, and workflows. It helps organizations streamline maintenance operations and improve team coordination.
- [Make](https://composio.dev/toolkits/make) - Make is an automation platform that connects your favorite apps and services. Build powerful, custom workflows without writing code.

## Frequently Asked Questions

### What are the differences in Tool Router MCP and Celigo MCP?

With a standalone Celigo MCP server, the agents and LLMs can only access a fixed set of Celigo tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Celigo and many other apps based on the task at hand, all through a single MCP endpoint.

### Can I use Tool Router MCP with Mastra AI?

Yes, you can. Mastra AI fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Celigo tools.

### Can I manage the permissions and scopes for Celigo while using Tool Router?

Yes, absolutely. You can configure which Celigo scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

### How safe is my data with Composio Tool Router?

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Celigo data and credentials are handled as safely as possible.

---
[See all toolkits](https://composio.dev/toolkits) · [Composio docs](https://docs.composio.dev/llms.txt)