> ## Documentation Index > Fetch the complete documentation index at: https://www.integrate.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # ETL: MCP Troubleshooting > Common Integrate.io ETL MCP connection errors and fixes, plus known limitations of the MCP server. If a client won't connect or a tool call fails, find the symptom below. For how tokens and OAuth work, see [Authentication](https://www.integrate.io/docs/etl/mcp-authentication.md). For client-specific setup, start at the [connect hub](https://www.integrate.io/docs/etl/mcp-connect.md). ## Common errors | Symptom | Cause | Fix | | - | - | - | | `401 Unauthorized` | Missing or expired token | Mint a new token (see [Authentication](https://www.integrate.io/docs/etl/mcp-authentication.md)). 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](https://www.integrate.io/docs/etl/integrateio-mcp-server.md#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)](https://www.integrate.io/docs/etl/mcp-connect-claude.md#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](https://www.integrate.io/docs/etl/integrateio-mcp-server.md#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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.