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.

Server URL

https://mcp.koltrix.com/mcp

This 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 Koltrix and paste https://mcp.koltrix.com/mcp as 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/mcp

Then 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, paste https://mcp.koltrix.com/mcp and 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):

mcp.json

{
  "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.

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. Not send them.

Apps ask for all three by default, and the approval page lists each one.

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-resource and https://mcp.koltrix.com/.well-known/oauth-authorization-server, and points to them from a 401 response.
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.

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.

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.

Each of these is reversible in Koltrix and safe to repeat.

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. The assistant can't send it.

Safety

Nothing is sent without you. No tool sends, forwards or permanently deletes mail. The tools that change things are 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 Settings → AI assistants 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 Settings → AI assistants. Every connection stops working at once and new ones can't be made until it is turned back on. 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, and the tool set is built so that even a fooled assistant can't send, forward or delete anything. Still, 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 Settings → AI assistants.
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.
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.

AI assistants (MCP)

Server URL#

Set it up#

Claude (claude.ai)#

Claude Desktop#

Claude Code#

ChatGPT#

Cursor#

Other apps#

Signing in and permissions#

Tools#

Reading (mail.read)#

Organising (mail.organize)#

Drafting (mail.draft)#

Safety#

Email is untrusted text#

Privacy#

Troubleshooting#

Server URL

Set it up

Claude (claude.ai)

Claude Desktop

Claude Code

ChatGPT

Cursor

Other apps

Signing in and permissions

Tools

Reading (`mail.read`)

Organising (`mail.organize`)

Drafting (`mail.draft`)

Safety

Email is untrusted text

Privacy

Troubleshooting