MCP troubleshooting - Itoflow developer docs

Find the step that failed:

Plugin installed → Signed in → Tools loaded → Request returned a result

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. Never paste tokens or browser cookies into the conversation.

Plugin

Problem	What to do
No worker skill	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.

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. 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 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 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 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.