Troubleshooting

When the remote server says no, it says why, in a structured answer with a code and a message. The agent reads it back to you. Find the code below.

Refusal codes

Codes starting MCP_ come from the remote server. The rest come from the FlyDocs relay, which makes the lifecycle decisions for the CLI and the remote server alike.

Choosing an organization and workspace

Code	Meaning	What to do
MCP_ORG_REQUIRED	You belong to several organizations, have no primary one, and named none.	Pass organization, picking from the list in the answer. Setting a Default Organization in account Preferences avoids the prompt.
MCP_ORG_NOT_FOUND	The organization you named is not one your account belongs to.	Use a name from the list.
MCP_WORKSPACE_REQUIRED	The organization has several workspaces you can reach, and none was named.	Pass workspace with a slug from the list.
MCP_WORKSPACE_NOT_FOUND	The workspace you named is not one you can reach.	Use a slug from the list.
MCP_WORKSPACE_NONE	You are in the organization but in none of its workspaces.	Ask an admin to add you to one.
MCP_NO_ORGANIZATIONS	The account belongs to no FlyDocs organization.	Get invited to one.
MCP_IDENTITY_UNKNOWN	The account has no FlyDocs profile yet.	Sign in to the FlyDocs portal once, then reconnect.
MCP_ORG_DISABLED	An admin turned Remote MCP off for this organization.	See the org switch.

Arguments the tool could not use

Code	Meaning	What to do
MCP_NAME_NOT_FOUND	A milestone, project or sprint name matched nothing.	The answer lists what exists. Pick one, or create it.
MCP_NAME_AMBIGUOUS	The name matched more than one.	Say which you meant, by exact name or id.
MCP_NO_ACTIVE_SPRINT	A sprint of active was asked for and none is running, or the board has no sprints.	Name a sprint from flydocs_sprint_list, or leave the sprint out.
MCP_ASSIGNEE_NOT_MEMBER	The person is not on the workspace roster.	Pick someone from the roster in the answer.
MCP_ASSIGNEE_AMBIGUOUS	A name matches more than one member.	Use their email.
MCP_UPDATE_EMPTY	An update named no field to change.	Name at least one.
MCP_CRITERION_UNKNOWN	The criterion id is not on that issue, or appears twice in one batch.	The answer prints the criteria as they read now. Run it again against those ids.
MCP_ACCEPTANCE_UNAVAILABLE	The issue has no acceptance criteria this tool can address, or the tracker supplied no revision to guard the write.	Read the issue, and edit its description instead.
MCP_SCOPE_REQUIRED	A release digest got no scope or more than one. A plan estimate got neither or both of children and ref.	Give exactly one.
MCP_RANGE_INVALID	An analytics window is inverted, too wide, or mixes days with start and end.	Ask again with one spelling and a window inside the retention limit.
MCP_NOT_AVAILABLE	The request asked for something the tool does not do yet, such as an impact view of an issue or a spend dimension that is not rolled up.	Use what the answer offers.
MCP_TEAM_TIER_REQUIRED	The delivery analytics need the Team plan.	An org admin can change the plan in the portal.

Partial results

Code	Meaning	What to do
MCP_ACTIVATE_PARTIAL	flydocs_issue_activate assigned the issue, and the status move was then refused.	The assignment stands. Clear what the nested refusal names, then run the same call again.
MCP_CREATE_SPRINT_PARTIAL	flydocs_issue_create created the issue, and putting it in the sprint then failed.	The issue exists and the answer names it. Set its sprint with flydocs_issue_update. Do not create it again.

Reaching the tracker

Code	Meaning	What to do
MCP_RELAY_UNCONFIGURED, MCP_RELAY_UNREACHABLE, MCP_RELAY_TIMEOUT	The relay that talks to your tracker is not reachable right now.	Wait and try again. Do not retry in a loop.
MCP_RELAY_KEY_REVOKED	Remote access for this account was revoked.	Ask an org admin to restore it.
PROVIDER_NOT_CONNECTED, TEAM_NOT_SET	The workspace has no tracker connection or no team.	An admin connects the provider in the portal.
UNMAPPED_CURRENT_STATE, CURRENT_STATE_UNREADABLE	The issue's status in the tracker does not map to a FlyDocs status.	An admin fixes the status mapping for the workspace.

Lifecycle refusals from the relay

