Set-up documentation

LibreChat in 4 steps

1. Create an access token

   In the control panel, for the mailbox this LibreChat instance should reach.

2. Add the server to librechat.yaml

   Under mcpServers, with type streamable-http and a url of https://mcp.mailbox-mcp.com/db/mcp/YOUR-MAILBOX-KEY.

3. Put the token in an environment variable

   Reference it in the headers block with the dollar-brace syntax so the credential is not in the file.

4. Restart and check the tools appear

   Start a conversation and ask for something only the mailbox can answer.

One token in librechat.yaml: everybody as the owner

The simple arrangement: one shared mailbox, one token. Everybody who uses this LibreChat instance reaches the same mail as the owner, and every call is recorded under the owner's name.

Every person can do whatever the token can, which is whatever the mailbox's limit allows. The token carries that limit as its permission level, set on the mailbox's Connector tab: Send and delete with the calendar unless the owner lowers it.

It suits a team inbox worked by people you would trust with its password, and is wrong for anything else. The section after this one is the arrangement for everybody else.

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.

A connection each, with Team Access

One entry cannot give a team a mailbox each, whatever it puts in a headers block: this server reads no per-user header, so a placeholder such as {{LIBRECHAT_USER_ID}} sent alongside the owner's token hands every user the owner's connection under a different label. This page said otherwise until 13 September 2026, and the snippet it carried has been withdrawn.

What gives each person their own connection is Team Access. The owner invites each person by email address with a permission level (Read only, Draft and file or Send and delete), a daily cap and the mailboxes they may reach. Each accepted person gets a connector URL of their own for each mailbox.

A shared connector is reached by that person signing in, never by a token: there is no access token for a mailbox shared with you. So in LibreChat it is one entry per person, carrying their own URL and no headers block. Each person authenticates with their own login the first time they use it.

LibreChat's own documentation covers that half. It supports OAuth for MCP servers, gives each user an isolated connection, and prompts each user to authenticate with their own login on first use. It also registers itself automatically where the server supports that, which this one does.

mcpServers:
  mail-priya:
    type: streamable-http
    url: https://mcp.mailbox-mcp.com/db/mcp/PRIYAS-CONNECTOR-KEY
    timeout: 30000
    serverInstructions: true
  mail-tom:
    type: streamable-http
    url: https://mcp.mailbox-mcp.com/db/mcp/TOMS-CONNECTOR-KEY
    timeout: 30000
    serverInstructions: true

Each person's level is fixed by their share rather than by the entry, and never acts above the mailbox's own limit. A person invited at Draft and file is shown only that level's tools, and a call outside it is refused before the meter, whatever the YAML says.

The owner changes a level, pauses or removes a person in the control panel, and it lands on that person's next call. Nothing in librechat.yaml has to change.

Every call each person makes sits under their own name in the owner's activity record. The Team Access guide walks an invitation, a claim and an approval through end to end.

The 2 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.

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

Where to go next

Team Access 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.

Read 13 September 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.