Errors and troubleshooting
Every error people hit connecting and using the Stensul MCP server: what it means, why it happened, and who can fix it.
Check these first
- Is your instance name in every URL? The MCP URL, the redirect URI and the OAuth URLs all need it:
https://mcp.stensul.com/<your-instance>/… - Does it fail for everyone, or one person? Everyone on a connection means a scope. One person means a permission.
- Does it work in the Stensul app? If yes and it fails in your AI host, it's the connection's scopes; the app doesn't use them.
- Did an admin just add a scope? That revokes existing tokens. Sign in again.
Error table
| Status | Message | Cause | Fix |
|---|---|---|---|
| 401 | Authentication expired or missing | The session's authorization expired. | Sign in again when the host prompts. On a 401 or 403, the server's instructions tell the model to re-check sign-in first. |
| 403 | Insufficient OAuth scope (403): The token lacks the required scope | The API connection doesn't have the scope this tool needs. | An admin adds the scope to the API connection. Then sign in again: adding a scope revokes existing tokens. |
| 403 | Invalid scope(s) provided. | The connection was created with only api-read/api-write, which apply to server-to-server integrations and do nothing for MCP. | Select the granular scopes (emails:read, emails:write, libraries:read, …) on the connection. |
| 403 | API error (403): Action is unauthorized. | The signed-in user's role lacks the permission, for example edit_campaign. | Grant the permission to the user's role in Admin > Users & Roles. It works for other users on the same connection. |
| 403 | API error (403): Sent emails cannot be edited. | The email has already been sent. | Nothing to fix. Copy it and edit the copy. |
| 403 | Access denied (403): Your IP address is not in the allowed list | The caller's IP isn't in the external API allowlist. | An admin adds the IP in Settings > External API > Allowed IPs. |
| 403 | API error (403): | The server didn't say which check failed. | Work through the other 403 rows: confirm sign-in with stensul-check-auth, then scopes on the connection, the person's permissions, and the IP allowlist. |
| 409 | Version conflict | The email changed since your last read, and you passed its old save_version. | Read the email again and re-apply your change on the current version. Never retry by dropping save_version. |
| 422 | Field not enabled for this library | stensul-update-email-settings sent a title, subject line or preheader the library doesn't enable, so the whole call is declined. | Send only fields the library enables (see stensul-get-libraries). |
| declined | Content declined by a guardrail | A value is outside what the template allows: an off-palette color, a size out of range, locked text. | Keep the value within the guardrail or make no change. Guardrails are enforced by Stensul and cannot be overridden from a chat. |
| sign-in | Redirect URI mismatch | The redirect URI on the API connection is missing your instance name or doesn't match exactly. | Set it to exactly https://mcp.stensul.com/<your-instance>/oauth/callback (Writer also needs its own callback). |
| 410 | Gone | A client is still calling the old shared /mcp endpoint with X-Stensul-* headers, which was removed. | Use the per-instance endpoint https://mcp.stensul.com/<your-instance>/mcp with OAuth. Existing Client IDs keep working. |
| 422 | Fixed header or footer can't be added | stensul-add-email-module was asked for a module the library fixes at the top or bottom of every email. | Nothing to fix. Those modules are governed by the library. Report it and don't offer a substitute. |
| 422 | The "before" module is not in this email | The email changed since it was read, so the module named in beforeModuleId is gone. | Read the email again and ask the user where the new module should go now. |
Sign-in problems
| What you see | Fix |
|---|---|
| No API connections page in Stensul | The external API isn't enabled, or you don't have access_admin_api_connections. Ask your Stensul customer success manager. |
| The client secret isn't shown anymore | It's shown once. Create a new connection for a fresh ID and secret. |
| ChatGPT won't finish connecting | Clear the pre-filled Authorization server base and Registration URL fields. Keep Auth URL, Token URL and Resource. |
| Writer asks for a client secret | Expected: create the connection with PKCE off. |
| Claude or ChatGPT asks for a client secret | Leave it blank: PKCE connections have none. |
| Stensul isn't listed in Claude's Customize > Connectors | Your Claude admin hasn't added it yet. Ask them to add the custom connector under Admin settings > Connectors. |
| Image upload from the chat fails in Claude | Allow <your-instance>.stensul.com in Claude's Capabilities > Additional allowed domains. |
Two browser tabs or EADDRINUSE in Claude Code | Pin --callback-port 3334. |
| A change doesn't show in the preview | Close and reopen the email, especially if it's also open in the Stensul editor. |
Reporting a problem
Send your Stensul contact, or help@stensul.com: which host you used, what you asked, what you expected, what happened, and a screenshot. Don't include tokens or client secrets.