[Enhancement]: Custom headers for user-created MCP servers

[francoisauclair911]

What features would you like to see added?

Custom headers for user-created MCP servers, configurable from the MCP server dialog.

Today a server created in the UI can authenticate with a single header only. The dialog offers None, one API key header (Bearer, Basic or one custom header name), OAuth, or OBO. The client form never sends headers, even though MCPServerUserInputSchema already accepts them.

Some MCP servers need several headers. A Mautic MCP server, for example, expects:

• X-Mautic-Url
• X-Mautic-Client-Id
• X-Mautic-Client-Secret

Other common cases are a client ID plus a client secret, or a tenant URL header next to a secret. None of these can be set up from the UI. Admins can configure them in librechat.yaml with headers and customUserVars, but that requires a config change and a restart for each server, and is not available to regular users creating their own servers.

Proposed behavior:

• A "Custom headers" section in the MCP server dialog (HTTP transports only): one row per header with a name input, a masked value input and a remove button, plus an "Add header" button.
• Header values are encrypted at rest with encryptV2 for DB-backed servers (stored as enc:v2:<iv:ciphertext>), decrypted on read before placeholder resolution and connection creation.
• Header values are never returned to the client. Editors receive only headerNames.
• On edit, a blank value keeps the stored one ("Leave blank to keep existing"), the same as the OAuth client secret.
• Keeping a stored value is refused when the same update changes url, type or proxy, so a stored secret cannot be redirected to a new endpoint without re-entering it. This mirrors the existing MCP_API_KEY_REENTRY_REQUIRED rule with a new MCP_HEADERS_REENTRY_REQUIRED (400).
• Existing placeholder stripping ({{LIBRECHAT_OPENID_*}}, {{LIBRECHAT_USER_*}}, {{LIBRECHAT_GRAPH_*}}, {{LIBRECHAT_BODY_*}}, ${VAR}) is unchanged and runs before encryption.
• No new permission: anyone who can already create or edit an MCP server can set headers.

More details

Areas affected:

• Client: client/src/components/SidePanel/MCPBuilder/MCPServerDialog/ (new sections/HeadersSection.tsx, hooks/useMCPServerForm.ts, MCPServerForm.tsx).
• Backend: packages/api/src/mcp/registry/db/ServerConfigsDB.ts, registry/MCPServersRegistry.ts, a new registry/headers.ts (encrypt/decrypt, keep-on-blank merge, re-entry guard), utils.ts (redactServerSecrets returns headerNames), errors.ts.
• API: the MCP server update controller, so the OBO lockdown compares resolved values and a kept header is not treated as a change.

Compatibility:

• Existing plaintext header rows keep working and are encrypted on their next save. No migration.
• A value that fails to decrypt is dropped with a warning instead of being sent upstream as ciphertext, matching the existing handling for client_secret and apiKey.key.
• During a mixed-version rollout, an older replica would send enc:v2: values literally, so a server saved by the new code may fail to authenticate on old replicas until all replicas are updated.
• Responses gain an optional headerNames: string[], for editors only.

Alternatives considered:

• librechat.yaml with headers and customUserVars: works for admin-defined servers, but not for servers users create themselves, and needs a config change per server.
• The single custom API key header: covers one header only.

Related: #6115 asks for multiple auth headers for Agent Tools (Actions). This request covers the same need for user-created MCP servers.

An implementation is open in #17827. I would like to take this and be assigned, per CONTRIBUTING.md. Happy to adjust the scope or approach based on maintainer feedback before review.

Which components are impacted by your request?

UI, Endpoints

Pictures

Screenshots of the create and edit dialogs will be added to #17827.

Code of Conduct

• I agree to follow this project's Code of Conduct

[redbotster]

the multi-header gap is a real gap. the workaround until the UI ships is to add them in librechat.yaml under headers and customUserVars, which you already know, but for user-owned servers that's a pain since it requires admin access and a restart.

the proposed UX looks right to me. one thing worth calling out during review: make sure header values go through the same encryption path as oauth secrets and are stripped before any client-side response serializes them, since it's easy to accidentally leak them in a "get server config" endpoint. the headerNames-only-on-edit pattern you described is exactly the right approach there.

(disclosure: i work on 1Claw, which solves a related but different problem around keeping secrets out of model context entirely, but that's not what this issue is about.)