Before you start to use our MCP, please review the following items:

Ensure you have completed the iPaaS.com platform training before using this to best understand what is going on. If you need to gain access to it reach out to partnerships@ipaas.com.
With great power comes great responsibility - the MCP can do things like trigger a sync for your entire catalog and modify (or remove) data from your account. Ensure you understand what you want it to do before you work with it. iPaaS.com is not responsible for restoring any data or configuration changes made using the MCP.
- Keep this in mind when selecting API permissions below and feel free to start with fewer permissions and add from there.
Measure twice, cut once: When working with this, planning ahead of time (or asking the MCP to plan for you) will greatly benefit your work.
Remember that this is in beta so some features may be added, removed or altered as we continue our development. The latest change log notes can be found here.
If you have any issues or need to report a bug please reach out to us at mcp@ipaas.com.

This article takes you from nothing to a working connection. Allow about ten minutes, most of it spent choosing permissions.

What you need

An iPaaS.com account with permission to manage API keys (the Manage API Keys permission - this should be enabled on the Company Admin role).
An AI assistant that supports MCP, such as Claude (custom connector, Claude Desktop or Claude Code), Cursor, VS Code with GitHub Copilot, Gemini CLI, or another app that can connect to a remote MCP server (Step 4).
Node.js, only if you connect Claude Desktop through its configuration file (Step 3). Every other method in Step 4 works without it.

Step 1: Create an API key

Your API key is how the MCP accesses your account. The MCP server holds no credentials of its own. Every request carries your key, and the key alone decides which company you see and what you can do. Treat it like a password.

Follow the steps in API Keys to create one, and keep these points in mind:

Use an API key, not your sign-in token. The bearer token you receive when you sign in expires, and once it does every call fails with a 401 error that looks like a permissions problem.
You choose the expiration when you create the key: 60 days, 90 days, 120 days or Never Expires. When a key expires, every tool starts returning 401. Create a new key and update your connection settings.
An API key can't be edited after it is created. If you need different permissions later, create a new key. Decide on permissions before you click Apply (Step 2).
Copy the key somewhere safe. Never paste it into a chat with the assistant.

Step 2: Choose the key's permissions

The key's permissions decide which tools work. Each permission in the key screen has up to five levels: View, Create, Edit, Delete and Admin. Enable only what you need.

View is enough for tools that only read.
Add Create, Edit or Delete only for the changes you want the assistant to be able to make. Every change still needs your confirmation, but a key without the permission can't make it at all.
A missing permission only affects the tools in that area. The assistant reports a 401 for those tools and everything else keeps working.

If you want to work with	Enable these permissions
Anything (recommended for every key)	Subscription, Lookup, External Id
Products	Product, Product Variant, Product Category, Product Category Set, Product Inventory, Product Variant Inventory, Location, Product Kit, Product Option, Product Unit, Related Product
Alternate IDs	Alternate Id Type, Product Alternate Id, Product Variant Alternate Id
Customers	Customer, Customer Address, Customer Category, Customer Company, Company Relationship, Customer Company Relationship
Transactions	Transaction, Payment Method, Shipping Method, Transaction Tracking
Gift cards	Gift Card
Employees and timesheets	Employee, Employee Address, Timesheet, Timesheet Entry
Messages and images	Message, Image
Custom fields	Custom Field, plus the matching one for each type you use: Customer Custom Field, Product Custom Field, Transaction Custom Field, Gift Card Custom Field, Employee Custom Field, Message Custom Field
Mappings and translations	Mapping Collection, Mapping, Translation Collection, Translation, Export Mapping Collection, Export Mapping, Export Translation Collection, Export Translation
Errors and diagnosing failed syncs	Error, Integration Monitoring Error Logs, Integration Monitoring Activity Logs, Event, Event Rules
Resyncing records	Manual Sync, Show Unmatched, Debug Tracing
Webhooks	Webhook
Email templates	Email

NOTE: Subscription matters more than it looks. Without it, the assistant can't turn a connected system's name into its ID, so you will have to give it system IDs yourself.

Once you're connected (Step 5), ask the assistant to run check_my_permissions. It tests each area and tells you which ones your key can and can't use.

Step 3: Install Node.js (only if your app needs it)

Most apps connect to the iPaaS.com MCP server directly and don't need Node.js. The one exception in this article is the Claude Desktop configuration file method in Step 4, which uses a small bridge called mcp-remote that runs on Node.js (version 18 or later; the current LTS release is fine). If you connect any other way, skip this step. You never run Node yourself, because your app does.

Check whether you already have it

Open Terminal (macOS) or PowerShell (Windows) and run these two commands:

node -v
npx -v

Each should print a version number. If you see "command not found" or "is not recognized", install Node.js using one of the options below.

Install on a Mac

Installer: download the LTS installer from nodejs.org, open it and accept the defaults.
Homebrew: if you already use Homebrew, run:

