MCP troubleshooting

Your AI assistant usually tells you ContentForge's reason word for word. Find it below.

The tool list looks out of date, or tools are missing

Your app reads ContentForge's list of tools when it connects, and some apps keep that list for a while.

1. Start a new chat or session.
2. Still old? Quit and reopen the app, or refresh the connector in its settings.
3. Still old? Disconnect it on Settings → API & MCP → Connected apps (sign-in) (or remove it in your app) and connect again.

If editing or publishing tools are missing, you probably didn't tick them when you connected. A connection only lists the tools it's allowed. Reconnect and tick Change drafts (and Publish if you want it). For a key, make a new key with Read + write drafts or Read, write + publish. See MCP permissions explained.

Sign-in doesn't work

• You signed in on a client domain. Agency sign-in only works on ContentForge's main address. On one of your client domains, only that client's portal logins can connect, so an agency login sees "this account can't connect AI tools yet". Copy the MCP server URL from Settings → API & MCP on the main address and add the connector again with that.
• "This app isn't registered with ContentForge" or "The app sent a return address it didn't register": remove the connection in your AI app and add it again.
• "This consent screen expired": the connect page is good for 30 minutes. Start again from your AI app.
• "You're signed out": sign in to ContentForge, then start again from your AI app.
• A client person sees "… hasn't turned on "Connect your own AI tools" for you": the agency turns it on in Client → Settings. See Client MCP access.
• "This account is suspended for an unpaid invoice": the account owner pays it in Billing & credits, then connect again.
• The app can't sign in at all (no browser page opens): use an API key instead.

"This connection doesn't have the write scope needed for …"

The connection was made without that level. Connect again (or make a new key) with Change drafts, or Publish for publishing. "This API key can't publish" means the same for publishing a blog post or showing a collection item.

Refused because of your role or permissions

• "The person this connection acts as doesn't have access to … in ContentForge": that tool is turned off for you under Settings → Team Members → Tools. Ask your Owner or an Admin.
• "Client … not found in your agency" for a client you know exists: you're a Member who isn't assigned that client. Ask to be assigned.
• "… is only available to your agency, not through a client connection" or "Zeus is only available to your agency": this is a client person's connection. Client connections never get Zeus, paid runs or agency-only tools.
• "Your access doesn't include … — it needs …": a client person's permissions don't cover it. The message names the permission. The agency can add it in Client → Settings → Edit access.
• A part of a page is refused for a client connection: it's locked for client editing.

Not enough credits

Your assistant says the cost and that you don't have enough, for example "Buy credits in ContentForge → Billing & credits, then try again." Nothing ran and nothing was charged. Buy credits on Billing & credits and ask again.

If your assistant says it's showing you the cost again after you said yes, that's normal: it has to show the cost first, with the same details, in the last 30 minutes. Say yes once more.

A change doesn't show

• Not on the live site? Changes go to the draft. Ask your assistant to publish (needs Publish), or publish in the editor.
• Not in the editor? Open changes appear by themselves. If a bar says "This site was changed somewhere else", click Refresh. A shared preview link is a separate page, so reload it.
• "Conflict: this page changed since you read it": someone edited the page at the same moment. Nothing was saved. Your assistant reads the page again and redoes it. Just ask it to try again.
• Your own unsaved edits on the same section: they're kept, and the section shows Updated elsewhere. Click Review to choose, or Keep mine.
• Wrong site or page? Ask "Which site and page did you change?" and check it's the one you meant.

Undo didn't work

• "No change … that you can undo": ask your assistant for the change number from that change's result. Client connections can only undo their own changes.
• "That change was already undone."
• "That change has nothing to undo": the change failed, or it's a kind undo doesn't cover (blog posts, collection items, social posts, press releases, new clients or sites, a deleted page).
• Some parts "skipped": those parts were changed again since, so undo left them alone. Ask for a fresh change instead.
• Undo in the editor only undoes your own edits there. Ask your assistant to undo its changes.

The key or connection stopped working

• "This connection has been revoked.": the key was revoked, or the app was disconnected. Make a new key, or connect again.
• "This API key or access token has expired.": the key reached its expiry date, or a signed-in app wasn't used for 30 days. Make a new key, or click Connect in your app again.
• "The person this connection acts as is no longer part of the agency.": keys and connections stop when someone leaves. The person who'll use it makes their own.
• "The person this connection acts as no longer has access to connect AI tools.": a client person's Connect your own AI tools was turned off.
• "Sign in needed" or "Invalid API key or access token.": the key wasn't pasted in full, or the header is wrong. It must be Authorization: Bearer followed by the whole key.
• "Account suspended": the account has an unpaid invoice. It works again as soon as the owner pays it in Billing & credits. Client connections see "temporarily unavailable" meanwhile.

"Rate limit: 120 requests per minute"

Each key, and each signed-in app, can make 120 requests a minute. Every tool your assistant uses counts. The message says how many seconds to wait. This normally only happens on very big jobs, such as changing hundreds of items at once. Ask your assistant to slow down or do it in batches. Checking a long run's progress about once a minute is plenty.

"Request too large" or an image won't upload

A single request can be up to about 12 MB, and a pasted image over about 4 MB is refused. Give your assistant the image's web address instead of the file. Images can be JPEG, PNG, WebP, GIF or AVIF, up to 25 MB.

"Not found"

• "Site … not found in your agency": the site was deleted or archived, it belongs to a client you're not assigned, or the id is wrong. Ask "List the sites for this client." Only Mount Olympus sites are listed.
• "Client … not found": check the name with "List my clients", or you're not assigned that client.
• "No page … on this site": ask "List the pages on this site" and use the page's name or address.
• Blog post, collection, item or recommendation not found: ask your assistant to list them first, then pick from the list.
• A client person's connection only finds their own business and the sites they're assigned.

Publishing stopped

• "This page still shows the template's reviews": those are another business's reviews. Change or remove them, or tell your assistant to publish anyway if you're sure.
• A blog post won't publish while the client approves blog posts and hasn't approved it. Send it for approval in ContentForge first.
• One page won't publish: publishing one page only works on a live site, and new pages, address changes and dynamic pages need the whole site published.

Still stuck?

Owners and Admins can check Recent changes made through the API on Settings → API & MCP: every change, which key or app made it, and the exact error if it failed.