ETL: MCP Server Overview & Connect

The Integrate.io MCP server exposes a Model Context Protocol (MCP) endpoint that AI agents such as Claude, ChatGPT, and OpenAI Codex (or debugging tools like the MCP Inspector) can call to inspect and act on your account. Clients connect over JSON-RPC 2.0 and use a curated set of tools to list workspaces, list packages, inspect runs, search resources, validate pipelines, preview database data, and (with explicit mutating tools) clone packages, edit components, manage schedules, and run jobs. Credentials, TLS certificates, and SSL keys are never returned.

Verified clients

These are the clients we have set up and verified, with step-by-step instructions below. They are not the only ones that work: any MCP-capable client can connect (see Any other MCP client).

Client	Transport	Auth method	Bridge required?
Claude Desktop	stdio (via `mcp-remote`)	Bearer token	Yes - `mcp-remote`
Claude Code	Streamable HTTP (native)	OAuth (browser sign-in) or Bearer token	No
Claude.ai web	Streamable HTTP (native)	OAuth (browser sign-in)	No
ChatGPT (custom connector)	Streamable HTTP (native)	OAuth (browser sign-in)	No
OpenAI Codex	stdio (via `mcp-remote`)	Bearer token	Yes - `mcp-remote`
Cursor	stdio (via `mcp-remote`)	Bearer token	Yes - `mcp-remote`
MCP Inspector (debugging tool)	Streamable HTTP (native)	Bearer token	No

MCP Inspector is not an AI agent. It is a debugging tool from the MCP project team (npx @modelcontextprotocol/inspector) that opens a local UI for listing and calling tools directly. Use it to confirm the endpoint works before wiring up a real agent.

Claude.ai web supports custom connectors: go to Settings → Connectors, click Add custom connector, enter the endpoint URL, and authorize with OAuth. It is available on the free, Pro, Max, Team, and Enterprise plans (free accounts are limited to one custom connector). Like every Claude client, claude.ai connects from Anthropic’s cloud rather than from your device, so the endpoint must be reachable over the public internet (the production URL is).

Two ways to authenticate. Clients that support OAuth (such as Claude Code, claude.ai web, or a ChatGPT custom connector) can connect with browser sign-in - no token to copy or paste. See Connecting with OAuth. For clients that need a static bearer token (Claude Desktop’s manual config, OpenAI Codex, the MCP Inspector, curl), create a Personal Access Token instead - see Step 1.

Endpoint

All you need to connect a client is the full URL, with your account id filled in: https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp

You don’t have to assemble this URL by hand. Open Settings → Developer Settings → Connected Applications in your dashboard and copy the MCP server URL shown at the top of the page, your account id is already filled in.

Why api.xplenty.com instead of integrate.io? The Integrate.io API still runs at api.xplenty.com - this is expected and normal. The domain predates the Integrate.io rebrand. Your dashboard URL (dashboard.xplenty.com) and the API URL both work correctly.

The endpoint accepts a single JSON-RPC 2.0 message per request. Batch requests are not supported. Authentication uses a bearer token in the Authorization header. The token must belong to a user with access to the account named in the URL. Cross-account requests return 403 Forbidden.

Prerequisites

Reach out to the Integrate.io team to enable this for your account.
A way to authenticate. You have two options:
- OAuth browser sign-in (easiest) - supported clients like Claude Code authenticate interactively, no token to manage. See Connecting with OAuth.
- A Personal Access Token (PAT) - a long-lived bearer token for clients that need a static credential (Claude Desktop manual config, MCP Inspector, curl). The recommended way to mint one is Connected Applications in the dashboard (see Step 1).
An MCP-capable client. The setup below covers Claude Desktop 0.7.0 or later (0.10 or later for the one-click extension), Claude Code, and the MCP Inspector.

The easiest way to connect a client that supports OAuth (such as Claude Code or a ChatGPT custom connector) is to skip the token entirely and authenticate in your browser. The client registers itself, sends you to a consent screen, and stores the resulting credentials for you. There is nothing to copy or paste. The steps below show Claude Code. For ChatGPT, the same browser sign-in happens inside ChatGPT’s connector setup, see ChatGPT (custom connector) under Step 2.