brew install node

Install on Windows

Installer: download the LTS installer from nodejs.org, run it and accept the defaults.
winget: in PowerShell, run:

winget install OpenJS.NodeJS.LTS

Microsoft's guide: for a version manager setup, follow Set up Node.js on native Windows.

After you install

Close and reopen your terminal, then run node -v and npx -v again to confirm. Then quit your app completely and reopen it, because an app that was already running won't see the new installation. If your computer is managed and you can't install software, ask your IT team.

Step 4: Connect your assistant

Every app connects to the same server with the same credentials. Only the place you enter them differs:

Server URL: https://mcp.ipaas.com/mcp
Header name: X-Ipaas-Api-Key
Header value: the API key you created in Step 1

Pick your app from this table, then follow its section below.

App	How you connect	Needs Node.js?
Claude custom connector (Claude, Claude Desktop, Cowork)	Settings screen, Request headers	No
Claude Desktop configuration file	Edit `claude_desktop_config.json` using `mcp-remote`	Yes
Claude Code	One `claude mcp add` command	No
Cursor	Edit `mcp.json`	No
VS Code with GitHub Copilot	Edit `.vscode/mcp.json`	No
Gemini CLI	One `gemini mcp add` command, or edit `settings.json`	No
ChatGPT	Not supported yet	Not applicable
Other apps	Remote server URL plus a custom header	Only if the app can't connect to remote servers directly

Claude custom connector (Request headers)

This is the simplest option for Claude, Claude Desktop and Cowork, and it needs no Node.js. Custom connectors are available on Free, Pro, Max, Team and Enterprise plans.

Open Customize > Connectors, click + Add, then choose Add custom connector. On Team and Enterprise plans, an organization owner first adds the connector under Organization settings > Connectors, and each member then connects it from Customize > Connectors.
Enter a name such as iPaaS.com and the server URL https://mcp.ipaas.com/mcp.
For authentication, choose the Request headers (fixed credentials) option instead of OAuth.
Add a header named X-Ipaas-Api-Key and paste your API key as its value. Enter the key only, with no extra words in front of it.
Save the connector, then enable it for your conversation.

Claude Desktop configuration file (uses mcp-remote)

Use this method only if you prefer a configuration file. It is the only method in this article that needs Node.js, so complete Step 3 first. In Claude Desktop, open Settings > Developer and click Edit Config to open the file, or find it here:

App	File
Claude Desktop on macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop on Windows	`%APPDATA%\Claude\claude_desktop_config.json`

Add the following, replacing paste-your-api-key-here with your key (from Step 1). If the file already has an "mcpServers" section, add the "ipaas" block inside it instead of pasting a second copy.

{
  "mcpServers": {
    "ipaas": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.ipaas.com/mcp",
        "--header", "X-Ipaas-Api-Key:${IPAAS_API_KEY}"
      ],
      "env": {
        "IPAAS_API_KEY": "paste-your-api-key-here"
      }
    }
  }
}

Two details that cause most failed first attempts:

Leave no space after the colon in X-Ipaas-Api-Key:${IPAAS_API_KEY}. A space garbles the header, and the failure looks like a bad key.
Keep the key in the env section, not directly in args. That keeps it out of process listings.

Then quit the app completely and reopen it. On macOS, press Cmd-Q. Closing the window isn't enough, because new tools are only picked up when the app starts.

Claude Code

Claude Code connects to the server directly, so it doesn't need Node.js or mcp-remote. In your terminal, run this command, replacing YOUR_API_KEY with your key:

claude mcp add --transport http ipaas https://mcp.ipaas.com/mcp --header "X-Ipaas-Api-Key: YOUR_API_KEY"

By default the server is saved for you in the current project only. Add --scope user to make it available in all your projects.
If you would rather edit a file, add this to .mcp.json in your project folder. The ${IPAAS_API_KEY} value is read from an environment variable, so the key itself stays out of a file you might share:

{
  "mcpServers": {
    "ipaas": {
      "type": "http",
      "url": "https://mcp.ipaas.com/mcp",
      "headers": {
        "X-Ipaas-Api-Key": "${IPAAS_API_KEY}"
      }
    }
  }
}

Start a new Claude Code session, and run claude mcp list or type /mcp to confirm that ipaas is connected.

Cursor

Cursor connects directly and doesn't need Node.js. Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (this project only):

{
  "mcpServers": {
    "ipaas": {
      "url": "https://mcp.ipaas.com/mcp",
      "headers": {
        "X-Ipaas-Api-Key": "${env:IPAAS_API_KEY}"
      }
    }
  }
}

${env:IPAAS_API_KEY} reads the key from an environment variable that must be set before you start Cursor. If you paste the key into the file instead, don't commit that file to source control. Restart Cursor after saving.

VS Code with GitHub Copilot

