🔌 feat: Add Agent Plugins (Experimental) (#14704)

* 🔌 feat: Add Agent Plugins v1.0.0 Support

Implements the Agent Plugins 1.0.0 specification so LibreChat can load
portable plugin packages: a `plugin.json` manifest, `skills/` holding Agent
Skills, `mcp.json` describing MCP servers, and reverse-domain extension
directories.

- Validate the closed `plugin.json` schema, selecting rules from `$schema`
  without retrieving it. Unknown top-level fields and a non-object
  `extensions` field are reported and ignored; every other violation rejects
  the plugin.
- Enforce plugin-root containment through realpath, including for paths whose
  leaf does not exist, and apply the narrowest failure boundary per component.
- Map `mcp.json` onto LibreChat MCP options across stdio, Streamable HTTP, and
  legacy HTTP+SSE, bypassing the config loader's `${VAR}` process-env
  expansion so plugin values never resolve against the server environment.
- Expand only `${PLUGIN_ROOT}` and `${PLUGIN_DATA}`, once and non-recursively,
  in `args`, `env` values, and `cwd`; supply both variables to the subprocess
  after configured `env`, and reject entries that declare them.
- Discover skills from the immediate children of `skills/` only, reusing the
  deployment skill loader so plugin skills are ordinary deployment skills with
  a distinct id namespace.
- Read LibreChat's `ai.librechat` extension directory and hand
  `hooks/hooks.json` to the Claude hook compatibility layer.
- Load operator-installed plugins from `DEPLOYMENT_PLUGINS_DIR` at startup,
  merging their skills into the deployment skill registry and their MCP
  servers into the app config. Plugins never displace a configured server or
  deployment skill.
- Add `cwd` to the stdio MCP transport, which the specification requires and
  LibreChat did not previously support.

Component failures stay isolated: a malformed `mcp.json`, an invalid skill, or
a bad hooks document never prevents the rest of a plugin from loading.

* 🔒 fix: Contain Agent Plugins config at the runtime boundary

Review of #14704 surfaced that every real finding sat where the loader's
output crosses into LibreChat's existing runtime, not in the specification
logic. The loader deliberately left plugin placeholders literal, but
downstream layers re-processed the same fields and undid it.

- Mark plugin MCP configuration with `source: 'plugin'` and return it verbatim
  from `processMCPEnv`. Without this a remote plugin could declare
  `Authorization: Bearer ${OPENAI_API_KEY}` and receive host credentials at its
  own origin. The gate reads the configuration rather than a caller-supplied
  flag, so no future call site can reintroduce the leak by omitting it.
- Skip `preProcessGraphTokens` for plugin configuration as well; it resolves
  placeholders into headers, url, and args on the same path.
- Reject plugin server names that change under `normalizeServerName`. Tool keys
  embed the normalized name while request-time resolution uses the raw name, so
  an unstable name published tools that nothing could resolve.
- Reject `__proto__`, `constructor`, and `prototype` as server names, and merge
  plugin servers with `Object.defineProperty` and an own-property conflict
  check, so a package cannot reach a prototype setter or collide with an
  inherited member.
- Enforce manifest-name uniqueness before components are accepted; two packages
  sharing a name would share one `PLUGIN_DATA` directory.
- Isolate a failed data-directory creation to the single plugin instead of
  rejecting the whole scan.
- Prefix rejected-plugin diagnostics with the directory, which is the only
  identifier a package without a valid manifest has.
- Type extension namespace contents as JSON rather than `unknown`, and correct
  the header field-value comment to name obs-text.

Verified end to end from the built package: a plugin declaring an environment
placeholder in a header reaches the transport with the placeholder intact while
operator-authored configuration still resolves normally.

* 🔇 fix: Report Agent Plugin hooks that will not run

The loader reads `ai.librechat/hooks/hooks.json`, but nothing registers the
resulting plan, and startup supplies no hook capabilities. A package declaring
hooks was therefore accepted in silence, leaving an operator to believe the
hooks ran.

Detect the document when no capabilities are registered and report it as
unsupported, so the limitation is visible in startup diagnostics rather than
inferred from behavior that never happens.

* 🧯 test: Restore MCP startup test mocks

Carries the two mock additions from #14711 so this branch can prove itself
green. `initializeMCPs` now calls `syncStaticTools`, which the server startup
specs do not stub, so they fail on every branch that has not picked this up.
Drops out of the rebase once #14711 lands.

Co-authored-by: Danny Avila <danny@librechat.ai>

api/server/index.js

@@ -27,6 +27,8 @@ const {
   agentStartupTelemetryMiddleware,
   initializeFileStorage,
   initializeDeploymentSkills,
+  initializeDeploymentPlugins,
+  getDeploymentPluginSkills,
   loadToolApprovalHooks,
   maybeInjectQueryDevtoolsBootstrap,
   preAuthTenantMiddleware,
@@ -152,7 +154,12 @@ const startServer = async () => {
   });
   const appConfig = await getAppConfig({ baseOnly: true });
   initializeFileStorage(appConfig);
-  await initializeDeploymentSkills({ projectRoot: path.resolve(__dirname, '../..') });
+  const projectRoot = path.resolve(__dirname, '../..');
+  await initializeDeploymentPlugins({ projectRoot });
+  await initializeDeploymentSkills({
+    projectRoot,
+    additionalSkills: getDeploymentPluginSkills(),
+  });
   initializeGitHubSkillSync(appConfig);
   startExpiredFileSweep({ appConfig, loadAppConfig: getAppConfig });
   // Register any programmatic tool-approval policy hooks declared in

api/server/services/initializeMCPs.js

@@ -3,6 +3,7 @@ const { logger } = require('@librechat/data-schemas');
 const {
   registerShutdownTask,
   setMCPToolsChangedHandler,
+  getDeploymentPluginMcpServers,
   setMCPToolsChangedGenerationHandler,
   setMCPToolsChangedGenerationRenewalHandler,
   setMCPToolsChangedRevisionHandler,
@@ -61,12 +62,43 @@ async function refreshChangedServerTools({
   );
 }
 
+/**
+ * Merges Agent Plugins MCP servers under the configured servers. A plugin never
+ * displaces a server the operator declared in `librechat.yaml`.
+ */
+function withPluginServers(configured) {
+  const pluginServers = getDeploymentPluginMcpServers();
+  const names = Object.keys(pluginServers);
+  if (names.length === 0) {
+    return configured;
+  }
+
+  const merged = { ...configured };
+  for (const name of names) {
+    /** Own-property check: an inherited member like `toString` is not a conflict. */
+    if (Object.hasOwn(merged, name)) {
+      logger.warn(
+        `[MCP] Plugin server "${name}" conflicts with a configured server and was skipped.`,
+      );
+      continue;
+    }
+    /** Defined rather than assigned so a name like `__proto__` cannot reach a setter. */
+    Object.defineProperty(merged, name, {
+      value: pluginServers[name],
+      enumerable: true,
+      writable: true,
+      configurable: true,
+    });
+  }
+  return merged;
+}
+
 /**
  * Initialize MCP servers
  */
 async function initializeMCPs() {
   const appConfig = await getAppConfig({ baseOnly: true });
-  const mcpServers = appConfig.mcpConfig;
+  const mcpServers = withPluginServers(appConfig.mcpConfig);
 
   try {
     createMCPServersRegistry(

api/server/services/initializeMCPs.plugins.spec.js

@@ -0,0 +1,169 @@
+/**
+ * Tests for merging Agent Plugins MCP servers into the configured servers.
+ *
+ * Plugin packages are third-party data, so a plugin must never displace a server
+ * the operator declared in librechat.yaml, and a plugin-controlled server name
+ * must never reach a prototype setter.
+ */
+
+jest.mock('mongoose', () => ({
+  connection: { readyState: 1 },
+}));
+
+jest.mock('@librechat/data-schemas', () => ({
+  logger: {
+    debug: jest.fn(),
+    error: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+  },
+}));
+
+const mockGetDeploymentPluginMcpServers = jest.fn();
+const mockRegisterShutdownTask = jest.fn();
+const mockSetHandler = jest.fn();
+
+jest.mock('@librechat/api', () => ({
+  get getDeploymentPluginMcpServers() {
+    return mockGetDeploymentPluginMcpServers;
+  },
+  get registerShutdownTask() {
+    return mockRegisterShutdownTask;
+  },
+  get setMCPToolsChangedHandler() {
+    return mockSetHandler;
+  },
+  get setMCPToolsChangedGenerationHandler() {
+    return mockSetHandler;
+  },
+  get setMCPToolsChangedGenerationRenewalHandler() {
+    return mockSetHandler;
+  },
+  get setMCPToolsChangedRevisionHandler() {
+    return mockSetHandler;
+  },
+}));
+
+jest.mock('./Config/mcp', () => ({
+  getMCPToolsCacheGeneration: jest.fn(),
+  renewMCPToolsCacheGeneration: jest.fn(),
+  getNextAppToolsPublicationRevision: jest.fn(),
+  updateMCPServerTools: jest.fn(),
+}));
+
+const mockGetAppConfig = jest.fn();
+const mockMergeAppTools = jest.fn();
+const mockSyncStaticTools = jest.fn();
+
+jest.mock('./Config', () => ({
+  get getAppConfig() {
+    return mockGetAppConfig;
+  },
+  get mergeAppTools() {
+    return mockMergeAppTools;
+  },
+  get syncStaticTools() {
+    return mockSyncStaticTools;
+  },
+}));
+
+const mockCreateMCPServersRegistry = jest.fn();
+const mockCreateMCPManager = jest.fn();
+const mockMCPManagerInstance = {
+  getAppToolFunctions: jest.fn(),
+  connectAppServers: jest.fn(),
+  disconnectAppServers: jest.fn(),
+};
+
+jest.mock('~/config', () => ({
+  get createMCPServersRegistry() {
+    return mockCreateMCPServersRegistry;
+  },
+  get createMCPManager() {
+    return mockCreateMCPManager;
+  },
+}));
+
+const { logger } = require('@librechat/data-schemas');
+const initializeMCPs = require('./initializeMCPs');
+
+const pluginServer = { type: 'streamable-http', url: 'https://plugin.example.com/mcp' };
+
+describe('initializeMCPs plugin server merge', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockCreateMCPServersRegistry.mockReturnValue(undefined);
+    mockCreateMCPManager.mockResolvedValue(mockMCPManagerInstance);
+    mockMCPManagerInstance.getAppToolFunctions.mockResolvedValue({});
+    mockMergeAppTools.mockResolvedValue(undefined);
+    mockSyncStaticTools.mockResolvedValue(undefined);
+    mockMCPManagerInstance.connectAppServers.mockResolvedValue(undefined);
+    mockGetDeploymentPluginMcpServers.mockReturnValue({});
+  });
+
+  /** Returns the config object the manager was constructed with. */
+  function managerConfig() {
+    return mockCreateMCPManager.mock.calls[0][0];
+  }
+
+  it('adds plugin servers alongside configured ones', async () => {
+    mockGetAppConfig.mockResolvedValue({ mcpConfig: { yamlServer: { type: 'stdio' } } });
+    mockGetDeploymentPluginMcpServers.mockReturnValue({ pluginServer });
+
+    await initializeMCPs();
+
+    expect(Object.keys(managerConfig()).sort()).toEqual(['pluginServer', 'yamlServer']);
+  });
+
+  it('leaves the configured servers untouched when no plugins contribute', async () => {
+    const mcpConfig = { yamlServer: { type: 'stdio' } };
+    mockGetAppConfig.mockResolvedValue({ mcpConfig });
+
+    await initializeMCPs();
+
+    expect(managerConfig()).toBe(mcpConfig);
+  });
+
+  it('never displaces a server declared in librechat.yaml', async () => {
+    const configured = { type: 'stdio', command: 'operator-owned' };
+    mockGetAppConfig.mockResolvedValue({ mcpConfig: { shared: configured } });
+    mockGetDeploymentPluginMcpServers.mockReturnValue({ shared: pluginServer });
+
+    await initializeMCPs();
+
+    expect(managerConfig().shared).toBe(configured);
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('conflicts with a configured'),
+    );
+  });
+
+  it('does not treat an inherited property name as a conflict', async () => {
+    mockGetAppConfig.mockResolvedValue({ mcpConfig: {} });
+    mockGetDeploymentPluginMcpServers.mockReturnValue({ toString: pluginServer });
+
+    await initializeMCPs();
+
+    expect(Object.hasOwn(managerConfig(), 'toString')).toBe(true);
+    expect(managerConfig().toString).toBe(pluginServer);
+    expect(logger.warn).not.toHaveBeenCalledWith(expect.stringContaining('conflicts'));
+  });
+
+  it('does not pollute the prototype through a plugin server name', async () => {
+    mockGetAppConfig.mockResolvedValue({ mcpConfig: {} });
+    mockGetDeploymentPluginMcpServers.mockReturnValue({ ['__proto__']: pluginServer });
+
+    await initializeMCPs();
+
+    expect({}.polluted).toBeUndefined();
+    expect(Object.getPrototypeOf(managerConfig())).toBe(Object.prototype);
+  });
+
+  it('tolerates a null mcpConfig while still adding plugin servers', async () => {
+    mockGetAppConfig.mockResolvedValue({ mcpConfig: null });
+    mockGetDeploymentPluginMcpServers.mockReturnValue({ pluginServer });
+
+    await initializeMCPs();
+
+    expect(Object.keys(managerConfig())).toEqual(['pluginServer']);
+  });
+});

api/server/services/initializeMCPs.spec.js

@@ -69,11 +69,15 @@ const mockUpdateMCPServerTools = jest.fn();
 const mockGetMCPToolsCacheGeneration = jest.fn();
 const mockRenewMCPToolsCacheGeneration = jest.fn();
 const mockGetNextAppToolsPublicationRevision = jest.fn();
+const mockGetDeploymentPluginMcpServers = jest.fn(() => ({}));
 
 jest.mock('@librechat/api', () => ({
   get registerShutdownTask() {
     return mockRegisterShutdownTask;
   },
+  get getDeploymentPluginMcpServers() {
+    return mockGetDeploymentPluginMcpServers;
+  },
   get setMCPToolsChangedHandler() {
     return mockSetMCPToolsChangedHandler;
   },