Most MCP problems come down to one of four things: the connection is gone, it belongs to a different company than you expect, it has less access than you need, or the AI tool is misconfigured. Find your symptom below.
Connecting
The sign-in page appears, but no "Connect ... to Formwork" page.
You were not signed in to Formwork. Sign in; the consent page follows immediately. If it doesn't, start the connection again from your AI tool.
No consent page at all, and the AI just works.
Your AI tool already holds a valid connection and reused it. Check Settings → API access to see it. If you wanted a fresh connection (for another company or a different access level), revoke the old one there first, then connect again.
"Connection failed. The app sent a request Formwork cannot accept."
The AI tool started the OAuth flow with something Formwork rejects, usually a wrong redirect address or a missing PKCE challenge. This is a client configuration problem, not an account problem: remove the Formwork server from the tool and add it again exactly as in Connect Your Own AI via MCP. For Claude custom connectors, leave the OAuth client ID and secret fields empty.
I clicked Connect and nothing seems to happen in the AI tool.
The browser tab was handed back to the AI tool; look there. Claude Code and Codex show the server as connected in /mcp or codex mcp list. If the tool still says it is not authenticated, revoke the connection under Settings → API access and connect again.
"That access level is not available to you in this company."
Your role in this company is viewer, so only read access exists. Pick Read, or ask a company admin to change your role first.
"This company is archived."
Switch to an active company in Formwork before connecting.
Suddenly unauthorized (401)
The AI worked yesterday and now gets 401 / asks me to sign in again.
The connection is no longer valid. One of:
- it was revoked, by you or by a company admin, under Settings → API access;
- it expired and the AI tool could not renew it silently;
- you are no longer a member of the company it belongs to;
- the company was archived;
- for API tokens: the token expired or was revoked.
Sign in again from the AI tool (or create a new token). The old connection cannot be revived.
My script gets 401 with a token that looks right.
Check the header reads exactly Authorization: Bearer fw_... and that the token is the full string shown at creation. Then check the token's row under Settings → API access: status must be Active, and the company must be one you still belong to. Extend it if it is about to expire; an expired token stays expired.
Wrong company
The AI answers about the wrong company.
A connection is bound to the company you were viewing when you connected. It keeps working there even when you switch companies in Formwork. Ask the AI which company it is connected to; it knows. To work in another company, switch to it in Formwork and connect again from the AI tool; both connections then coexist and each stays in its company.
The AI's company changes when I switch companies in Formwork.
That is a connection made before September 2026, which follows your active company. Revoke it under Settings → API access and reconnect to get a company-bound one.
Missing tools and refused changes
"Tool not found" for create_formwork_resource, update_formwork_resource, upload_formwork_file or dispatch_formwork_agent.
The connection is read-only. Revoke it and reconnect choosing Read and write, or create a read-and-write token.
"this resource is not editable by you (it may be released, under review, or you may lack edit access)".
The item is not a draft, or your role cannot edit it. Approved documents and released records are never edited in place: ask the AI to create a new draft version. Items under review wait until the review is done. Viewers cannot edit anything, with or without AI.
"you do not have edit access for this company" / a forbidden answer on a role or a project.
Your account's permissions in this company don't allow it (roles, for example, can only be created by admins). The AI has exactly your permissions, never more.
The AI won't approve, release, archive or delete something.
By design. Those actions are not available through MCP or the assistant at all. Do them in Formwork.
"the file exceeds the ... upload limit".
Inline uploads are limited to 1 MB; ask the AI to use the upload-URL path for larger files (up to 15 MB on free plans, 150 MB on paid plans). SVG images cannot be embedded inline.
"upload URL is invalid, expired, or already used".
Upload URLs work once and for 10 minutes. Request a new one.
Searching and reading
The AI can't find a document I know exists.
Search matches literal text of at least three characters; long phrases miss. Ask for a shorter, distinctive word or stem ("evaluat", "nonconform"). Archived items are excluded unless you ask for them. Items in a restricted folder you cannot open are invisible to the AI too.
The AI finds an uploaded PDF or a Google Doc but can't tell me what's in it.
Search covers the content of uploaded files and synced Google Docs, but reading their content through MCP is not possible. Convert an uploaded file to a native document in Formwork to make it readable; Google Docs stay in Google.
The AI says "the Formwork manual does not appear to cover this yet".
It searched this manual and found nothing relevant. Reach out in the support chat; that is also how the manual grows.
Client-specific notes
- Claude (Desktop, Web): add Formwork as a custom connector with the MCP URL and nothing else. Connections show up as "Claude" in Formwork.
- Claude Code:
claude mcp add --transport http ..., then/mcp→ Authenticate. The browser redirects to alocalhostaddress on an ephemeral port; that is Claude Code receiving the authorization, not an error. Connections show as "Claude Code (formwork)" (the name includes your server alias). - Codex CLI: run
codex mcp login formworkif the first use does not open the browser. Tokens go in an environment variable via--bearer-token-env-var, never in the config file. - ChatGPT: requires Developer Mode; without it the Apps menu does not offer custom MCP servers.
- Two rows for the same app: every fresh sign-in creates a new connection; refreshes replace the old one over time. Revoke the ones with no recent Last used.
Still stuck?
Under Settings → API access, note the app name, company, access and Last used of the connection in question, then reach out in the customer support chat in the bottom right corner with the exact error text your AI tool shows.