Skip to main content

Troubleshooting

Hosted Token Is Rejected​

  • Create the token in Settings > MCP Access on the same Ideagram instance as the MCP endpoint.
  • Send Authorization: Bearer <token> with the full idg_pat_... value. Do not send your user ID or Supabase service key.
  • Check that the token has not been revoked. If the associated session cannot be refreshed, sign in again, create a replacement token, and update the client's Authorization header.
  • If MCP Access is locked, check the organization's enabled features with its administrator.
  • Ordinary client users do not set Supabase service keys in their MCP client configuration.

PATs currently derive from your browser's Supabase session. Session termination or refresh-token reuse detection can invalidate them even without an explicit PAT revocation. An already invalidated session cannot be repaired by reconnecting the MCP client.

Endpoint Or SSE Returns 404​

Use https://ideagram.dev/mcp for the hosted alpha instance. A plain "page could not be found" response indicates a wrong URL or a missing deployment route, before MCP authentication runs.

The old alpha.ideagram.dev hostname returned DEPLOYMENT_NOT_FOUND when checked on October 12, 2026. Update clients still using that hostname to ideagram.dev.

The HTTP server uses stateless Streamable HTTP: each POST is authenticated independently, with no in-memory session affinity between Vercel instances. GET/SSE and DELETE return 405 Method Not Allowed, which is expected for this transport. Restart the MCP connection after deploying this fix if the client still holds an old session ID.

Operators must regenerate the committed api/mcp.js with npm run build:mcp-http before deploying server changes. A deployment still reporting MCP session not found is using the older stateful handler.

Authentication Is Temporarily Unavailable (503)​

Retry shortly. A token lookup, refresh, or save failed, or a concurrent request changed the token during renewal. This differs from an invalid/revoked token (401); replacing a PAT is not the first step for a temporary infrastructure failure.

Writes Are Blocked Or Queued​

Hosted clients use the token scope, not a client-side IDEAGRAM_MCP_READ_ONLY flag. read blocks writes; write allows permitted edits; propose queues decision/spec upserts but applies other permitted writes directly. Resource permissions still apply.

Changing a prompt does not change the server's permissions.

Cannot Find My Project Or Diagram​

Use list_organizations, list_workspaces, and list_projects, then list_diagrams and get_diagram. The server does not inherit the current browser selection. Check the selected instance and the token owner's membership if data is missing.

Operator Allowlist Tokens​

If using the advanced IDEAGRAM_MCP_HTTP_TOKENS fallback, check the bearer token record, real user identity, matching Supabase user access token, and any configured expiry. Expired Supabase access tokens must be replaced. This is separate from self-service PAT management.

ChatGPT Cannot Connect​

Check ChatGPT compatibility. The current PAT endpoint is not a documented direct ChatGPT-web setup. A local JSON config does not configure ChatGPT web.

Documentation Deployment Cannot Find build​

For the docs Vercel project, set Root Directory to docs-site, build with npm run build, and use Output Directory build. The docs log should run Docusaurus, not the root Vite application. Save the settings and redeploy.

Canvas View Fails To Load​

Refresh after a deployment. If the same action repeatedly fails, record the action, browser error, and any displayed error reference. A view-loading error can also be a runtime failure; do not assume every occurrence is an outdated build.