Troubleshooting

My agent doesn't use the workspace

The agent has the tools but writes without calling get_context.

• Check it's connected. Most clients show connected servers and their tools somewhere in settings. If the tools aren't listed, the connection didn't finish; reconnect.
• Tell it once. "Use the context tools before you write this." Agents decide for themselves when to call tools, and a direct request settles it.
• Add a line to your agent instructions. Something like "Always pull context before writing anything a customer or prospect will read, even short replies." See Agent instructions.
• Make sure the workspace describes itself. Agents decide whether a request is about your company partly from the tool description, which lists your page types and most-used tags. A workspace with no published pages or no tags gives them little to go on. Open What agents see when they connect on the Connect agents page to check.
• Check the client keeps it switched on. Some clients let you toggle connectors per chat, or limit how many tools are active at once.

The agent called get_context but missed something

Start in Activity. Find the request and look at which pages came back and which pack matched.

• Nothing came back: the page might not be published, might have expired, or might be somewhere the connection can't see (a folder a key isn't limited to, or a folder the person doesn't have access to).
• The wrong pages came back: the page you expected probably doesn't say what you think it says in a way search can find. Put the fact under a specific heading, in a section of its own. See Writing pages agents can use.
• The page came back but the agent ignored part of it: if it's important, make it a rule, or put it in the page's usage note.
• A whole page you expected is missing: pinned and pack pages are skipped when they don't fit in three quarters of the budget. Either the agent asked for a small budget, or your rules are taking most of it.

How get_context chooses goes through every step.

I changed a page but agents still see the old version

Almost always, it hasn't been published. Check the chip at the top of the page: Unpublished changes means agents are getting the previous version. Press Publish.

If it's published and still looks old, check you're editing the page you think you are (two pages can have the same title), and that the agent didn't get the content from a different page that says the same thing.

New tags don't apply to pages that were published before the tag was added. Open the pages that mention it and click Republish.

Claude or ChatGPT won't connect

• Use the sign-in URL, the one ending in /api/mcp, or a workspace URL. Both work for signing in.
• Sign in with the same account you use for the app. If you have more than one, make sure it's the one that belongs to the organization.
• Check you have access to a workspace. A member with no workspace access has nothing to connect to. Ask an owner or admin.
• If the Connect agents page shows a warning that sign-in connections aren't configured, your server hasn't been set up for them yet. Use an API key with a client that supports custom headers in the meantime, like Cursor or Claude Code.

"You're signed in as ..., which doesn't have access"

You signed in on a workspace URL with an account that isn't in that workspace. This usually happens when you're in workspaces under two accounts: the browser was still signed in as the other one. Sign out of the app in your browser, then reconnect the server (in Claude Code, /mcp and choose it) and sign in with the account that belongs to the workspace.

A sign-in connection is reading the wrong workspace

On a workspace URL, the connection only ever reads that workspace. On the sign-in URL, connections use your default workspace. Open Connect agents in the workspace you want and press Make this my default. Or ask the agent to use a specific workspace by name; it can see your workspaces with list_workspaces. If you have several workspaces and no default, the agent has to name one on every call.

My API key returns 401

The key isn't being accepted. In rough order of likelihood:

• The header is wrong. It must be Authorization: Bearer cmcp_..., with the word Bearer and a space.
• It's the wrong workspace URL. A key only works for its own workspace. If you're using a workspace URL (/api/mcp/...), make sure the id is the workspace the key was made in. The sign-in URL (/api/mcp) accepts any key and uses the key's workspace.
• It's been revoked. Check the key list on Connect agents.
• It's a personal key and its creator lost access to the workspace.
• Its creator was removed from the organization. That revokes their personal keys, and their workspace keys too unless someone took them over.
• It was limited to folders that have all been deleted. The key list marks these.

Edit tools are missing, or edits are refused

• The key is read-only. Read-only keys don't get editing tools. Create a key with Can edit.
• The person can only read here. A sign-in connection can only edit what the person can. They can still keep private notes.
• It's a rule or pin. Making a page a rule, or always including it, needs whole-workspace edit access.
• It's an access change. update_owners needs a key with Can change who has access to pages and folders.
• It's a publish. publish_page needs publish access: a key created with Can edit and publish, or a sign-in from someone who can publish that page. Editing alone keeps changes as drafts.
• It's a private note from a workspace key. Private notes belong to a person, and a workspace key isn't one.

An agent's edit didn't show up for anyone else

That's by design. Edits to page text are drafts until someone publishes them. Look in Unpublished, or under Activity → Agent edits, and publish it from there. If you'd rather the agent published itself when you ask, it needs publish access (see above).

"Too many requests for this workspace"

The workspace made more than 120 retrieval requests in a minute. Wait a minute and it clears. If you see this regularly, something is probably calling in a loop: check Activity for the same request repeated, and look at whichever key it's coming from.

A file link doesn't work

Download links from get_file and the REST API last two minutes. Ask for a new one and fetch it straight away.