Add the MCP server without a token

Point your client at the endpoint with no Authorization header. For Claude Code:

claude mcp add --transport http integrateio \
  https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp

Replace YOUR_ACCOUNT_ID with your account subdomain or numeric id (the value in your dashboard URL).

Start authentication

Run /mcp in Claude Code and choose Authenticate for the integrateio server. Claude Code opens your browser to the Integrate.io consent screen. Sign in if you aren’t already.

Authorize access

You’ll see an Authorize access screen naming the client and the account it’s connecting to:

Claude Code is requesting access to your Integrate.io account your-account via the MCP server. This will let it read and manage your pipelines, connections, and jobs in this account.

Click Authorize. The browser hands the client back its credentials and you can close the tab. Skip ahead to Step 3: Verify the connection.

The consent screen is locked to the account subdomain the client connected to, so a client can only ever be granted access to that one account.

What OAuth grants

Access is account-wide with the same permissions as the signed-in user - identical in scope to a Personal Access Token.
Tokens are short-lived and refreshed automatically by the client, so you won’t be prompted again every couple of hours during normal use.
The connection appears in Settings → Developer Settings → Connected Applications under the client’s name (e.g. “Claude Code”), alongside any Personal Access Tokens, so you can audit and revoke it in one place.

Revoking and re-authenticating

Revoke: open Connected Applications, find the client, and click Revoke. Access stops immediately and the client must authorize again to reconnect.
Re-authenticate: if you authorize the same client again, the new session replaces the previous one for that client name, so you won’t accumulate duplicate entries in Connected Applications. The consent screen still appears each time; that approval is the security checkpoint and is expected on every authorization.