VS Code connects directly and doesn't need Node.js. Create .vscode/mcp.json in your project, or open your user-level file by running MCP: Open User Configuration from the Command Palette. Note that VS Code uses "servers" at the top, not "mcpServers". The inputs section makes VS Code ask for the key once and store it, so it never appears in the file:

{
  "servers": {
    "ipaas": {
      "type": "http",
      "url": "https://mcp.ipaas.com/mcp",
      "headers": {
        "X-Ipaas-Api-Key": "${input:ipaas-api-key}"
      }
    }
  },
  "inputs": [
    {
      "type": "promptString",
      "id": "ipaas-api-key",
      "description": "iPaaS.com API key",
      "password": true
    }
  ]
}

Start the server from the Start link that appears above it in the file (or run MCP: List Servers), paste your key when prompted, then use the tools from Copilot Chat in Agent mode.

Gemini CLI

Gemini CLI connects directly and doesn't need Node.js to talk to the server. Run this command, replacing YOUR_API_KEY with your key:

gemini mcp add --transport http --header "X-Ipaas-Api-Key: YOUR_API_KEY" ipaas https://mcp.ipaas.com/mcp

Or add the server to ~/.gemini/settings.json yourself. For a streamable HTTP server, Gemini CLI uses httpUrl, not url:

{
  "mcpServers": {
    "ipaas": {
      "httpUrl": "https://mcp.ipaas.com/mcp",
      "headers": {
        "X-Ipaas-Api-Key": "YOUR_API_KEY"
      }
    }
  }
}

Start a new Gemini CLI session and type /mcp to confirm that ipaas is connected.

ChatGPT (not supported yet)

ChatGPT can't connect to the iPaaS.com MCP server at this time. ChatGPT custom connectors expect OAuth sign-in (or no authentication), and they don't let you add a custom header such as X-Ipaas-Api-Key. The iPaaS.com MCP server authenticates with an API key, so there is no way to complete the connection. We'll update this article if that changes. Don't paste your API key into a ChatGPT conversation as a workaround.

Other apps

Any app that can connect to a remote MCP server and send a custom request header will work. Look for the app's setting for adding a remote or HTTP MCP server, then enter the same three values: the URL https://mcp.ipaas.com/mcp, the header name X-Ipaas-Api-Key, and your API key as the value. If an app only supports locally run servers, use the mcp-remote configuration from the Claude Desktop section above. That route needs Node.js (Step 3). Wherever you use it, keep no space after the colon in the header.

When in doubt, ask your agent to read this page and provide you instrctions for how to connect.

Step 5: Check that it works

Ask your assistant:

"Which iPaaS.com company am I connected to?" It should run get_active_tenant and name your company and its connected systems.
"Check my permissions." It should run check_my_permissions and list the areas your key can and can't use.

If both answer, you're ready to go. The Overview article has ideas for what to ask first, and Choosing Your Tools explains how to narrow the tool set once you know what you're working on.

If something doesn't work

No iPaaS.com tools appear. Fully quit and reopen the app (or start a new session in a command-line tool). If you edited a configuration file, check it for a missing comma or brace, because many apps ignore the whole file without telling you. Paste it into a JSON checker. Also confirm you used the right top-level name: "servers" for VS Code, "mcpServers" for the others. In Claude Code, run claude mcp list to see whether the server is registered.
Every call returns 401. The key is wrong, has expired, or is a sign-in token rather than an API key. Check its expiration in User/Role Management > API Keys, or ask the assistant to run get_active_tenant, which reports the kind of credential it holds. Also check that the header name is exactly X-Ipaas-Api-Key and the value is only the key.
Only some tools return 401. The key lacks a permission for that area. Run check_my_permissions to see which one. Because keys can't be edited, create a new key with the right permissions and update your connection.
"command not found: npx" or "'npx' is not recognized". This only affects the Claude Desktop configuration file method, which needs Node.js. Node.js is missing, or was installed after the app started. Follow Step 3, close and reopen your terminal, run node -v and npx -v to confirm, then fully restart the app. If you don't want to install Node.js, use the Claude custom connector method instead.
The key looks right but the connection fails (mcp-remote). Check for a space after the colon in X-Ipaas-Api-Key:${IPAAS_API_KEY}. A space garbles the header, and the failure looks like a bad key.
The Claude custom connector won't connect. Confirm you chose Request headers rather than OAuth, and that the header name and value are entered exactly as shown in Step 4. On Team and Enterprise plans, ask an organization owner whether the connector has been added for your organization.
You can't add the server in ChatGPT. ChatGPT isn't supported yet. See the ChatGPT section in Step 4.
The assistant says a record doesn't exist and you know it does. Check which company you're in. The key decides that, and it's easy to hold a key for a different company than you expect.

Anything else: mcp@ipaas.com.

iPaaS.com MCP: Getting Started