Troubleshooting

Can’t connect

What you see	Cause	Fix
The first tool call returns `401`	Normal. The challenge is what starts your host’s OAuth flow.	Let the host open the sign-in page. If it does not, re-add the server and run its login step (Connect).
The host expects an SSE stream or a session id	The server is JSON-only and stateless. Current hosts handle this.	Use a current host version, or bridge with `npx -y mcp-remote https://mcp.sidecars.ai/mcp`.
The host only speaks stdio	Remote HTTP is not supported by that host.	Same `mcp-remote` bridge.
Opening the URL in a browser shows an error	The URL is for MCP clients, not browsers.	Paste it into a host.
Batched JSON-RPC requests are rejected	Batching was removed from the protocol.	Send one request per POST.
Your host lists a docs server from this site	Mintlify hosts a search server for these pages; it cannot act in a workspace.	Use `https://mcp.sidecars.ai/mcp` for the product server.

What you see	Cause	Fix
`403` with `error="insufficient_scope"` naming a scope	The tool needs a scope the token does not carry. Write, comment, export and document-read tools all arrive by step-up.	Hosts re-run consent for that one scope automatically. If yours does not, reconnect and grant it.
`401` with `error="invalid_token"` on any method, including `tools/list`	The token is expired, malformed, opaque, or issued for another server. Tokens last 24 hours.	Sign in again from the host.
Consent asks for `pods:read` or `conversations:write`	Those scopes are advertised but no exposed tool uses them (`conversations:read` is used, by `list_conversations`).	Granting them is harmless; nothing changes.

Workspace errors

These come back as tool errors after a successful sign-in. Each message names its fix.

Message	Fix
Your account is not registered in this workspace app yet. Sign in to the web app first, then re-authenticate this MCP connection.	Open sidecars.ai once, then reconnect.
Your token carries no active workspace. Re-authenticate this MCP connection and pick a workspace on the consent screen (Claude Code: /mcp; Codex: codex mcp login).	Reconnect and choose a workspace on consent.
Your workspace hasn’t finished syncing yet. Retry in a moment — no fallback workspace is ever substituted.	Retry shortly.
You are not a member of the workspace this token claims.	Reconnect and pick a workspace you belong to.

To act in a different workspace, reconnect and choose it on the consent screen.

Permission refusals

Refusals use the app’s own wording and never reveal whether an artifact exists.

Message	Cause	Fix
`Artifact not found`	Not visible to you, in another workspace, or no such id. Also returned for a conversation or pod you cannot reach.	Check the id with `list_documents`; ask the owner to share.
`This document is read-only for you`	You are a viewer and tried to write or comment.	Ask for commenter or editor access in the app.
`You can comment on this document but not edit it`	You are a commenter and tried `edit_document` or `write_page`.	Use `add_comment`, or ask for editor access.
`This document is archived`	Writes to an archived artifact are refused.	Unarchive it in the app.
`That conversation is archived or gone, so nothing was created.`	`create_document` or `create_page` into an archived room.	Create in another room, or with a `scope` instead.
`That artifact is an HTML page, not a document — use write_page.` and similar	Wrong tool for the artifact kind.	Use the tool the message names. Tables cannot be edited over MCP.

There is no share, grant, move, link, restore or delete tool, so none of these can be worked around from an agent. See Authentication and access.

Write conflicts

Each of these is a tool result with isError: true and an error code in structuredContent.