Integrate.io uses the OAuth 2.1 Authorization Code flow with PKCE (S256), the same standard used by major SaaS MCP connectors. After you click Authorize, your browser returns to the client’s local callback (e.g. http://localhost:…/callback) and shows a brief “Authentication Successful” page rendered by the client; that page comes from the MCP client, not from Integrate.io.

Step 1: Get a Personal Access Token

If your client supports OAuth (e.g. Claude Code), you don’t need a token at all - use Connecting with OAuth instead. Personal Access Tokens are for clients that need a static bearer credential: Claude Desktop’s manual config, the MCP Inspector, curl, and scripts.

The simplest way to get a token is from the Connected Applications page in your Integrate.io dashboard - no curl, no password grant, no token expiry to manage.

Sign in to your dashboard and navigate to Settings → Developer Settings → Connected Applications. (Direct URL: https://dashboard.xplenty.com/<your-account>/settings/developer/connected_applications) If you don’t see the Connected Applications link in the sidebar, contact Integrate.io support to request access.
Click + Create new connection.
Give it a recognizable name (e.g. “Claude Desktop on Macbook”) and click Create token.
The token is displayed once in a reveal modal. Click Copy before closing the modal. Integrate.io does not store the plaintext token and cannot show it again. If you lose it, revoke the connection and create a new one.

The reveal modal also includes ready-to-paste configuration snippets for Claude Desktop, Claude Code, the MCP Inspector, and curl. You can skip ahead to Step 3 and paste the Claude Desktop snippet directly into your config file.

The Connected Applications page also has a Quick install for Claude Desktop card with a one-click .mcpb extension download. If Claude Desktop is your client, use that path - see Step 2: Claude Desktop (one-click extension) below.

Why Connected Applications instead of an OAuth grant request?Connected Applications mint long-lived Personal Access Tokens (PATs) tied to a specific named integration. You don’t need to keep re-running an OAuth password-grant call every two hours, and you can revoke a token from the same page without affecting your dashboard session. Each connection appears in the list with its name, scope, and creation date, making it easy to audit which agent is connected to your account.A connection can be revoked at any time from the same page. The bearer token stops working immediately everywhere it’s pasted.

PAT scope and security notes:

PATs are account-wide and carry the same permissions as the user who created them.
There is currently no option to create a read-only PAT or restrict a PAT to a subset of MCP tools. Contact Integrate.io support if you need scoped access.
PATs have a 10-year lifetime by default. Treat them like passwords: store in a secrets manager, not in plain text.
Token rotation: revoke the existing connection in Connected Applications and create a new one. Update your MCP client config with the new token.

Alternative: OAuth password grant (legacy)

If you can’t use Connected Applications (e.g., automation that must mint tokens programmatically without a logged-in user), you can still use the OAuth Resource Owner Password Credentials grant. These tokens expire after two hours, so you’ll need to refresh them regularly.

curl -X POST 'https://api.xplenty.com/oauth/token' \
  -H 'Content-Type: application/json' \
  -d '{
    "grant_type": "password",
    "email": "you@your-org.com",
    "password": "your-password"
  }'

The response includes the access_token:

{
  "access_token": "ABC123...",
  "token_type": "Bearer",
  "expires_in": 7200,
  "created_at": 1234567890
}

For interactive use with Claude Desktop or MCP Inspector, prefer Connected Applications. The 10-year PAT lifetime means you set it up once and forget it.

Step 2: Configure your MCP client

Claude Desktop (one-click extension)

The fastest way to connect Claude Desktop is to install the Integrate.io extension (.mcpb). The extension prompts you for your account subdomain and Personal Access Token at install time, so you never touch claude_desktop_config.json by hand. Requires Claude Desktop 0.10 or later on macOS or Windows.

In the Integrate.io dashboard, go to Settings → Developer Settings → Connected Applications.
In the Quick install for Claude Desktop card, click Download Claude Desktop extension. The browser downloads integrate-io-mcp.mcpb.
Open Claude Desktop and go to Settings → Extensions. Drag the downloaded .mcpb file onto that page. Claude Desktop opens the extension install dialog.
When prompted:
- Account Subdomain - your Integrate.io account subdomain or numeric id (the value in your dashboard URL).
- Personal Access Token - a PAT from Step 1. If you haven’t minted one yet, click + Create new connection on the Connected Applications page first.
Click Install, then restart Claude Desktop (fully quit and reopen).

In Claude Desktop’s MCP picker you should now see integrateio with the full tool list. Skip to Step 3 to verify.

On a staging Integrate.io account the same card serves integrate-io-mcp.staging.mcpb and displays a Staging build badge. The staging extension only talks to api-staging.xplenty.com - it won’t work with a production PAT. Both extensions can be installed side by side - Claude Desktop treats them as separate integrations (integrate-io-mcp and integrate-io-mcp-staging).

Migrating from the manual claude_desktop_config.json entry? Remove the old xplenty (or whatever you named it) entry from mcpServers in your config file before installing the extension. If both an extension and a manual entry point at the same backend, the install dialog may silently no-op because Claude Desktop sees the integration as already configured. Restart Claude Desktop after removing the stale entry, then drag the .mcpb in.

Updating or removing the extension

Update: download the latest .mcpb from the Connected Applications page and drag it onto Settings → Extensions again. The version field in the bundle increments on each release, so Claude Desktop treats it as an update rather than a duplicate. Your subdomain + token entered at first install are preserved.
Remove: go to Settings → Extensions in Claude Desktop, find Integrate.io in the list, and click the remove/uninstall control. Optionally revoke the underlying Personal Access Token from Connected Applications in the Integrate.io dashboard.

Claude Desktop (manual config)

If you can’t install the extension - corporate policy, an older Claude Desktop, or you’d rather hand-edit the config - edit your Claude Desktop configuration file directly:

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

Add an entry under mcpServers. Claude Desktop speaks MCP over stdio only, so the snippet uses mcp-remote as a thin bridge to the remote HTTP endpoint:

{
  "mcpServers": {
    "integrateio": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp",
        "--header",
        "Authorization: Bearer YOUR_ACCESS_TOKEN"
      ]
    }
  }
}

