mirror of
https://github.com/danny-avila/LibreChat.git
synced 2026-11-18 14:08:21 +00:00
Profile writes are judged in the tenant partition the profile merges in. For a role, or a
caller inside a tenant, that is the caller's partition. For a group or user profile written by
an admin without a tenant, it is the stored document's tenant: PUT, PATCH and POST …/changes
validate on librechat.yaml as that tenant resolves it with that tenant's __base__ over it, use
the same Base for the recheck after commit and for key binding, tombstones and field deletes
judge re-entry on that tenant's librechat.yaml, and every route reports `ignored` over that
tenant's Base. Each attempt reads the document in that partition only, and a document that
moved partition while the write ran answers 409 CONFIG_VERSION_CONFLICT. The config store's
partition rules are unchanged; another tenant's Base is read in that tenant's context.
Deleting a group, role or user clears the config caches when it removes or restores the
principal's profile (`invalidatingConfigStore`), awaited before the response and broadcast with
Redis as config writes do; a call that rejects clears too, since it may have committed.
POST …/changes lets `unset` remove any part of a top-level section configSchema does not
define; the section's own `unknown_section` issue is no longer blamed on the removal, and every
other op there still answers 400 UNKNOWN_SECTION.
POST /api/admin/config/reload, for an admin without a tenant holding broad manage:configs (a
tenant admin gets 403, since the reload reaches every tenant), runs the config cache clear without
a write, loads librechat.yaml again on the answering instance, and once it loaded publishes the
clear over Redis so every other instance loads the file on its next read. It uses
ConfigCacheInvalidation.reload, which reports the clear, the load and the publish instead of only
logging a failure (writes keep `invalidate`, which leaves the load to the next read). It answers
200 `{ success: true, broadcast }`, `broadcast` false without Redis; 422 CONFIG_RELOAD_INVALID
with each schema issue's location when the loader refuses the file, keeping the last good config
and publishing nothing; 500 CONFIG_RELOAD_FAILED when a clear fails or the config cannot be built
from the file; and 503 CONFIG_RELOAD_BROADCAST_FAILED when this instance reloaded but the publish
failed, since an instance that misses the broadcast keeps its cached librechat.yaml, which never
expires. Every reload that runs is audited as `config.reloaded`, a failed one with outcome
`failure` and its code. The meta reports `features.reloadRoute`. Writes still reload the file.
The e2e content-filter helper uses the route instead of a sentinel profile.
docs/mcp-overrides.md describes the current timing: the awaited clear, the Redis broadcast, what
still waits for a TTL, that a process the clear misses keeps its old librechat.yaml, and hiding
as an access boundary at checkout.
163 lines
10 KiB
Markdown
163 lines
10 KiB
Markdown
# MCP servers in config profiles
|
|
|
|
Config profiles (the `__base__` document and role, group and user documents written through
|
|
`/api/admin/config`) merge over `librechat.yaml`. For MCP servers, the merge can also take away
|
|
what `librechat.yaml` declared: a profile can hide a whole server, remove a field, or remove one key
|
|
of a record map. All three are tombstones, written and removed with the same two calls:
|
|
|
|
| Method | Path | Body / query |
|
|
| ------ | ---------------------------------------------------------------- | --------------------------------- |
|
|
| POST | `/api/admin/config/:principalType/:principalId/fields/tombstone` | `{ "fieldPath": "mcpServers.…" }` |
|
|
| DELETE | `/api/admin/config/:principalType/:principalId/fields` | `?fieldPath=mcpServers.…` |
|
|
|
|
Profiles merge in a fixed order, the last winning: `__base__` first whatever its priority, then
|
|
ascending priority, then role, group and user on equal priority. A "higher" profile below is one
|
|
that merges later.
|
|
|
|
`librechat.yaml` stays authoritative for which servers exist. A profile cannot delete or rename a
|
|
`librechat.yaml` server; it can only hide it from the principals the profile applies to.
|
|
|
|
## Hiding a server
|
|
|
|
`fieldPath: "mcpServers.<name>"` hides the server for every principal the profile applies to. A
|
|
hidden server is an access boundary, not only a catalog filter. For those principals:
|
|
|
|
- it is missing from `GET /api/mcp/servers`, MCP tool lists, connection status and the agent
|
|
builder;
|
|
- registry lookups by name return nothing, so the reinitialize, auth-value, OAuth initiation and
|
|
OAuth callback routes answer as they do for an unknown server;
|
|
- an OAuth sign-in started before the hide goes no further: initiation does not redirect to the
|
|
authorization server, and the callback does not exchange the code;
|
|
- checkout refuses it, including a configuration resolved before the hide took effect, so a
|
|
persisted agent, a scheduled run or an MCP App that references the server cannot connect to it;
|
|
- tools from it are dropped when an agent loads, and its `serverInstructions` are left out of the
|
|
model's context, even when a model spec pins the server;
|
|
- saving an agent drops tools from it that the save adds. Tools the agent already had stay stored,
|
|
because a collaborator who edits the agent may not see every server it uses, but they cannot
|
|
load or run for these principals.
|
|
|
|
Two broader tombstones hide more than one server or reach more principals:
|
|
|
|
- `fieldPath: "mcpServers"` removes the whole section, so it hides every server a profile can hide
|
|
(all but the ones listed below) for the profile's principals.
|
|
- A tombstone in the `__base__` profile applies to every principal, administrators included.
|
|
`__base__` merges first, so every other profile is higher than it: a profile that writes fields
|
|
of a server `__base__` hides brings it back for that profile's principals, as described below.
|
|
|
|
Deleting the tombstone shows the server again. A higher profile that writes some fields of
|
|
a server a lower profile hides also brings it back for its own principals, but not with those
|
|
fields. The merge keeps only what the higher profile wrote, which is not a usable server
|
|
definition, so those principals get the server as `librechat.yaml` defines it, and the incomplete
|
|
entry stays behind as a failed configuration that is inspected again every 5 minutes. To bring the
|
|
server back with changes, write the complete definition (`type`, `url` and every other field the
|
|
server needs) in the higher profile. To bring it back unchanged, delete the lower profile's
|
|
tombstone.
|
|
|
|
Some servers are never hidden:
|
|
|
|
- Process-backed (`stdio`) servers. The merge ignores tombstones under them, because their process
|
|
is shared by every user.
|
|
- Agent Plugins servers, which are not part of `librechat.yaml`.
|
|
- A user's own servers.
|
|
|
|
The decision comes from the principal's merged configuration (user, role and group memberships, in
|
|
merge order). When that configuration cannot be read, every server a profile could hide is
|
|
withheld instead of falling back to `librechat.yaml`.
|
|
|
|
### When a change takes effect
|
|
|
|
The decision is derived from the principal's merged configuration. Each process caches the merged
|
|
configuration per user and role for 60 seconds, and the decision for `MCP_REGISTRY_CACHE_TTL`
|
|
(5 seconds by default), including a decision made while the configuration could not be read.
|
|
|
|
Every admin config write that changes a profile clears these caches before it answers: the merged
|
|
configurations (of the admin's tenant, or of every tenant for an admin without one), the hiding
|
|
decisions and the cached `librechat.yaml`. Deleting a group or role through the admin API clears
|
|
them the same way when it removes (or, if the deletion cannot finish, restores) that principal's
|
|
profile, and so does `POST /api/admin/config/reload`, which changes no profile. A merge that
|
|
read the configuration before the clear is never cached after it, so a request racing the write
|
|
cannot put the old decision back. Hiding or unhiding a server therefore takes effect:
|
|
|
|
- in the process that handled the write, for every request after the response, the admin's next
|
|
read included;
|
|
- with Redis (`USE_REDIS`), in every other process as soon as it receives the clear the write
|
|
publishes before it answers. A process whose subscription is down, for example while Redis is
|
|
unreachable, catches up when its caches expire, within 60 seconds plus `MCP_REGISTRY_CACHE_TTL`
|
|
(65 seconds by default);
|
|
- without Redis, in every other process only when its caches expire, within the same 65 seconds.
|
|
|
|
The cached `librechat.yaml` does not expire. A process the clear does not reach (every other process
|
|
without Redis; with Redis, one whose subscription is down, or all of them when the publish fails)
|
|
keeps its old `librechat.yaml` until a later clear reaches it or it restarts, so a server added to
|
|
or removed from the file does not change there in the meantime.
|
|
|
|
`POST /api/admin/config/reload` is for an admin without a tenant, since it reaches every tenant.
|
|
The answering process loads `librechat.yaml` again before it answers, and publishes the clear only
|
|
once the file loaded. It answers 422 `CONFIG_RELOAD_INVALID`, with the location of each schema
|
|
issue, when the file fails to load: that process keeps its last good configuration and the others
|
|
are not told, so nothing changes until the file is fixed and reloaded. It answers 503
|
|
`CONFIG_RELOAD_BROADCAST_FAILED` when the answering process reloaded but the clear could not be
|
|
published (for example while Redis is unreachable), so the reload can be retried, and
|
|
`{ "success": true, "broadcast": false }` without Redis, when only the answering process reloaded.
|
|
It cannot tell whether a subscribed process missed a clear that was published, or whether another
|
|
process, which loads the file on its next read, failed to load it.
|
|
|
|
When `APP_CONFIG` is removed from `FORCED_IN_MEMORY_CACHE_NAMESPACES`, merged configurations live in
|
|
Redis, where they are not listed and cleared. They then expire after 60 seconds in every process,
|
|
the writing one included; the hiding decisions are still cleared.
|
|
|
|
Hiding is enforced on every use, not only in what the catalog lists, so a server stays unusable
|
|
once the principal's decision hides it: a stale catalog entry or a persisted agent that still names
|
|
it fails at checkout, as described above.
|
|
|
|
Group membership is not part of either cache key, and adding a user to a group or removing one from
|
|
it clears nothing, so a membership change takes up to 65 seconds to change what the user can see.
|
|
|
|
Hiding does not stop the shared connections started at boot for other principals, and it keeps the
|
|
principal's stored OAuth tokens. Revoking those tokens (uninstalling the server or deleting the
|
|
account) still reaches the server. The name stays reserved: a user cannot create a server with the
|
|
name of a hidden `librechat.yaml` server.
|
|
|
|
### After upgrading
|
|
|
|
Profiles could store these tombstones before they had any effect on `librechat.yaml` servers. They
|
|
take effect after the upgrade: `mcpServers` and `mcpServers.<name>` tombstones hide servers, and
|
|
`mcpServers.<name>.<field>` tombstones remove the field. At startup, each process logs a warning
|
|
that lists the stored tombstones of these kinds, by principal (and by tenant, for profiles that
|
|
belong to one), so you can review them.
|
|
|
|
## Removing inherited values
|
|
|
|
`fieldPath: "mcpServers.<name>.<field>"` removes a field `librechat.yaml` set, such as `timeout`,
|
|
`headers` or `customUserVars`, for the principals the profile applies to.
|
|
|
|
`fieldPath: "mcpServers.<name>.<record>.<key>"` removes one key from a record map and keeps its
|
|
siblings. This works for `headers`, `oauth_headers`, `requestHeaders` and `customUserVars`:
|
|
|
|
```json
|
|
{ "fieldPath": "mcpServers.github.headers.Authorization" }
|
|
```
|
|
|
|
These tombstones behave as follows:
|
|
|
|
- Writing a sibling key in the same profile keeps the tombstone. Writing the same key clears it.
|
|
- `DELETE …/fields?fieldPath=<same path>` removes that tombstone and restores the inherited key.
|
|
- `DELETE …/fields?fieldPath=mcpServers.<name>.headers` resets the whole record: it clears the key
|
|
tombstones under it as well as the keys the profile wrote.
|
|
- A higher profile can supply the key again.
|
|
- Fields of a process-backed server, including `env`, cannot be removed.
|
|
- A record key that contains `.` cannot be addressed with a dotted `fieldPath`.
|
|
|
|
The server without the removed value is inspected as its own configuration. If that inspection
|
|
fails, for example because the server rejects requests without the removed `Authorization` header,
|
|
those principals get it as a failed configuration, inspected again every 5 minutes. They never fall
|
|
back to the `librechat.yaml` definition, which still has the value. A change that removes nothing
|
|
(such as a new `timeout`) still falls back to `librechat.yaml` while its inspection fails.
|
|
|
|
Removing `oauth_headers` keys, or the whole field, also covers OAuth sign-in. A sign-in sends the
|
|
headers the principal's config had when it started, and none when that config had none left, never
|
|
the `librechat.yaml` headers. A sign-in started before the removal goes no further, because the
|
|
server's definition changed; signing in again uses the remaining headers.
|
|
|
|
Removing a `customUserVars` key that a header still references as `{{VAR}}` leaves that placeholder
|
|
unresolved for those principals; remove or change the header too.
|