`error`	Tool	Meaning	Recovery
`version_conflict`	`edit_document` (`replace_all`), `write_page`	The artifact moved since your read. `current_version` is included; `write_page` adds `diff_excerpt`.	Re-read, merge your change onto the current content, write again with the new version.
`excerpt_not_found`	`edit_document`	The quoted `section_excerpt` no longer matches. `candidates[]` lists the nearest passages with `similarity`.	Re-read and quote one exactly.
`excerpt_ambiguous`	`edit_document`	The excerpt matches more than one place. `locations[]` shows each.	Quote a longer passage that matches once.
`write_conflict`	`edit_document`, `create_document` (retry)	Another agent holds the document’s write lease.	Wait `retry_after_seconds` (up to 30) and retry.
`not_empty`	`edit_document` (`fill_empty`)	The document already has content.	Read it, then `append` or `replace_section`.
`selection_gone`	`edit_document`	The targeted section was removed while the write queued.	Re-read and resolve a fresh excerpt.
`format_unavailable`	`export_document`	The format does not apply to that kind.	Documents: markdown, pdf. Pages: html. Tables: csv, json, markdown.
`export_disabled`	`export_document`	Server-side export is off for the workspace.	Copy the markdown from `read_document` instead.
`source_missing`	`export_document`	The artifact is empty.	Fill it first.
`still_rendering`	`export_document`	A render of the same version is in progress.	Retry shortly.
`render_failed`	`export_document`	The renderer failed.	Report it to the person.

Successful writes can also report an early stop: stop_reason: "cap" (the 60,000-character budget; continue with another call) or anchor_gone (the section was removed; do not re-add it). A script_stripped warning on a page means its scripts are stored but will not run when viewed.

How errors come back

Three kinds, at three layers:

Recoverable tool errors (isError: true)

Refusals, conflicts and unavailable exports are tool results, not protocol errors. The text says what to do next; diagnostic structure rides in structuredContent:

{
  "content": [{ "type": "text", "text": "The document moved from version 12 to 14 since you read it. Re-read it, merge your changes onto the current content, and write again with the new expected_version." }],
  "structuredContent": { "error": "version_conflict", "expected_version": 12, "current_version": 14 },
  "isError": true
}

Failures from below the tool (an access gate, a backend error) use the form Tool failed: <reason>, where <reason> contains the gate’s own wording, for example Artifact not found.

Invalid arguments

Arguments that violate a tool’s JSON schema (wrong type, unknown enum value, missing required field) are rejected before the tool runs, as a JSON-RPC -32602 error.Checks a tool performs itself (expected_version missing on replace_all, two selectors passed together) come back as Tool failed: followed by the check’s message, such as `section_excerpt` is required for replace_section.

HTTP-level refusals

Status	When	Header
`401`	No token on `tools/call`, or an invalid token on any method	`WWW-Authenticate: Bearer error="invalid_token", resource_metadata="..."`
`403`	Token lacks the tool’s scope	`WWW-Authenticate: Bearer error="insufficient_scope", scope="documents:write"`

Hosts handle both by starting or re-running the OAuth flow.

Limits

Limit	Value
Search results per call	1 to 25 (default 10)
Characters per search excerpt	2,000, then `[…truncated]`
Characters per search response	50,000, then a `[…N more results truncated]` line
Documents per listing	1 to 50 (default 50); `truncated: true` when more exist
Pods enumerated for an org-wide listing	50, then `truncated: true`
Read window	24,000 characters per `read_document` call; page with `offset`
Content per edit or create	60,000 characters; longer writes stop early with `stop_reason: "cap"`
Versions per listing	The 20 most recent
Idempotency key window	10 minutes
Export download URL	15 minutes
Busy-document retry hint	Up to 30 seconds
Access token lifetime	24 hours

Something else

Every call is recorded in the workspace’s agent activity history, and every write lands as you via the host, so a person can see in the app which client did what. Writes are checkpointed and undoable there. If a result does not match this page, note the exact text and the tool name when you report it.

Get started

Use it

Reference

Can’t connect

Workspace errors

Permission refusals

Write conflicts

How errors come back

Limits

Something else

​Can’t connect

​Sign-in and scope errors

​Workspace errors

​Permission refusals

​Write conflicts

​How errors come back

​Limits

​Something else

Can’t connect

Sign-in and scope errors

Workspace errors

Permission refusals

Write conflicts

How errors come back

Limits

Something else