Replace YOUR_ACCOUNT_ID with your account subdomain or numeric id and YOUR_ACCESS_TOKEN with the value from Step 1, then restart Claude Desktop (Cmd+Q on macOS - fully quit and reopen; reloading the window isn’t enough).

The Connected Applications reveal modal generates this snippet for you with the URL and token already filled in. Click Copy under the Claude Desktop tab, paste into your config, restart Claude.

Claude Code

Claude Code has native HTTP MCP support, so no bridge is needed. Run:

claude mcp add --transport http integrateio \
  https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN"

MCP Inspector

The MCP Inspector has a native UI for ad-hoc debugging. Launch it:

npx @modelcontextprotocol/inspector

Then in the UI:

Transport: Streamable HTTP
URL: https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp
Headers: Authorization: Bearer YOUR_ACCESS_TOKEN

The Inspector lets you call tools/list and tools/call directly and view the JSON-RPC response.

Cursor

Cursor uses the same stdio-only MCP transport as Claude Desktop. Use the same mcp-remote bridge - edit ~/.cursor/mcp.json (or per-workspace .cursor/mcp.json) with the JSON snippet above.

ChatGPT (custom connector)

ChatGPT connects to the MCP server natively over OAuth, so there is no token to paste and no bridge to install. You add the endpoint as a custom connector and approve access in your browser.

Custom MCP connectors are available on ChatGPT plans that expose connectors / developer mode (for example Plus, Pro, Business, and Enterprise). If you don’t see the option to add a custom connector, your plan or workspace admin settings may not have it enabled yet.

Open the custom connector dialog

In ChatGPT, go to Settings → Connectors and choose to add a custom connector. On some plans this lives under Settings → Connectors → Advanced → Developer mode.

Enter the endpoint

Give the connector a recognizable name (e.g. “Integrate.io”) and set the MCP server URL to:

https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp

Replace YOUR_ACCOUNT_ID with your account subdomain or numeric id (the value in your dashboard URL).

Choose OAuth and authorize

For authentication, select OAuth. ChatGPT registers itself and opens the Integrate.io consent screen. Sign in if you aren’t already, then click Authorize. ChatGPT stores the resulting credentials and refreshes them automatically.

Use the connector

Enable the connector in a chat and ask a read-only prompt to confirm it works, for example: “List the workspaces in my Integrate.io account.” See What you can do with it for more.

This uses the same OAuth 2.1 Authorization Code flow with PKCE described in Connecting with OAuth. The connection appears in Settings → Developer Settings → Connected Applications in your Integrate.io dashboard, where you can audit or revoke it.

OpenAI Codex

Codex speaks MCP over stdio, the same as Claude Desktop and Cursor, so it uses the mcp-remote bridge to reach the remote HTTP endpoint. Add the server to ~/.codex/config.toml:

[mcp_servers.integrateio]
command = "npx"
args = [
  "-y",
  "mcp-remote",
  "https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp",
  "--header",
  "Authorization: Bearer YOUR_ACCESS_TOKEN"
]

Replace YOUR_ACCOUNT_ID with your account subdomain or numeric id and YOUR_ACCESS_TOKEN with a Personal Access Token from Step 1, then restart Codex.

If you omit the --header line, mcp-remote falls back to OAuth browser sign-in instead of a static token, the same flow Claude Code uses. A Personal Access Token is the simpler choice for an always-on CLI because it does not expire after a couple of hours.

Any other MCP client

MCP is an open standard, so the sections above (Claude, ChatGPT, Codex, Cursor) are just specific cases of the same thing. Any MCP-compatible client or agent, on any LLM provider, connects to the same endpoint:

https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp

To connect a client not listed above, answer two questions about it: 1. Does it support remote MCP servers natively, or only local (stdio) ones?

Native remote (Streamable HTTP) support: point the client straight at the endpoint URL. No bridge needed.
Local / stdio only: run the mcp-remote bridge in front of the URL, exactly as the Claude Desktop, Cursor, and Codex examples above do. mcp-remote turns the remote HTTP endpoint into the local stdio server these clients expect.

