AI assistants (MCP)
Koltrix works with the AI assistant you already use. Connect Claude, ChatGPT, Cursor or any other app that supports the Model Context Protocol (MCP), and you can ask it things like:
- "What came in overnight that needs a reply from me?"
- "Find the thread with Dana about the contract renewal and summarise it."
- "Label everything from our accountant Finance and archive the receipts."
- "Draft a reply to the latest message from Acme saying we'll ship on Friday."
The assistant works through your Koltrix account, with exactly the access you have in the app, and only after you approve it.
Koltrix's own AI (sorting, summaries, suggested replies and auto-reply drafts inside the app) is separate and unchanged: it never sends without a person clicking Send.
Server URL
https://mcp.koltrix.com/mcpThis is the only thing you paste. There is no API key: the first time an app connects, it sends you to Koltrix to sign in and approve it.
Set it up
Claude (claude.ai)
- In Claude, open Settings → Connectors and choose Add custom connector.
- Name it
Koltrixand pastehttps://mcp.koltrix.com/mcpas the URL. - Click Connect. Claude opens Koltrix: sign in if you need to, choose the workspace, check the permissions and click Approve.
- In a chat, turn Koltrix on from the tools menu and ask about your mail.
On Claude Team and Enterprise plans an owner may need to add the connector for the organisation first; everyone then connects their own Koltrix account.
Claude Desktop
Claude Desktop uses the same connectors as claude.ai. Add Koltrix under Settings → Connectors → Add custom connector with the URL above, in either app, and sign in when asked. You don't need to edit a configuration file.
Claude Code
claude mcp add --transport http koltrix https://mcp.koltrix.com/mcpThen run /mcp inside Claude Code, choose koltrix and authenticate. Your
browser opens Koltrix to sign in and approve. Add --scope user to the
command to make Koltrix available in every project rather than just the
current one.
ChatGPT
- In ChatGPT, open Settings → Apps & Connectors. Under Advanced settings, turn on Developer mode if your plan requires it for custom connectors.
- Choose Create (or Add custom connector), name it
Koltrix, pastehttps://mcp.koltrix.com/mcpand choose OAuth for authentication. - Sign in to Koltrix and approve when asked.
Koltrix offers the search and fetch tools that ChatGPT's connectors and
deep research expect, alongside the full tool set below. Menu names vary
between ChatGPT plans and change from time to time; look for "connectors" or
"apps".
Cursor
Add Koltrix to ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one
project):
{
"mcpServers": {
"koltrix": {
"url": "https://mcp.koltrix.com/mcp"
}
}
}Open Cursor's MCP settings, find Koltrix and sign in when Cursor asks.
Other apps
Any MCP client that supports remote servers over Streamable HTTP with OAuth sign-in can connect with the URL above.
For an app that can only start local (stdio) servers, bridge to Koltrix with
mcp-remote:
{
"mcpServers": {
"koltrix": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.koltrix.com/mcp"]
}
}
}Signing in and permissions
When an app connects for the first time, Koltrix shows an approval page at
app.koltrix.com with:
- the app's name and the website it will send you back to,
- the workspace to connect, if you belong to more than one,
- the permissions it asks for, in plain words,
- if an admin has allowed sending in that workspace, an unticked box, Also allow sending email.
Click Approve to connect or Deny to refuse. The connection belongs to you, in that one workspace. To use a second workspace, connect again and choose it.
| Permission | What it allows |
|---|---|
mail.read | Search and read your mail, and list your mailboxes and labels. |
mail.organize | Add and remove labels, archive, mark read or unread, and star. All of these can be undone in Koltrix. |
mail.draft | Save drafts to your Drafts folder for you to review. On its own it can't send them. |
mail.send | Send a draft that already exists, after the assistant has shown you the message and you've said yes. See Sending email from an assistant. |
Apps ask for the first three by default, and the approval page lists each one.
mail.send is never part of that default. It appears as its own checkbox, unchecked,
and only when a workspace owner or admin has turned assistant sending on for the
workspace you are connecting. If you don't tick it, the connection can't send,
whatever the app asks for.
Behind the scenes this is standard OAuth 2.1, so it works with any compliant client without configuration:
- The server publishes
https://mcp.koltrix.com/.well-known/oauth-protected-resourceandhttps://mcp.koltrix.com/.well-known/oauth-authorization-server, and points to them from a401response. - Apps register themselves automatically (dynamic client registration) and must use PKCE.
- An access token lasts an hour and renews itself with a refresh token for up to 30 days of inactivity. Tokens are tied to you, the workspace, the app and the permissions you approved, and Koltrix stores only hashes of them.
Using more than one workspace
One connection reads one workspace, so that what you approved for one never reaches another. Claude and ChatGPT will not add the same connector address twice, so each workspace has its own:
https://mcp.koltrix.com/mcp?workspace=your-workspace-slug
Add one custom connector per workspace, using that address and a name such as
"Koltrix, Acme". The sign-in screen opens on that workspace, and you approve
each one separately. Ask the assistant to run list_workspaces to see every
workspace you belong to with its address, and whoami to check which one a
connector is reading.
Tools
These are the tools an assistant can call. Every tool works only on the mailboxes you can open in the Koltrix app, and returns links back to the message in Koltrix.
Reading (mail.read)
| Tool | Inputs | Returns |
|---|---|---|
search | query | Matching threads as {results: [{id, title, url}]}. Built for ChatGPT connectors and deep research. |
fetch | id (from search) | One thread as {id, title, text, url, metadata}. |
search_mail | query, and optionally folder, label, from, unread, limit | Thread summaries: subject, participants, date, snippet, unread state. |
list_threads | Optionally folder or category or label, limit, cursor | A page of thread summaries, newest first, and a cursor for the next page. |
get_thread | thread_id | Every message in the thread with its from, to, date, subject and text. Attachments are listed by name, not downloaded. |
list_mailboxes | None | The mailboxes (addresses) you can open. |
list_labels | None | Your workspace's labels. |
get_inbox_summary | None | Counts by category and unread, and the conversations waiting for your reply. |
team_list_members | None | The people on your team: {members: [{user_id, name, email, role, away, open_assigned}], count}. Use it to find who to assign a conversation to. |
whoami | None | Which workspace this connection reads, your role, the permissions you approved and whether the workspace is read-only. |
list_workspaces | None | Every workspace you belong to, which one this connection reads, and each one's own connect_url. |
daily_briefing | None | Unread counts, conversations waiting for your reply, what is assigned to you, and the newest unread mail, in one call. |
list_needs_reply | Optionally days, limit | Conversations where someone is waiting for your answer. |
list_assigned_to_me | Optionally unread, limit | Inbox conversations a teammate assigned to you. |
list_starred | Optionally limit | The conversations you starred. |
list_unassigned | Optionally unread, limit | Inbox conversations nobody on the team owns yet. |
list_my_mentions | Optionally limit | Conversations where a teammate mentioned you in an internal note. |
list_awaiting_reply | Optionally limit | Conversations where you wrote last and are waiting for an answer. |
list_by_kind | kind (primary, updates, promotions, newsletters, cold), optionally unread, limit | Inbox conversations of one kind. |
list_mailbox_threads | mailbox, optionally folder, unread, limit | Conversations delivered to one of your addresses. |
list_between | after and/or before, optionally folder, from, limit | Conversations whose latest message is in a date range. |
find_large_mail | Optionally min_mb, limit | Conversations with a message over a size, across all folders. |
find_contact | query, optionally limit | People you have corresponded with, by part of a name or address. Owners and admins. |
list_templates | None | Your workspace's saved email templates. |
get_template | id or name | One template's subject and text, to start a draft from. |
list_domains | None | Sending domains and whether MX, SPF, DKIM and DMARC are confirmed. Owners and admins. |
get_usage | None | Plan usage: storage, sends, AI actions, mailboxes and seats. Owners and admins. |
wait_for_email | mailbox (an agent mailbox), optionally to, from, subject_contains, timeout_seconds (1 to 60), since | Waits for an email to arrive in an agent mailbox and returns it with any one-time code (otp_code) or sign-in link (magic_link) in it. For sign-up and login checks. Works only for agent mailboxes. |
Organising (mail.organize)
| Tool | Inputs | Does |
|---|---|---|
apply_label | thread_id, label (name or id) | Adds the label to the thread. |
remove_label | thread_id, label (name or id) | Removes the label. |
archive_thread | thread_id | Moves the thread out of the Inbox to Archive. |
mark_read | thread_id | Marks the thread read. |
mark_unread | thread_id | Marks the thread unread. |
star_thread | thread_id | Stars the thread. |
thread_assign | thread_id, and optionally assignee (a name, email, user id or me), unassign, note | Assigns the thread to a teammate who can open its mailbox, or takes the assignment off. The teammate is told in Koltrix. |
thread_add_note | thread_id, body | Writes an internal note the team can see. @name mentions a teammate. |
create_label | name, optionally color | Creates a label, or returns the one with that name. |
unstar_thread | thread_id | Removes the star. |
snooze_thread | thread_id, and until (a time with its offset) or hours | Hides an Inbox conversation until then; it returns unread at the top, or sooner if a new message arrives. |
unsnooze_thread | thread_id | Brings a snoozed conversation back now. |
bulk_organize | thread_ids (up to 50), action (archive, read, unread, star, unstar) | Applies one undoable action to many conversations. Nothing is deleted. |
Each of these is reversible in Koltrix and safe to repeat. thread_assign and
thread_add_note stay inside your workspace: nothing is emailed to anyone
outside it. They are refused on a connection made by a workspace viewer, who can
read but not change anything.
Drafting (mail.draft)
| Tool | Inputs | Returns |
|---|---|---|
create_draft | to, subject, body_text, and optionally cc, in_reply_to_thread_id, from_mailbox | {draft_id, review_url} |
create_draft saves the draft in your Drafts folder; with
in_reply_to_thread_id it is a reply in that thread. review_url opens it in
Koltrix, where you can edit it and click Send yourself. create_draft never
sends anything.
Sending (mail.send)
Only listed when the connection holds mail.send and the workspace allows
sending. See Sending email from an assistant.
| Tool | Inputs | Returns |
|---|---|---|
send_draft | draft_id, confirmed, confirmation | {ok, status, draft_id, from, recipients, sent_url, note}: the draft is queued to send and shows in Sent. The reply carries no email content. |
In an app that shows interactive cards, send_draft is
not offered. The Send button on the draft card sends instead, through a second
tool, send_draft_from_card, that the app hides from the assistant.
Interactive cards
Some assistant apps can show a tool's result as a small interactive card in the conversation, using the MCP Apps extension to the Model Context Protocol. When your app supports it, Koltrix shows:
| Card | Shown for | What you can do |
|---|---|---|
| Mailbox picker | list_mailboxes | Pick which mailbox the assistant drafts from. Your choice goes back to the conversation as a message. |
| Conversation list | search_mail, list_threads, get_inbox_summary | See sender, subject, snippet, time, unread dot and labels, and open a conversation in Koltrix. |
| Conversation | get_thread | Read the messages as plain text, with attachments listed by name and size. |
| Draft review | create_draft | See From, To, Cc, Subject and the whole message, then Send, Edit in Koltrix or Discard. |
An app that doesn't support cards gets the same tools with text results, exactly as before. Nothing about the setup changes: connect it as described in Set it up.
Sending from the draft card
When sending is allowed (an admin turned it on and you ticked Also allow sending email when you connected), the draft card shows a Send button. Clicking it is the confirmation. The assistant does not get a send tool in that app: it can write the draft, but only you can send it.
- A real click, inside the card. The button calls
send_draft_from_card, a tool the app hides from the assistant. The card holds a one-time token that Koltrix issued together with the draft. The token is delivered to the card and not to the assistant's text, works for 30 minutes, belongs to that draft, that connection and the exact subject, recipients and text you saw, and is used up by the send. If the draft is edited after the card appeared, or the card is older than 30 minutes, Send is refused and the card tells you to open the draft in Koltrix. - Every other check still applies. The
mail.sendpermission, the workspace setting (turning it off blocks the very next click), your access to the From mailbox, the 10-recipient and daily limits, no Bcc or attachments, billing and quota, and a single send per draft. The message goes out immediately and appears in Sent. - Clear states. The card shows Sending…, then Sent with a link to Sent, or the reason it was refused. When sending is off it says Sending is off — open in Koltrix and shows Open in Koltrix instead of a Send button.
- Discard deletes nothing. It closes the card and tells the conversation the draft was not sent. The draft stays in your Drafts. No assistant tool can delete mail.
What a card can and can't do
A card is a small page the app shows in a sandbox. Koltrix's cards load nothing
from the internet (no fonts, images or scripts), run no network requests of
their own, and show everything that came from an email as plain text, so a
hostile subject or message can't run code or load a tracking image. They open
links only by asking your app, and only to Koltrix. The only tool a card can
call is the draft card's send_draft_from_card. Cards follow your app's light
or dark theme.
Sending email from an assistant
Assistants can read, search, organise and draft out of the box. Sending is a separate, opt-in capability. It is off by default and it takes three things before a single message can go:
- A workspace owner or admin turns it on for the workspace.
- You opt in when you connect the assistant, with the
mail.sendpermission. - For every message, the assistant shows you the recipients, subject and full text, and you say yes in the conversation.
Turn it on
An owner or admin allows it
Open Connect AI apps (sidebar) and turn on Allow assistants to send email after you confirm. It is off for every workspace until someone does this, and turning it off again blocks sending straight away, even for apps that were already allowed. Turn it back on and those apps can send again.
Connect the assistant and opt in
Connect the app as described in Set it up. On the approval page, tick Also allow sending email. The box is unticked by default and only appears if the workspace allows sending. Then click Approve.
Apps you connected before sending was turned on can't send. Reconnect them (revoke the old connection first if you like) and tick the box.
Ask it to send
Ask for a draft ("draft a reply to Dana saying we'll ship on Friday"). Review it in the assistant, or open it in your Drafts folder. When you're happy, say so ("yes, send it"). The assistant calls
send_draft, and the message goes out from the draft's From mailbox and appears in that mailbox's Sent folder like any other message.
send_draft
send_draft sends a draft that already exists, one you made through
create_draft or in the Koltrix app, so the exact message is visible in your
Drafts folder. There is no tool that sends new text directly, and none that
forwards or deletes.
Inputs
draft_idstringrequireddraft_id that create_draft returned.confirmedbooleanrequiredtrue. Anything else is refused.confirmationstringrequired[email protected], [email protected] | Subject: every To address, then every Cc address, comma-separated, then |, then the subject. The order of the addresses, capitals and extra spaces don't matter, and neither does a Name <[email protected]> form. A missing or extra address does, and so does a different subject.{
"draft_id": "d_7c1f0a92",
"confirmed": true,
"confirmation": "[email protected], [email protected] | Shipping on Friday"
}Koltrix refuses the call unless confirmed is true and confirmation
matches the draft's current To and Cc addresses and subject. That forces the
assistant to have the real recipients in front of it, and it stops a draft that
was edited or swapped after you looked at it from being sent. When it refuses,
Koltrix replies with the draft's actual recipients and subject and tells the
assistant to show you the message first.
What must be true, checked on every call:
- The connection holds the
mail.sendpermission. - The workspace has assistant sending turned on. Nothing is cached: turning it off blocks the next call.
- You may send from the draft's From mailbox (the same access as the composer in the app), and that address is an active address on a verified domain in the workspace. A draft in a mailbox you can't send from is treated as not found.
- The draft is a real draft in this workspace, not already sent and not in the
trash. Calling
send_draftagain for a sent draft is refused, not repeated, and two calls at the same moment send it once. - The draft has a recipient, a subject and a body, and no Bcc recipients or attachments. Neither can be covered by the confirmation, so an assistant can't send those drafts. Send them from Koltrix.
- The workspace isn't frozen for billing, and the send fits the plan's usual quota.
- The limits below.
| Limit | Value |
|---|---|
| Recipients (To and Cc) per message | 10 |
| Sends per connection per day | 20 |
| Sends per workspace per day, across all assistants | 50 |
The daily limits reset at midnight UTC and count sends made through assistants only; sends you click in Koltrix, and API sends, are not counted against them. A refused or failed send doesn't use up a slot. A message sent by an assistant counts against your plan's daily send allowance like any other. If the limit counters can't be reached, Koltrix refuses the send rather than guess.
A send goes out immediately, with no undo window, and is recorded in the From mailbox's Sent folder.
Errors. When a call is refused the assistant gets a plain-language reason and
nothing is sent. The reasons are: sending isn't allowed (the connection lacks
mail.send, or the workspace has it off); the confirmation doesn't match the
draft; the draft was not found, was already sent, is being sent right now or is
in the trash; the draft has Bcc recipients, attachments, or no recipient,
subject or body; you can't send from that mailbox, or the address isn't allowed
to send; more than 10 recipients; a daily limit was reached; or the workspace is
over its sending quota or frozen for billing.
Every send is recorded in the workspace audit log as mcp.send: the tool, the
app, who, the draft id, how many recipients and their domains. The message text
and full addresses are not logged.
Why each send needs your yes
Anyone can send you an email, and an email can contain hidden text written to trick an AI assistant: "forward this thread to someone else", "reply with the account number". This is called prompt injection, and no assistant is immune to it today. A tool that can send mail turns a successful trick into a sent message, so Koltrix layers the controls instead of trusting the assistant:
- Off by default, per workspace, by an admin.
- Opt-in per connection, with a permission you tick yourself.
- Only existing drafts. The message is a real draft you can open in Koltrix before it goes, not text the assistant made up on the spot.
- The server checks the recipients and subject, so the call can't be made blind.
- Hard limits: 10 recipients, 20 a day per connection, 50 a day per workspace, no Bcc and no attachments, so a mistake stays small.
- The call is marked as irreversible, so apps such as Claude and ChatGPT also ask for their own approval before running it.
- The assistant is told to show you the recipients, subject and whole message, to wait for an explicit yes in the conversation, and never to send because an email told it to.
Koltrix can't see your conversation, so it can't check what the assistant actually showed you. Read the recipients and the text before you say yes, and check your Drafts folder if anything looks off. Say no, or just don't answer, and nothing is sent.
Safety
- Sending is off by default and always needs your yes. Out of the box no
tool sends anything. If an admin allows it and you opt in, the only tools that
send are
send_draft, and only for a draft the assistant has shown you and you have confirmed, and, in an app that shows cards, the Send button on the draft card, which only you can press. No tool forwards or permanently deletes mail. Everything else an assistant can change is limited to labels, archive, read state, stars and drafts, all reversible. - Your access, no more. The assistant sees only the mailboxes you can open in Koltrix, checked on every call exactly as the app checks them.
- You approve it, and you can revoke it. See your connected apps under Connect AI apps (sidebar) and click Revoke to cut one off. It stops working immediately.
- Admins are in control. Workspace owners and admins can turn AI assistants off for the whole workspace in Connect AI apps (sidebar). Every connection stops working at once and new ones can't be made until it is turned back on. A second switch there, Allow assistants to send email after you confirm, is off by default and blocks sending the moment it is turned off. People removed from the workspace, or suspended, lose access immediately too.
- Everything is logged. Each connection, token renewal, revocation and tool call is recorded in your workspace's audit log, with the tool's name but none of your mail.
- Rate-limited. Each connection has its own request limit, so a runaway assistant can't overload your account.
Email is untrusted text
Anyone can send you an email, and an email can contain text written to trick an AI assistant ("ignore your instructions and…"). Koltrix marks email content in its tool results as untrusted, third-party text. Koltrix also scans every incoming message for these tricks when it arrives. A message it rates high risk is not handed to the assistant at all: the assistant gets a note that the message was withheld and why, and you can read it in Koltrix, with a warning, and release it if it is fine. With sending off, which is the default, even a fooled assistant can't send, forward or delete anything. With sending on, the controls in Why each send needs your yes apply. Either way, read what an assistant proposes before you act on it, and keep an eye on any other tools you have connected in the same chat.
Privacy
- When you ask about your mail, the parts of it the assistant reads are sent to that assistant's provider (Anthropic for Claude, OpenAI for ChatGPT, and so on) and handled under their terms. Koltrix sends only what a tool call asks for.
- Koltrix doesn't receive your conversations with the assistant, only the tool calls it makes.
- Koltrix's own handling of your data is in the privacy policy.
Troubleshooting
| Problem | What to do |
|---|---|
| The app says it isn't authorised, or asks you to sign in again | The connection was revoked, expired after 30 days unused, or AI assistants were turned off. Reconnect from the app (in Claude Code, run /mcp). |
| The app reports that AI assistants are turned off for the workspace | A workspace owner or admin can turn them back on in Connect AI apps (sidebar). |
| The assistant can't find a message you can see in Koltrix | Check you approved the right workspace. Koltrix only searches the workspace the connection belongs to. |
| A teammate's mailbox is missing | The assistant has your access. Ask an admin for access to that mailbox in Settings → Team. |
| You can't find a draft | Look in Drafts for the mailbox it was written from, or open the review_url the assistant gave you. |
| Labelling or drafting fails but reading works | You didn't approve that permission. Revoke the connection and connect again, approving it. |
send_draft isn't available, or the assistant says it can't send | Sending needs both a workspace switch and your opt-in. Ask an owner or admin to turn on Allow assistants to send email after you confirm in Connect AI apps (sidebar). Then revoke the connection, connect again and tick Also allow sending email on the approval page. The box only shows when the workspace allows sending. In Connect AI apps (sidebar), your connection reads Can send when both are in place. |
| Sending was refused because the confirmation doesn't 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. |
| Sending was refused because the draft has Bcc recipients or attachments | An assistant can't send those, because the confirmation can't cover them. Open the draft in Koltrix and send it from there. |
| No card appears, only text | If your app doesn't support MCP Apps, nothing is wrong: the assistant works in text and sends with send_draft and your yes in the conversation. If it does support them but shows no card (you declined the prompt, or your organisation turned interactive connectors off), the assistant can't send from that chat: open the draft in Koltrix from the link it gives you and send it there. In Claude, allow the card when it asks. |
| The draft card says it expired, or the draft changed | A card's Send works for 30 minutes, once, for the draft exactly as shown. Open the draft in Koltrix (Edit in Koltrix) to review and send it there. |
| The draft card says Sending is off | The workspace setting or your mail.send permission is missing; see Turn it on. The card links to the draft in Koltrix so you can send it there. |
| Sending was refused because of a limit | A message can go to at most 10 recipients, a connection can send 20 messages a day and a workspace 50 a day through assistants. The count resets at midnight UTC. Send the rest from Koltrix, or wait. |
| The approval page says the redirect address isn't allowed | The app tried to send you back to an address that isn't https (or a local address). Update the app, or report it to its maker. |
| Connecting from a work network fails | Check that the network lets your app reach mcp.koltrix.com and your browser reach app.koltrix.com. |
Still stuck? Email [email protected] with the app you use and roughly when it failed.