> ## Documentation Index
> Fetch the complete documentation index at: https://docs.itoflow.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP troubleshooting

> Fix connection, sign-in, missing-tool, plugin, research and file problems.

Find the step that failed:

```text theme={null}
Plugin installed → Signed in → Tools loaded → Request returned a result
```

## Connection and sign-in

| Problem | What to do |
| - | - |
| The server URL doesn't connect | Use `https://mcp.itoflow.ai/mcp` with Streamable HTTP and OAuth. Check that your client supports remote servers and that your workspace allows plugins or custom MCP servers. |
| Sign-in didn't finish or has expired | Authenticate again from the client's MCP settings: `/mcp` in Claude Code, or `codex mcp login itoflow` in Codex. Restarting the client doesn't finish a sign-in. |
| Codex keeps asking you to sign in | You may have more than one Codex installed. Sign in with the CLI that belongs to the Codex app running your task. |
| Tools don't appear | Start a new task or restart the client. If you use the plugin, check that it finished installing. |
| Permission denied | Check which Itoflow account you signed in with and whether it can use that resource. Reinstalling doesn't change access. |

After you reconnect, repeat the [first request](https://docs.itoflow.ai/mcp/install.md#make-your-first-request). Never paste tokens or browser cookies into the conversation.

## Plugin

| Problem | What to do |
| - | - |
| No worker skill | Install the [plugin](https://docs.itoflow.ai/mcp/install.md#install-the-plugin), or add the skills as the guide describes for your client. |
| Marketplace not found | Add `itoflow/skills`, or for an archive, the extracted `itoflow` folder. Keep that folder in place. |
| Marketplace name already in use | You already added the `itoflow` marketplace, for example from an archive. Remove it, then add `itoflow/skills`. |
| Plugin not found | Check that the marketplace step succeeded, then install `itoflow@itoflow` again. |
| You don't get the latest skills | Update the marketplace and plugin from your client, for example `claude plugin update itoflow@itoflow`, then start a new task. Check the version against the [latest release](https://github.com/itoflow/skills/releases). |

## Research and account tasks

| Problem | What to do |
| - | - |
| `search` finds nothing | Try a short phrase such as `list portfolios`. No match doesn't mean you lack access. |
| Claude Code blocks a call as "Data Exfiltration" | Auto mode doesn't know you send portfolio data to Itoflow. [Tell it](https://docs.itoflow.ai/mcp/install.md#use-itoflow-in-claude-codes-auto-mode). Approving the call in chat or retrying it under `/permissions` → **Recently denied** doesn't clear this check. |
| Research stays pending or running | Ask your assistant to check the same run again later. Don't send the question again; that starts a second run. |
| Research stopped with an error | Ask your assistant for any partial results first, then decide whether to run it again. |
| The result has no text | Ask your assistant to read the returned dashboard and its sources. The answer is often there. |
| Itoflow asks a question your client can't show | Use a client that can display forms, or answer in the Itoflow chat. Replying in a new message doesn't answer the question. |
| A change is rejected because of a version conflict | Ask your assistant to reload the current state and try the change again. |
| A direct API call returns `ok: false` | Read `status` and `body`. All 4xx responses and any 5xx status listed for that operation in its published OpenAPI document return `{ ok: false, status, body }`. If `Retry-After` is a whole number of seconds, the result also gives `retry_after_seconds`; wait that long before retrying. Other header forms are omitted. Redirects and undocumented server failures return a generic error. |
| An operation you expect is missing | Not every Itoflow feature is available through MCP. Use the [HTTP API](https://docs.itoflow.ai/api-reference/overview.md) or the app. |

## Local worker and files

| Problem | What to do |
| - | - |
| The worker can't read a file or database | Check that your local session can reach it. The plugin doesn't add access or credentials. |
| Itoflow asks about a local file | Let your local agent read and analyze it, then report back. Itoflow can't open paths on your machine. |
| Itoflow hands the whole task to the worker | Ask Itoflow to plan the research and give the worker one specific step at a time. |
| A chat file is too large | MCP reads files up to 32 MiB. Use the [download endpoint](https://docs.itoflow.ai/features/chat.md#download-files-from-a-chat) for larger files. |
| A file read says the workspace is busy | Two other downloads or reads from that chat's workspace are in progress. Try again when one finishes. Running research doesn't block reads. |
| You want to upload a file | MCP can't upload files. Use the Itoflow app, or let the worker analyze the file locally. |

## Ask for help

Email [support@itoflow.ai](mailto:support@itoflow.ai) with your client and its version, how you connected (URL or plugin, and the plugin version), which step failed, and the error text. Leave out tokens, account details and private file contents.

For HTTP API errors, see [Troubleshooting](https://docs.itoflow.ai/troubleshooting.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.