2. How does it authenticate?

Supports OAuth: add the server with no credentials and let the client run browser sign-in. It self-registers and stores its own tokens, see Connecting with OAuth. This is the same flow Claude Code and ChatGPT use.
Needs a static credential: create a Personal Access Token (see Step 1) and send it as an Authorization: Bearer YOUR_ACCESS_TOKEN header. For stdio clients, pass it through mcp-remote with --header as shown in the Codex snippet.

Once connected, every client sees the identical set of tools and obeys the same per-account permissions, regardless of which client or model is calling. If your client supports the Streamable HTTP MCP transport but still won’t connect, the Troubleshooting table at the end of this page covers the common causes.

Step 3: Verify the connection

In Claude Desktop, type /mcp in the chat input. You should see integrateio listed with all 41 tools available. Try a prompt such as:

List the workspaces in my Integrate.io account.

Claude invokes tools/call with list_workspaces and returns the response payload.

What you can do with it

These are real prompts you can type into Claude (or any connected AI agent) once the MCP server is configured:

Natural-language prompt	Tools invoked
”My Salesforce sync just failed - what broke?”	`explain_job_failure`
”Show me all packages that haven’t run successfully this week”	`list_runs` with status filter
”Clone the Salesforce to Snowflake package into a new workspace for testing”	`clone_package`
”Which schedules are currently disabled?”	`list_schedules` with `enabled: false`
”Preview the first 20 rows of the `orders` table on our production DB connection”	`preview_data`
”Show me what the `clean_orders` Select transform outputs before I wire up the destination”	`preview_transformation`

Tool reference

The server registers 41 tools, grouped by what they do. Every tool is scoped to the authenticated account, obeys the signed-in user’s permissions, and never returns credentials, TLS certificates, or SSL keys. Read-only tools inspect account state; mutating tools create, modify, or run packages and jobs, and take effect immediately (there is no sandbox). Full parameter-level reference is split across three pages:

Reading & Inspecting

16 read-only tools: inventory (connections, packages, runs, clusters), schema discovery, data preview and profiling, expression and package validation, and documentation Q&A.

Building & Editing Packages

14 authoring tools: build a pipeline from intent, create or clone packages, add, edit, and remove components and edges, manage variables, and roll back versions.

Jobs & Schedules

11 tools: inspect and diagnose runs, create and manage schedules, and run, cancel, or retry jobs.

Tools that hit external services (validate_package, validate_expression, discover_schema, discover_file_schema, preview_data, preview_transformation, profile_data, test_connection, run_package, ask_docs) make real network calls to JMS, the expression evaluator, the schema-importer, the previewer, the docs assistant, or your upstream systems. Use them sparingly.

Safety, audit, and read-only mode

Mutating tools (build_pipeline, create_package, clone_package, update_package_components, update_package_edges, add_package_components, remove_package_components, rename_package, manage_package_variables, delete_package, revert_package, toggle_schedule, create_schedule, update_schedule, run_package, cancel_job, retry_job) modify your live account, including production pipelines. There is no sandbox mode. Changes take effect immediately.

Audit trail: All writes made through the MCP server are captured in your account’s audit history via PaperTrail. Changes made by update_package_components are versioned and reversible through the existing package version history UI. Running in read-only posture: If you want to connect an AI agent with no write access, limit your prompts to the read-only tools (list_*, get_*, search_all, explain_job_failure, validate_package, validate_expression, discover_schema, discover_file_schema, preview_data, preview_transformation, profile_data, test_connection, ask_docs). There is currently no server-side mechanism to restrict a token to read-only tools. This is a client-side discipline for now. Contact Integrate.io support if you need a scoped token. Procurement checklist:

All MCP-driven changes appear in the PaperTrail audit log.
Tokens can be revoked instantly from Settings → Developer Settings → Connected Applications.
No credentials, TLS certificates, or SSL keys are ever returned by any tool.

Inline secret redaction in get_package

