Connect an AI assistant to Folio

The MCP server, the access you grant, and the Outbox that approves every send.

Updated 10 minute read

Folio runs a remote MCP server at https://api.folioinbox.com/mcp. Claude, ChatGPT, Cursor, Claude Code, Muse, Grok and Dots can read your mail and calendar through it. You can also let an assistant compose, label, move, archive or trash. Labels, moves, archives and trash apply immediately. Every send is approved by you in Folio: by default in the Outbox, or in Folio's proof card when your client supports MCP Apps; every permanent delete from Trash waits in the Outbox.

What you need

  • A Folio trial or a paid Solo, Studio or Holding plan.
  • An AI client that supports remote MCP servers.
  • A browser for the sign-in step. Cursor and other clients without OAuth use an access key from Connected apps instead.

Connect your assistant

Paste the server URL into the client and sign in. The client asks for read access by default. If you want the assistant to write, tick Compose, Organize or both on the consent screen. You can change that later by reconnecting.

Server URL

https://api.folioinbox.com/mcp

Claude

Claude signs in to Folio itself — no key to copy.

  1. In Claude, open Settings, then Connectors, and choose Add custom connector.

  2. Name it Folio and paste the server URL.

    https://api.folioinbox.com/mcp
  3. Click Connect. Folio asks you to sign in, then shows what Claude can read.

  4. Choose Allow. Folio appears in Claude's tools menu for new chats.

The cards above carry the written steps for the seven clients Folio documents. Any other client that supports remote MCP over HTTP uses the same server URL.

Choose what the assistant can do

Read access is always on. Compose and Organize are optional, and both require read access.

Read

Always on

Search and read mail, threads, labels and folder counts; read calendar events and free time.

“Summarize this thread.” “What is on my calendar on Thursday?”

Compose

Optional

Draft a new message, reply, reply-all or forward; change or delete a draft; attach files already in the mailbox; ask you to send.

“Draft a reply saying the signed letter goes out on the 14th.”

Organize

Optional

Label, move, archive or trash a message; ask you to permanently delete one from Trash.

“Move every invoice from this sender to Archive.”

An existing read-only connection stays read-only until you reconnect it. Access keys are read-only; use OAuth to grant Compose or Organize.

How approval works

  1. A send starts with a draft and a request.

    The assistant creates a draft and a request, and reports that the request is waiting — not that the mail was sent.

  2. You choose where approval happens.

    By default the request lands in the Outbox, where the row names the connection, recipients, subject and body, and you can edit every field. If you set a card-capable connection to Approve in the assistant, Folio shows its proof card in the conversation. The proof names the connection and shows the From and To addresses, Cc and Bcc counts, subject, body excerpt and attachment names. A native client does not get a card; its request waits in the Outbox with a link. There is no Always allow.

  3. You decide.

    Send delivers the message. Reject leaves the draft in Drafts, or the message in Trash for a delete request. A permanent delete works the same way: the message must be in Trash, and the Outbox shows it before you approve.

No MCP token can approve a request. The Outbox needs your Folio session. In-chat approval is Folio's own card; the server verifies the card token and content digest. A native client always uses the Outbox. The model's message and the client's permission settings are never the gate.

What the assistant can do

Your client lists the tools for the access you granted. The names and descriptions are English.

Read tools9
search_messages
Search by sender, subject, preview text or receiving address, newest first.
get_message
One message: headers, plain-text body and attachment names, types and sizes.
get_thread
Every message in a conversation, oldest first.
list_businesses
The domains on the account and whether each one is verified.
list_labels
Labels with message counts.
folder_counts
How many messages are in each folder, without Spam.
list_events
Calendar events between two dates, including subscribed calendars.
get_event
One calendar event by id.
get_availability
Busy intervals between two dates, without titles or attendees.
Compose tools10
send_message
Compose a new message and create a send request.
reply_to_message
Reply or reply-all with the original thread headers.
forward_message
Forward a message, with its attachments when you choose.
save_draft
Create a draft in Drafts.
list_drafts
List drafts, newest first.
get_draft
Read one draft.
update_draft
Replace a draft's fields. A pending draft is locked.
delete_draft
Delete a draft. A pending draft is locked.
send_draft
Create a send request for an existing draft.
list_identities
The verified addresses you can send from.
Organize tools5
label_message
Add or remove labels on one message.
move_message
Move one message to Inbox, Archive or Trash.
archive_message
Move one message to Archive.
trash_message
Move one message to Trash.
delete_message
Ask to permanently delete a message that is already in Trash.
Status tools1
get_request
The status of a send or delete request: pending, sent, rejected, expired or failed.

Safety and limits

  • By default, every send waits in the Outbox. If you choose Approve in the assistant on a card-capable connection, Folio's proof card is the send gate. A native client always waits in the Outbox. Permanent delete from Trash always waits in the Outbox. Labels, moves, archive and trash apply immediately.
  • Spam and attachment contents are hidden. The assistant sees an attachment's name, type and size, not the file.
  • Attachments come only from files already in your mailbox. There is no upload from the client and no fetch from a URL.
  • One message per write call. There is no bulk, scheduled or campaign sending.
  • Each connection can make 120 tool calls a minute. Each account can make 5,000 a day.
  • An in-chat card expires after 24 hours. A pending Outbox request expires after 14 days. Decided requests stay in the Outbox for 30 days. Connections shows 30 days of activity, and the audit log keeps 90 days.
  • Revoke a connection in Connected apps. Access stops within five seconds, and its pending requests are rejected.
  • Mail is untrusted input. The server wraps message text in an untrusted-content envelope, and the Outbox is the human check for sends and permanent deletes.

Example prompts

Find the last three messages from Ledgerline and summarize the open questions.
Draft a reply to Sarah saying the signed letter goes out on the 14th. Put it in the Outbox.
Move every message from newsletter@example.com to Archive.
Forward the invoice thread to my accountant and keep the PDF attached.
What does my Thursday look like?
Label every message from the London office with Clients and archive it.

Troubleshooting

These are the errors customers hit most often. If none of them matches, send the client name and the tool call to support.

The client says the server did not respond.

Check the URL. It is https://api.folioinbox.com/mcp. Remove the connector and add it again, then sign in. A paused workspace returns a temporary error; try again later.

The assistant can read but not write.

Open Connected apps, reconnect the assistant and grant Compose or Organize. An older read-only connection keeps its read scopes until you do. Access keys cannot write.

I do not see the Outbox.

The Outbox is at /app/outbox and in the sidebar. If it is empty, no assistant has asked to send or delete anything. If Connected apps says assistant access is paused, try again later.

A send failed.

The request stays in the Outbox with the error. A plan or team send cap, a suppressed recipient or an invalid From address can block it. Fix the cause and press Send again. A rejected request keeps the draft in Drafts.

The assistant says a tool is not enabled.

The account may be outside its trial or paid plan, or the connection may lack the scope for that tool. Check Billing and Connected apps. A lapsed plan pauses every connection and resumes when the plan is active.

How do I disconnect an assistant?

Open Connected apps, find the connection and press Revoke. Its next call fails within five seconds, and any pending request is rejected.

Connect now

Add an assistant from Connected apps, or start a trial to connect one.

Back to the Manual