KoltrixTroubleshooting a Koltrix MCP connection: symptoms and fixes
Not authorized, missing permissions, no send tool, a wrong workspace or no card: a symptom-first checklist for fixing a Koltrix connection in minutes.
On this page(12 sections)
Most MCP connection problems are one of about six things, and nearly all are fixed in under two minutes once you know which. This is the checklist we would want if a connection stopped working: symptoms first, then causes, then the fix.
If you have not connected yet, start with Claude, ChatGPT or Cursor and Claude Code. Everything here assumes the server URL is https://mcp.koltrix.com/mcp, which is the same for every app.
Start here: three quick checks
Before any specific fix, check these, because they explain a surprising share of problems.
- Is the URL exact?
https://mcp.koltrix.com/mcp, withhttps, themcpsubdomain and/mcppath. A missing path or a stray space stops it at the first step. - Can the network reach it? Your app must reach
mcp.koltrix.com, and your browser must reachapp.koltrix.comfor the approval page. On a work or school network, a firewall may block one of them. - Which workspace did you approve? A connection belongs to one workspace. If you are in several, you may have approved the wrong one.
Symptom guide
| Problem | Likely cause | Fix |
|---|---|---|
| The app says it is not authorized, or asks you to sign in again | The connection was revoked, expired after 30 days unused, or assistants were turned off | Reconnect from the app. In Claude Code, run /mcp |
| The app says AI assistants are turned off for the workspace | An owner or admin switched them off | An owner or admin can turn them back on in Settings, under AI assistants |
| The assistant cannot find a message you can see in Koltrix | Wrong workspace approved | Reconnect and choose the right workspace |
| A teammate's mailbox is missing | The assistant has your access, and you do not have theirs | Ask an admin for access to that mailbox in team settings |
| You cannot find a draft | It is in the Drafts of the mailbox it was written from | Open the link the assistant gave you, or check Drafts for the right mailbox |
| Labeling or drafting fails, but reading works | You did not approve that permission | Revoke the connection, connect again, and approve it |
| The approval page says the redirect address is not allowed | The app tried to send you back to an address that is not https (or a local address) |
Update the app, or report it to its maker |
| Connecting from a work network fails | The network blocks mcp.koltrix.com or app.koltrix.com |
Ask IT to allow both, or try another network |
Authorization problems
"Not authorized" is the most common message and has three real causes.
The connection expired. An access token lasts an hour and renews itself with a refresh token, which keeps working for up to 30 days of inactivity. If you have not used the connection for a month, it lapses by design. Reconnect.
The connection was revoked. You, or someone using your account, clicked Revoke in your Koltrix settings. Revocation takes effect immediately.
Assistants were turned off. A workspace owner or admin can turn AI assistants off for the whole workspace, and every connection stops at once. They can turn it back on, and new connections can be made after that.
In Claude Code, run /mcp, choose koltrix and authenticate again. In Claude and ChatGPT, reconnect the connector from its settings page and approve again.
"It works, but it cannot do what I asked"
This is almost always permissions. Koltrix asks for four permissions and a connection only has the ones you approved.
| You asked it to | Permission needed |
|---|---|
| Search or read mail | Read |
| Label, archive, mark read, star | Organise |
| Write a draft | Draft |
| Send a draft | Send, with extra conditions |
If the assistant reads fine and fails on organizing or drafting, revoke the connection in Koltrix, connect again and approve every permission you want. Permission changes need a fresh approval; they do not update in place.
Sending problems
Sending is the most layered feature, so it has the most reasons to say no.
| Message | What it means | Fix |
|---|---|---|
| The assistant says it cannot send, or the send tool is missing | Sending needs a workspace switch and your opt-in | An owner or admin turns on Allow assistants to send email after you confirm. Then revoke the connection, connect again and tick Also allow sending email |
| The confirmation does not match | The recipients or subject changed after the assistant read the draft, or it left an address out | Ask it to read the draft again and show you the message before it retries |
| The draft has Bcc recipients or attachments | An assistant cannot send those, because the confirmation cannot cover them | Open the draft in Koltrix and send it there |
| Refused because of a limit | At most 10 recipients per message, 20 sends a day per connection, 50 a day per workspace through assistants | Send the rest from Koltrix, or wait. The count resets at midnight UTC |
| Refused over quota or billing | The workspace is over its sending allowance or frozen for billing | An owner can fix it in billing settings |
Two things catch people out. First, apps connected before sending was enabled cannot send, and you must reconnect and tick the box. The box only appears if the workspace already allows sending. Second, in the Koltrix connections list, a connection that can send is labeled so, which is a quick way to check. Safe sending from Claude explains each gate.
Card problems
Some apps show interactive cards. If you see only text, your app may not support them, and nothing is wrong. If you expected a card:
- You declined the app's prompt (Claude may ask the first time). Allow it.
- An organization turned interactive connectors off. Ask an admin.
- A card says it expired or the draft changed. A card's Send works once, for 30 minutes, for the draft exactly as shown. Use Edit in Koltrix.
- A card says Sending is off. The workspace setting or your send permission is missing. The card links to the draft so you can send it in Koltrix.
MCP Apps cards, explained has the full list.
Cursor and other editors
- The server does not appear. Check the JSON syntax and that the file is
~/.cursor/mcp.jsonor.cursor/mcp.json, then reload the MCP settings. - The app only supports local servers. Use the
mcp-remotebridge:npx -y mcp-remote https://mcp.koltrix.com/mcp, set as the command in the app's config. - It does not ask you to sign in. Open the app's MCP settings, find Koltrix and start the sign-in from there.
The "wrong mailbox" family
- Drafts come from the wrong address. If the assistant does not name a mailbox, Koltrix uses the one the conversation was addressed to, or your first. Name the address in your prompt, or ask the assistant to list your mailboxes first.
- A shared address is missing. You may lack access to it. Ask an admin.
- Results look thin. Ask the assistant to say which mailboxes and folders it looked in.
Reading logs and reports
When you ask for help, it is easier if you have details:
- Which app, and roughly when it failed.
- The exact message the app showed.
- Whether reading works but writing fails, or nothing works.
- Whether it worked before.
If you are an admin, the workspace audit log records connections, token renewals, revocations and tool calls with the tool name. It never includes your mail. Auditing what an AI assistant did in your mailbox shows how to read it.
When to disconnect and start over
If you have tried the above and it still misbehaves, a clean reconnect is quick and rarely makes things worse:
- Revoke the connection in your Koltrix settings.
- Remove the connector from the app.
- Add it again with the URL and approve.
It takes about a minute and removes any stale state.
Still stuck
Email [email protected] with the app you use and roughly when it failed. The full reference, including the troubleshooting table this post is based on, is in the docs, and koltrix.com/mcp has the overview.
Key takeaways
- Check the URL, the network and the workspace first; they explain many failures.
- "Not authorized" means expired (30 days unused), revoked or assistants switched off. Reconnect.
- Reading works but writing fails means a permission was not approved. Revoke and reconnect.
- Sending needs a workspace switch plus your opt-in, so reconnect and tick the box after an admin enables it.
- No card means the app may not support them. Open the draft in Koltrix.
Start with Koltrix
Your domain, one inbox, and an API that sends.
A team inbox where AI sorts and drafts (nothing is sent without your click), plus the transactional API and SMTP relay your product sends with. 7 days free, no card.