get_package(include_full_graph: true) returns a package’s full data_flow_json so an agent can clone or modify a pipeline by example. If component properties contain user-typed secrets, for example a REST source URL with ?api_key=..., an Authorization: Bearer ... header, a basic-auth password, or credentials embedded in a bash component body, those values are masked before the response leaves the server. The redaction is applied to the full-graph payload only. The summary returned by a default get_package call (counts and component-type tally) contains no secret-bearing fields and is unaffected. What gets masked

Values under keys whose name matches a secret pattern (password, token, api_key, client_secret, authorization, and similar).
The value side of { name, value } header pairs when the name side names a credential header (Authorization, X-API-Key, apikey, and similar). Non-credential headers like Content-Type are preserved.
URL userinfo credentials (https://user:pass@host).
URL query-string secret parameters (?api_key=..., &token=..., and similar).
Bearer and Basic tokens of 8 or more characters found anywhere in a string value.

Each masked value is replaced with the literal string [REDACTED]. Structure is preserved: component types, names, ids, positions, schema fields, edges, and non-secret properties (such as username) come through unchanged, so the canvas still renders and the agent can still reason about pipeline shape. Example A REST source with an api_key in the URL and an Authorization header comes back like this:

{
  "url": "https://api.example.com/export?api_key=[REDACTED]",
  "username": "demo_user",
  "password": "[REDACTED]",
  "headers": [
    { "name": "Authorization", "value": "[REDACTED]" },
    { "name": "Content-Type", "value": "application/json" }
  ]
}

What this is and is not Redaction is a best-effort defense in depth for inline secrets that users sometimes paste directly into component properties. It is not a substitute for storing credentials in connections or in secret variables, which are encrypted at rest and never returned by any MCP tool. Use connections and secret variables for any real credential.

Recommended first prompts

Use these prompts to explore your account and test the integration. They use read-only tools only, so they are safe for production accounts.

Goal	Prompt to type
Orient yourself	”List the workspaces in my Integrate.io account and summarize the health of each one.”
Find recent failures	”Show me all jobs that failed in the last 24 hours and summarize the most common errors.”
Diagnose a specific failure	”Explain why run ID 123456 failed and suggest how to fix it.”
Audit active schedules	”List all enabled schedules and tell me which packages run most frequently.”
Explore a connection	”What tables are available on the `production-postgres` connection?”

list_workspaces is the best starting point for AI agents. It gives a snapshot of package counts and recent failure rates across all workspaces before diving into details.

Example: Calling a tool with curl

You can also call the endpoint directly. The body is a JSON-RPC 2.0 request.

curl -X POST 'https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_packages",
      "arguments": { "status": "active", "limit": 10 }
    }
  }'

To diagnose a failed run, call explain_job_failure with the run id:

curl -X POST 'https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "explain_job_failure",
      "arguments": { "run_id": 123456, "log_tail_lines": 100 }
    }
  }'

To preview source data before designing a transformation:

curl -X POST 'https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "preview_data",
      "arguments": {
        "connection_id": 42,
        "table": "orders",
        "row_count": 20,
        "where_clause": "amount > 1000"
      }
    }
  }'

To preview a single component’s output mid-build, before a destination is wired:

curl -X POST 'https://api.xplenty.com/YOUR_ACCOUNT_ID/api/mcp' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "preview_transformation",
      "arguments": {
        "package_id": 12345,
        "component_name": "clean_orders"
      }
    }
  }'

Troubleshooting

