Mailbox MCP
Connect a mailbox
All documentation
Connect a mailbox Client not listed? Ask us
On this page

Set-up documentation

Connect your mailbox to LibreChat

LibreChat has two placeholder syntaxes and they are not interchangeable. The per-user one gives every member of a team their own mailbox behind one file.

Time About 5 minutes
Where librechat.yaml, or the UI if you prefer the database
It needs URL and an access token
Top-level key mcpServers
URL key url

One mailbox for everyone

The simple arrangement: one shared mailbox, one token, everybody who uses this LibreChat instance reaches the same mail. Suitable for a team inbox and wrong for personal mail, for the obvious reason.

librechat.yaml Shared mailbox 
mcpServers:
  work-mail:
    type: streamable-http
    url: https://mcp.mailbox-mcp.com/db/mcp/YOUR-MAILBOX-KEY
    headers:
      Authorization: 'Bearer ${MAILBOX_MCP_TOKEN}'
    timeout: 30000
    serverInstructions: true

streamable-http with a hyphen. Cline spells the same transport streamableHttp and Goose spells it streamable_http, so a snippet from either will not work here.

The token is referenced rather than written: ${MAILBOX_MCP_TOKEN} reads a server-side environment variable, so the credential lives in your environment and the YAML can be committed. timeout is in milliseconds here, unlike Goose, where it is seconds.

Or a mailbox each

This is the part worth reading, and it is a thing no other client in this section can do. LibreChat can substitute a value that differs per signed-in user into the headers it sends, which means one entry in one file can give every member of a team their own mailbox.

librechat.yaml A mailbox per user 
mcpServers:
  my-mail:
    type: streamable-http
    url: https://mcp.mailbox-mcp.com/db/mcp/YOUR-MAILBOX-KEY
    headers:
      X-User-ID: '{{LIBRECHAT_USER_ID}}'
      Authorization: 'Bearer ${MAILBOX_MCP_TOKEN}'
    timeout: 30000

The other user placeholders LibreChat documents are {{LIBRECHAT_USER_EMAIL}}, {{LIBRECHAT_USER_ROLE}} and {{LIBRECHAT_USER_USERNAME}}. Which of them is useful depends on how you have arranged your mailboxes with us; if you are running a team on this, write to us and we will work out the mapping with you rather than have you guess it.

The two placeholder syntaxes

They look similar and they are not interchangeable. Getting them the wrong way round produces a header containing the literal text of the placeholder, which fails as an authorisation and does not say why.

Syntax Resolved from Use it for
{{LIBRECHAT_USER_ID}} The signed-in user, per request Anything that should differ per person
${API_TOKEN} A server-side environment variable A credential that must not be in the file

Servers added in the UI are not in the file

LibreChat lets you add an MCP server through its interface as well as through YAML, and those are stored in the database rather than written back to librechat.yaml. It is a reasonable design and it catches people out during an upgrade or a migration: a server that works and is nowhere in your configuration is a server nobody will remember to carry across.

If you are running this in anything you would call production, put it in the file.

Check that it worked

Try this first

What has arrived in the shared inbox today that nobody has replied to yet?

A team question rather than a personal one, which is what this arrangement is for. Nothing is marked read by asking, so a triage pass does not disturb whoever normally works that inbox.

Pricing is per mailbox per year, so a team sharing one inbox is one mailbox and a team with one each is one per person. The free tier is 5 calls a day on any of them.

Connect a mailbox Sign in

Where to go next

Pricing is the page that matters for a team decision, and security answers what we hold and for how long, which is the question somebody will ask you before you roll this out to anyone else.

What we could not confirm
  • The absolute path of librechat.yaml. It is not on the page read.

Read 30 August 2026 Every value on this page came off LibreChat documentation: MCP on that day. If it has changed since, tell us and we will read it again.

By Mark McNeece, Founder Published Last reviewed Editorial standards