Connect Custom Celigo MCP Server to Claude Desktop

You've built a custom MCP server inside Celigo that exposes your NetSuite and Shopify flows as callable tools. Now you need Claude Desktop to actually invoke them. The documentation skips the part where the desktop app refuses to recognize the server, or the authentication handshake fails silently. This walkthrough covers the exact configuration steps, the two connection methods Celigo supports, and the validation checks that confirm the integration works end to end.

Prerequisites Before You Start

• A Celigo account with Platform Admin or Integration Owner permissions
• A published custom MCP server in that Celigo account (not the out-of-the-box Celigo MCP)
• The MCP server URL, format: https://<your-tenant>.celigo.com/mcp/<server-name>
• Claude Desktop version 0.8.0 or later (earlier builds lack the Connectors UI)
• NetSuite credentials with REST Web Services and Token-Based Authentication roles if your flows touch NetSuite records

The MCP server must be published from the Celigo designer before it appears in the connector list. Draft versions are not discoverable.

Method 1: Connect via Claude Desktop Connectors UI (Recommended)

This is the path Celigo documents officially and the one that handles token refresh automatically.

Step 1: Open Claude Desktop. Click the gear icon (Settings) in the lower-left corner, then select Connectors from the sidebar.

Step 2: Click Add custom connector. A modal appears with two fields:

• Name: Enter a label you'll recognize, e.g., Celigo-Prod-MCP
• MCP Server URL: Paste your full server URL exactly as shown in Celigo (including https://)

Step 3: Click Add. Claude immediately opens a browser window to the Celigo OAuth consent screen.

Step 4: Sign in with your Celigo credentials. If your organization uses SSO, you'll hit your IdP first. Grant the requested scopes, mcp:read, mcp:execute, and offline_access are required.

Step 5: After consent, the browser redirects back to Claude Desktop. The connector shows Connected with a green dot. The tools exposed by your MCP server now appear under the Search and tools icon (magnifying glass) in any new chat.

Method 2: Connect via Configuration File (Advanced)

Use this if you're on a managed device that blocks the Connectors UI, or if you need to pre-provision the connection for multiple users.

Step 1: Locate the Claude Desktop config file:

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

Step 2: Open the file (create it if missing) and add your server under mcpServers:

{
  "mcpServers": {
    "Celigo-Prod-MCP": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-tenant.celigo.com/mcp/your-server-name"
      ]
    }
  }
}

Step 3: Save the file and fully quit Claude Desktop (Cmd+Q / Ctrl+Q, not just close window). Relaunch.

Step 4: Open a new chat. Click the Search and tools icon. Your server appears under Edit config with a Connect button. Click it, the same OAuth flow launches in your browser.

The mcp-remote package is a lightweight proxy that handles the stdio-to-HTTP translation MCP requires. It ships via npx so you don't need a global install.

Validation: Prove the Handshake Works

Don't assume success because the UI shows green. Run this sequence:

1. List tools: In a new chat, type @ and scroll to your connector name. You should see every flow the MCP server exposes, each with its input schema. If the list is empty, the server published but has no Public flows. Check the Celigo designer: each flow must have Expose as MCP Tool enabled.

2. Execute a read-only flow first: Pick a flow that only queries data (e.g., "Get NetSuite Sales Orders by Date Range"). Provide valid parameters. Claude should return structured JSON within 10–15 seconds.

3. Execute a write flow: Run a flow that creates or updates a NetSuite record (e.g., "Create Shopify Order in NetSuite"). Verify the record appears in NetSuite with the correct External ID mapping.

4. Check the Celigo execution log: In Celigo, go to Monitor > Execution Logs. Filter by your MCP server name. Every Claude invocation appears as a separate run with the payload Claude sent and the response Celigo returned. This is your audit trail.

Common Failure Points

Edge Cases Worth Knowing

Multiple Celigo environments: If you maintain separate Dev/Test/Prod tenants, create a distinct connector for each (e.g., Celigo-Dev-MCP, Celigo-Prod-MCP). The config file method lets you define all three simultaneously; the UI method requires switching connections manually.

Rate limiting: Celigo enforces 100 requests/minute per MCP server by default. If your Claude conversation triggers rapid parallel calls, you'll hit 429 responses. Build retry logic into your flows using Celigo's Retry Policy setting (Exponential Backoff, max 3 attempts).

Schema drift: When you modify a flow's input/output schema in Celigo, republish the MCP server. Claude caches schemas for the session. Start a new chat to pick up changes, no need to reconnect.

NetSuite concurrency governance: Each MCP tool execution runs in its own Celigo integration flow, which consumes a NetSuite concurrency slot if it touches NetSuite. Ten concurrent Claude users = ten concurrent NetSuite connections. Monitor Setup > Integration > Web Services Usage to avoid governance violations. The NetSuite Basics Guide covers navigation to these administration pages.

What to Check Next

You've connected the pipe. Now harden it: add execution logging to a NetSuite custom record so every AI-initiated transaction leaves a traceable audit trail, and set up a Celigo alert on the MCP server for error rates above 5%. The integration is live, the operational discipline keeps it that way.

When you're navigating NetSuite to configure these monitoring records, the Navigation Portlet can save clicks by pinning your most-used administration shortcuts directly on your dashboard.