Symptom	Cause	Fix
`401 Unauthorized`	Missing or expired token	Mint a new token in Step 1. If you’re using an OAuth password-grant token, remember those expire after 2 hours. Switch to a Connected Application PAT for a long-lived token.
OAuth sign-in never opens a browser, or `SDK auth failed: HTTP 500 trying to load OAuth metadata`	The MCP feature isn’t enabled for your account, or the client cached a failed discovery attempt	Confirm the feature is enabled (contact Integrate.io support). Then remove and re-add the server (`claude mcp remove integrateio` then re-add), and run `/mcp` → Authenticate again.
After authorizing, the browser shows a `localhost` “Authentication Successful” page	Expected - that page is served by your MCP client’s local callback, not by Integrate.io	Nothing to fix. Close the tab and return to your client.
`401 Unauthorized` after revoking a Connected Application	The connection was deleted from Settings → Developer Settings → Connected Applications	Create a new connection from that page and update your client config. Revocation takes effect immediately.
`403 PTP MCP server is not enabled for this account`	Feature is off for your account	Contact Integrate.io support to enable the feature.
`403 Forbidden`	Token belongs to a user without access to the account in the URL	Use a token for a user who is a member of the target account.
`404 Not Found`	Wrong account id in URL	Use the account id or subdomain from your Integrate.io dashboard URL.
`{"error":{"code":-32600,...}}`	Malformed JSON-RPC body	Verify the request body matches the JSON-RPC 2.0 shape.
`{"error":"connection not found, or not a database connection"}`	Called `discover_schema` or `preview_data` against a cloud-storage or SaaS connection	These tools support database connections only. Use `get_connection` to confirm the type.
Dragging the `.mcpb` onto Claude Desktop does nothing - no install dialog appears	A previous manual`mcpServers` entry in `claude_desktop_config.json` targets the same backend, so Claude Desktop sees the integration as already configured and silently no-ops	Quit Claude Desktop, remove the old `mcpServers` entry from `claude_desktop_config.json` (location in the manual-config section above), reopen, then drag the `.mcpb` again.
Dragging the `.mcpb` opens the install dialog, but installation appears to do nothing	Older Claude Desktop versions (< 0.10) don’t render `.mcpb` install dialogs reliably	Update Claude Desktop to 0.10 or later (Settings → About → Check for Updates), then retry.
Extension installs but the `integrateio` integration isn’t visible in the MCP picker	Restart was skipped, or Claude Desktop is using a cached MCP picker state	Fully quit Claude Desktop (Cmd+Q on macOS, not just window-close), wait 3 seconds, reopen. The integration should now appear.
Extension installs but every tool call returns `401 Unauthorized`	Wrong Personal Access Token entered at install time, or the PAT was revoked since install	Open Settings → Extensions → Integrate.io in Claude Desktop and re-enter the token. If you don’t have one, mint a fresh PAT from Connected Applications in the dashboard first.
`Staging build` extension can’t reach the production account	The staging extension only talks to `api-staging.xplenty.com`	Install the production extension instead (downloaded from the production dashboard at `https://dashboard.xplenty.com/...`). The two extensions can coexist on the same machine.

​Verified clients

​Endpoint

​Prerequisites

​Connecting with OAuth (browser sign-in)

​What OAuth grants

​Revoking and re-authenticating

​Step 1: Get a Personal Access Token

​Alternative: OAuth password grant (legacy)

​Step 2: Configure your MCP client

​Claude Desktop (one-click extension)

​Updating or removing the extension

​Claude Desktop (manual config)

​Claude Code

​MCP Inspector

​Cursor

​ChatGPT (custom connector)

​OpenAI Codex

​Any other MCP client

​Step 3: Verify the connection

​What you can do with it

​Tool reference

Reading & Inspecting

Building & Editing Packages

Jobs & Schedules

​Safety, audit, and read-only mode

​Inline secret redaction in get_package

​Recommended first prompts

​Example: Calling a tool with curl

​Troubleshooting

Verified clients

Endpoint

Prerequisites

Connecting with OAuth (browser sign-in)

What OAuth grants

Revoking and re-authenticating

Step 1: Get a Personal Access Token

Alternative: OAuth password grant (legacy)

Step 2: Configure your MCP client

Claude Desktop (one-click extension)

Updating or removing the extension

Claude Desktop (manual config)

Claude Code

MCP Inspector

Cursor

ChatGPT (custom connector)

OpenAI Codex

Any other MCP client

Step 3: Verify the connection

What you can do with it

Tool reference

Safety, audit, and read-only mode

Inline secret redaction in get_package

Recommended first prompts

Example: Calling a tool with curl

Troubleshooting