Code	Meaning	What to do
TRANSITION_ILLEGAL	The target status cannot be reached from the current one.	Use a target the answer lists. See the lifecycle rules.
ASSIGNMENT_REQUIRED	The issue has no assignee, and moving it to In Progress needs one.	Use flydocs_issue_activate, which assigns and moves in one call, or assign first.
ACCEPTANCE_INCOMPLETE	Acceptance criteria are neither met nor deferred, and the move needs them to be.	Tick or defer the ones that are done with flydocs_issue_acceptance_update, then retry.
REVISION_MISMATCH, CRITERION_MISMATCH	The description changed between the read and the write, so nothing was written.	Run it again against the criteria in the answer.
POLICY_OVERRIDE_DENIED	The workspace does not allow overrides from this surface.	Stop. Ask a workspace admin if the rule should change.
BATCH_NON_CONFORMANT	A breakdown had children that do not match the workspace template. Nothing was created.	Fix the children the findings name and send the whole set again.
BATCH_FAILED	The tracker failed part way through a breakdown. The children already created were canceled.	The answer lists what was created and rolled back. Try again.
PARENT_NOT_FOUND	The issue named for a breakdown does not exist.	Check the reference.
REPO_NOT_FOUND	flydocs_project_context named a repository the workspace does not link.	Use one from the list in the answer.
VALIDATION_ERROR	A field is wrong: its format, its scale, or it is missing.	Fix the field as described, and retry once.

The lifecycle rules

The relay applies the same lifecycle to every caller: a person at a terminal, an agent in a chat client, a script. It checks four things.

1. Every status change carries a comment. A transition without one is refused before it reaches the tracker. Tell the agent why the issue is moving and it will include it.
2. The move must be legal. The lifecycle is a state machine. Backlog to Complete is not a move.
3. An assignee before In Progress. An unassigned issue cannot be started.
4. Acceptance criteria met or deferred before Complete. A workspace can also require this before Review.

Each workspace chooses how hard the last two are applied: off, warn (the relay records a verdict and lets the move through), or enforce (the relay refuses). If a move you expected to be blocked goes through, the workspace may not be enforcing yet. The legal moves are:

From	To
Backlog	Ready, In Progress, Canceled, Duplicate, Archived
Ready	In Progress, Backlog, Canceled, Duplicate, Archived
In Progress	Review, Blocked, Canceled, Archived
Blocked	In Progress, Canceled, Archived
Review	Complete, Testing, In Progress, Canceled
Testing	Complete, In Progress, Canceled
Canceled, Archived	Backlog
Complete, Duplicate	No further moves

Rate limits

Everyone has the same limits, counted over a rolling one-minute window:

• 300 calls per minute across all tools.
• 30 calls per minute to tools that fan one call out into many issues. Today that is flydocs_issue_breakdown. A request like "clean up the whole backlog" is slowed on purpose.

Over the limit, the call is refused with HTTP 429, the code MCP_RATE_LIMITED, and a Retry-After header giving the seconds to wait. Wait that long. An interactive session does not reach 300 a minute; a runaway loop does.

Signing in again

A refusal at the HTTP level (status 401 or 403, with MCP_INVALID_TOKEN, MCP_UNAUTHORIZED or MCP_INSUFFICIENT_SCOPE) means the client's token is missing, expired, or lacks the mcp:tools permission. Sign in again from the client:

Client	How
Claude Code	Run /mcp, choose flydocs-cloud, then Authenticate.
Cursor	Settings → MCP, sign in to flydocs-cloud.
Codex	codex mcp login flydocs-cloud
VS Code	Command Palette → MCP: List Servers, start flydocs-cloud.
Claude Desktop, claude.ai, ChatGPT	Remove the connector, add it again with the URL, and sign in.

If sign-in works and every call is still refused, check the account: it needs a portal profile (MCP_IDENTITY_UNKNOWN) and a place in an organization (MCP_NO_ORGANIZATIONS).

The server does not appear, or points at the wrong place

• Restart the agent. Registrations are read at startup.
• Run flydocs doctor --tools. A detected agent with the wrong URL under flydocs-cloud shows as a warning on mcp.remote.registration.<agent>. An agent without the entry passes, because Remote MCP is optional.
• Run flydocs connect remote --client <agent> again. It updates an entry that differs and leaves one that is already right.
• "This version of Claude Code does not support --client-id": update Claude Code and run it again.
• "The FlyDocs remote MCP server is not configured yet": the install configuration is not available from the server right now. Try again later, or paste the connector URL by hand.
• "No supported coding agents found": name one with --client.
• Only the flydocs-cloud entry belongs to Remote MCP. A flydocs entry is the local server and is a separate problem. See Tool Surface Troubleshooting.

The organization switch

An organization admin can turn Remote MCP off for the whole organization, and back on. It is one switch.

1. In the FlyDocs portal, open Settings → Connections.
2. Find the MCP section and the FlyDocs MCP row.
3. Choose Deactivate to turn it off, or activate it to turn it back on.

Switching it off takes effect on the next call. Every call in that organization is refused with MCP_ORG_DISABLED, and the answer names the organization, so a person in several can tell which one closed. Nothing is deleted. Connections, sign-ins and installed config stay as they are, and turning it back on restores access. The members' Account → Connect your agent page shows the connection as inactive while it is off.

The switch covers the remote server only. The local flydocs mcp server in a repository and the CLI are not affected.

Still stuck

Send us the code from the refusal, the tool that was called, roughly when, and which client it was. Account → Connect your agent shows the last call and the client that made it.