ETL: MCP Troubleshooting

If a client won’t connect or a tool call fails, find the symptom below. For how tokens and OAuth work, see Authentication. For client-specific setup, start at the connect hub.

Common errors

Symptom	Cause	Fix
`401 Unauthorized`	Missing or expired token	Mint a new token (see Authentication). 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.
A static token is rejected and the client reports a failed connection instead of falling back to OAuth	Some clients do not fall back to browser sign-in when a static credential is present but invalid	Verify the token in Connected Applications. To use OAuth instead, remove the static credential from the client config so it runs browser sign-in.
`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.
Tool call returns `isError: true` with `"reason":"mcp_write_disabled"`	The account has read access only, and the client called a mutating tool (`create_package`, `update_package_components`, `run_package`, `retry_job`, `cancel_job`, schedule writes, etc.)	If write access is expected, contact Integrate.io support to enable it. Otherwise, restrict prompts to the read tools listed in Safety, audit, and read-only mode. If your client cached an older tool list, ask it to re-list tools.
`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. Batch requests are not supported.
`{"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.

Claude Desktop extension issues

If you install the Integrate.io Claude Desktop extension (.mcpb) from the Connected Applications page (see Claude Desktop (one-click extension)):

Symptom	Cause	Fix
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`, 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.

Known limitations

No batch requests. The endpoint accepts a single JSON-RPC 2.0 message per request.
No sandbox for mutating tools. Writes take effect immediately against your live account, including production pipelines. See Safety, audit, and read-only mode.
Read or write access is set per account, not per token. A token or OAuth grant is account-wide with the signed-in user’s permissions. Accounts start with read access only; write access is opt-in. There are no per-token tool scopes. Contact Integrate.io support if you need finer-grained scoping.

Get started

Connect a client

Authentication

Tool reference

Troubleshooting

ETL: MCP Troubleshooting

Common errors

Claude Desktop extension issues

Known limitations

​Common errors

​Claude Desktop extension issues

​Known limitations

Common errors

Claude Desktop extension issues

Known limitations