AI INTEGRATIONS · CELIGO + CLAUDE
How to Connect a Customer's Custom Celigo MCP Server to Claude
This custom MCP server tutorial shows Hairball customers how to connect an AI agent to Celigo step by step.
If you have already built an MCP server inside your own Celigo account, this guide walks you through wiring it into Claude Desktop so the assistant can call your tools and APIs on demand. We will use a real Hairball example to show what is happening under the hood, then drop you a copy-paste configuration to get connected in minutes.
01 · SCOPE
Who this guide is for
This guide is for Hairball customers who already operate a Celigo account and have built (or want to expose) a custom MCP server. The goal is for Claude to be able to invoke that MCP server from a chat, so end users can ask questions in natural language and the assistant fulfills them through your existing Celigo integrations.
This is not about connecting to the standard MCP server that Celigo ships out of the box, and it is not about exposing the integrator.io API itself to Claude. The subject here is the MCP you own, sitting on top of your own flows, exports, imports, and connections.
02 · CONCEPT
What a Celigo MCP server actually does
An MCP server in Celigo is a thin exposure layer. It takes the building blocks you already have in your account (Tools and builder-mode APIs) and publishes them as callable endpoints for an AI agent. The agent does not see SuiteQL, GraphQL, mappings, or connections. It sees a clean tool with a name, a description, and an input schema. When it calls the tool, Celigo executes the full pipeline behind it and returns a structured response.
The chain looks like this:
Claude → MCP server → API or Tool → Export / Import → External system
The two key concepts to keep separate:
- The MCP server. A small resource in Celigo with a name, a URL path, and a list of Tools and APIs to expose. No business logic lives here.
- The underlying API or Tool. The actual pipeline. Validates input, calls exports and imports against the connections you already trust, shapes the response.
Build the pipeline once. Expose it everywhere.
03 · BEHIND THE SCENES
One MCP, one API, the full pipeline
Here is a concrete example from Hairball’s own Celigo account. We built an MCP server called “Get orders” that exposes two tools to any AI client: one that pulls orders out of NetSuite via SuiteQL, and one that pulls orders out of Shopify via GraphQL. Below we walk through the Shopify one to show what happens the moment Claude invokes it.
MCP SERVER · HAIRBALL INC ACCOUNT
Get orders
relativeURI: /getorders · exposes 2 builder-mode APIs
- Claude calls the MCP tool Pull_Shopify_orders_through_GraphQL, passing a startdate and an enddate in YYYY-MM-DD format. That schema is declared on the Celigo API resource itself, so Claude knows exactly what arguments to send.
- The MCP server routes the call to the linked builder-mode API. No code in the middle, no glue layer to maintain.
- The API validates the request body against its declared schema and runs the configured router branch.
- The branch executes a single page processor: a Celigo export that issues a GraphQL query to Shopify using the stored Shopify connection. That connection holds the API credentials, the rate-limit budget, and the version pinning. Your team configured it once.
- Shopify returns the matching orders. The API’s response mapping picks the data field, places it under an orders key, and the API returns a clean JSON object.
- Claude receives the structured response and uses it to answer the user’s question.
From the customer’s side, no SuiteQL or GraphQL was written by hand. From Claude’s side, no Shopify SDK, no token, no rate limit handling. The MCP server is the seam between the AI assistant and your battle-tested Celigo pipelines.
04 · SETUP
Connect the MCP to Claude Desktop Celigo MCP server setup
Claude Desktop talks to your MCP through a small local proxy called mcp-remote, which takes the remote HTTPS endpoint and presents it to Claude as a local MCP server. You only need three things: a Celigo API token, your MCP server URL, and a small change to Claude Desktop’s config file.
- Create a Celigo API token. In Celigo, open your profile menu, go to My account → API tokens, and create a token scoped to the user that owns the MCP server’s connections. Copy the token value once. Treat it like a production credential.
- Locate your MCP server URL. The pattern is https://api.integrator.io/mcp/v1<relativeURI>. For example, the Hairball “Get orders” server lives at https://api.integrator.io/mcp/v1/getorders. Use the relativeURI shown on your own MCP server resource in Celigo.
- Open Claude Desktop’s config file. On macOS the file is at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows it is at %APPDATA%\Claude\claude_desktop_config.json. If the file does not exist yet, create it with an empty JSON object.
- Add your MCP server. Paste the snippet below into the mcpServers section. Replace YOUR_RELATIVE_URI with your server’s path and YOUR_CELIGO_TOKEN with the token from step 1.
- Quit and reopen Claude Desktop. When it relaunches, the tools your MCP exposes should appear in the tool selector. Ask Claude to use one of them to confirm the wiring.
claude_desktop_config.json
{ “mcpServers”: { “celigo-get-orders”: { “command”: “npx”, “args”: [ “-y”, “mcp-remote”, “https://api.integrator.io/mcp/v1/YOUR_RELATIVE_URI”, “–header”, “Authorization: Bearer YOUR_CELIGO_TOKEN” ] } } }
// Example using Hairball’s “Get orders” MCP server: // “https://api.integrator.io/mcp/v1/getorders” |
Need Node.js? `mcp-remote` is run via npx, which ships with Node.js. If npx is not on your machine, install Node.js LTS first from nodejs.org. Once installed, no further setup is required, npx -y mcp-remote will download and run the proxy on demand. |
05 · AUTHENTICATION
Token-based, by design
The Celigo MCP server authenticates incoming requests with a Celigo API bearer token. That is the token you generated in step 1, and that is the same token mcp-remote forwards on every call from Claude. Outbound calls from your APIs and Tools (the ones that actually hit Shopify, NetSuite, or any other system) use the connections you already configured in Celigo, with their own credentials. The MCP layer never sees those.
A few rules to keep this safe in production:
- Use a token tied to a Celigo user with only the access the exposed tools actually need.
- Rotate the token on a schedule and immediately if a workstation is lost.
- Never commit claude_desktop_config.json to git, the token lives in plain text there.
- For shared environments, prefer a service-style user in Celigo over a personal account.
06 · TRY IT
Useful prompts to test the wiring
Once Claude Desktop has loaded the MCP server, ask it something that forces it to call the tool. If everything is connected, Claude will request your approval to use the tool, run it, and answer using the data it pulled back from Celigo.
- Use the Celigo MCP to pull all Shopify orders placed between May 1 and May 7, 2026, and summarize them by status.
- Run the NetSuite SuiteQL tool from my Celigo MCP for the last 7 days. How many sales orders came in and what is the total amount?
- Compare the Shopify and NetSuite order counts for last week using the tools from my Celigo MCP. Flag anything that does not match.
TALK TO HAIRBALL
We build the Celigo MCP servers your AI assistants actually need
If your team wants Claude (or any MCP-aware agent) to act on real business data through Celigo, Hairball designs the pipelines, exposes them as MCP tools, and wires them into your AI workflows end to end. The example in this guide is a small slice of what is possible.
Frequently Asked Questions
What is a Celigo MCP server?
A Celigo MCP server is a thin exposure layer inside your integrator.io account that publishes your existing Tools and builder-mode APIs as callable endpoints for AI agents. It lets a model like Claude invoke your Celigo pipelines without seeing the underlying SuiteQL, GraphQL, or connection credentials.
How do I connect a custom Celigo MCP to Claude Desktop?
You need three things: a Celigo API token, your MCP server URL (in the format https://api.integrator.io/mcp/v1/<relativeURI>), and an entry in Claude Desktop’s claude_desktop_config.json file that runs mcp-remote against your endpoint. Total Celigo MCP server setup time is under 10 minutes once you have a server built.
Do I need to write code to expose Celigo tools to Claude?
No. The MCP server itself holds no business logic. Your existing exports, imports, mappings, and connections do the work. The MCP layer simply makes them discoverable to an AI agent.
Is the Celigo API token secure when used with Claude Desktop?
The token is stored in plain text inside claude_desktop_config.json on the local machine. To follow MCP authentication best practices, scope the token to a Celigo user with only the access the exposed tools require, rotate it on a schedule, never commit the config file to git, and use a service-style account in shared environments.
Can Claude pull NetSuite and Shopify data through Celigo?
Yes. Once your MCP server exposes Tools backed by Celigo exports, Claude can run natural language NetSuite queries (via SuiteQL) and pull Shopify orders, customers, or products (via GraphQL) through the same authenticated pipeline your integrations already use.
What does Hairball do for customers building Celigo MCP servers?
Hairball designs the underlying pipelines, exposes them as MCP tools, handles authentication and rate limits, and wires the result into Claude or any MCP-aware AI agent. We focus on AI for NetSuite operations and AI for Shopify operations so the assistant can act on real business data, not just describe it.
