[Bug]: Regression: MCP customUserVars substitution into env no longer works

[notfoundry]

What happened?

Just noticed this inconsistency after updating to the latest Librechat commit.

• Substitution of MCP server environment variables from customUserVars entries appears to no longer be working. My assumption is that this is a consequence of 8780a78.
• Substituting MCP server headers from customUserVars entries does appear to still be working.

What I see still working:

• In api/server/services/MCP.js::createMCPTool::_call, the value of config?.configurable?.userMCPAuthMap?.[`${Constants.mcp_prefix}${serverName}`] correctly contains the substituted values of the environment variables from customUserVars for the current user
• The MCP auth information from createMCPTool correctly makes it into MCPManager::callTool, where processMCPEnv is called and the substitution connection.setRequestHeaders(currentOptions.headers || {}) is made. I'm assuming this is why headers still work with customUserVars.
• When I reinitialize a MCP server that isn't working, I can see in the handler for router.post('/:serverName/reinitialize', ...) in api/server/routes/mcp.js that freshly-computed values of customUserVars correctly contain the substituted values of the environment variables.
• After reinitializing, the freshly-computed values of customUserVars are visible in UserConnectionManager::getUserConnection and MCPConnectionFactory::create.

What I see not working:

• In api/src/mcp/MCPConnectionFactory.ts::constructor, the value of oauth?.customUserVars which is passed into processMCPEnv when creating all MCP servers (I don't use any oauth servers) is undefined. This is the 2nd of 2 total places where processMCPEnv is called with a customUserVars value, so I'm assuming this is the problem area from 8780a78.
• In api/src/mcp/ConnectionsRepository.ts::get, the value of this.oauthOpts (which is passed to the MCPConnectionFactory constructor as the object containing customUserVars) is undefined too. This seems to be because neither MCPManager or MCPServersRegistry initialize an instance of ConnectionsRepository with an argument for the constructor's second parameter oauthOpts.
• After reinitializing, even though the freshly-computed values of customUserVars seem to be propagated all the way through to the server (I can see in the freshly-created server process that the environment variables are populated), the old broken instance of the server is not destroyed, and is not used by Librechat for future MCP tool calls. So from a user's perspective, nothing changes after reinitializing. There are just multiple servers running now behind the scenes.

Past this point, it's hard for me to tell what's going on. But when MCPConnectionFactory::create is first called while Librechat is starting up, what I can see is that there's no customUserVars information available for that first instance of any created MCPConnection for a MCP server.

Version Information

$ git rev-parse HEAD
a6fd32a

Steps to Reproduce

1. Add a MCP server to librechat.yaml, with at least one customUserVars entry, and an env entry referencing the customUserVars entry.
2. Enable that MCP server in Librechat and populate the credentials for the user variable.
3. Verify on the MCP server that the environment variable configured in the env entry just contains the {{PLACEHOLDER}} text, not the substituted value.

What browsers are you seeing the problem on?

No response

Relevant log output

No errors or warnings occur, and no relevant debug diagnostics exist in the refactored code paths.

Screenshots

No response

Code of Conduct

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

[danny-avila]

Thanks @dustinhealy is taking a look, and maybe @nhtruong can take a look if this is related to the MCP refactoring

[nhtruong]

Taking a look myself

[nhtruong]

Just wanna confirm that this works fine for user-level connections

---

I have the following MCP Server in librechat.yaml:

  github:
  # Relies on User-provided credentials for successful connection
    type: http
    url: 'https://api.githubcopilot.com/mcp/'
    headers:
      Authorization: '{{PAT_TOKEN}}'
    customUserVars:
      PAT_TOKEN:
        title: 'GitHub PAT Token'
        description: 'GitHub Personal Access Token for GitHub Copilot MCP server'
    startup: false

And after I provided it with my my PAT:

The token was correctly replaced in the config when the connection is created in via MCPConnectionFactory:

{
  "type": "http",
  "url": "https://api.githubcopilot.com/mcp/",
  "headers": {
    "Authorization": "github_pat_REDACTED"                                                                                                        
  },
  "customUserVars": {
    "PAT_TOKEN": {
      "title": "GitHub PAT Token",
      "description": "GitHub Personal Access Token for GitHub Copilot MCP server"
    }
  },
  "startup": false,
  "requiresOAuth": false
}

And I could use this just fine:

[nhtruong]

The issue that @notfoundry described is about an app-level connection, because user-level connections are not managed by ConnectionsRepository yet. The changes in 8780a78 included a fix for a bug where all connections were treated as user-connections, meaning the app-connection code path was never used. After this bugfix, non-OAuth servers or servers without startup: false are treated as app-level connections. These connections do NOT have user nor customUserVars passed to the MCPConnectionFactory because they are meant to be shared by all users. So, that bug was used as a feature there.

To resolve this, you must mark your MCP server with startup: false as it's meant for servers that require non-Oauth authentication as @dustinhealy has previously confirmed.

@danny-avila I think startup: false is also not a good name for this because it's using the side-effect of connection creation time to determine if a server's connection is meant to be shared. On-top of that technically, app connections are not established during startup anymore after lazy loading. I think we should rename it sharedConnection: false to better reflect what this does.

[nhtruong]

@notfoundry for some context on the bug I mentioned in the previous comment: #8811 (reply in thread). Basically it caused inconsistent behaviors for different users and made it very hard to troubleshoot connection issues.

[notfoundry]

Wow, this perfectly explains the behavior I was seeing! @nhtruong I should've read the context in #8811 when looking into it. So: while it is a behavioral regression from an end user perspective to need to manually establish each connection now, from a design intent perspective it's a bugfix for app-level connections not working the way they should.

I wonder if it would be a bit nicer for people getting familiar with MCP tools to have different interface cues for this situation. I see that my MCP server with startup: false has the "orange plug" icon for "Server connection failed or lost", even though no connection had ever been established yet! Something like the OAuth orange key and a green "Connect" button instead for a first-time connection would make it a lot more friendly/obvious that Librechat or the MCP server aren't broken, and it's just a necessary setup step

[nhtruong]

I wonder if it would be a bit nicer for people getting familiar with MCP tools to have different interface cues for this situation. I see that my MCP server with startup: false has the "orange plug" icon for "Server connection failed or lost", even though no connection had ever been established yet! Something like the OAuth orange key and a green "Connect" button instead for a first-time connection would make it a lot more friendly/obvious that Librechat or the MCP server aren't broken, and it's just a necessary setup step

@notfoundry I agree, a 🔑 icon for connections that require creds makes sense and very intuitive. I also think that this Icon should stay put whether the connection is severed or not. And the app should try to auto connect to these connections if the creds are already provided previously and the user can always click on the key icon to update the creds. There are a lot of great ideas for this space though. We should create a discussion for it.

cc @danny-avila