Environment Variable references in MCP Config

[gorootde]

What happened?

When using a custom user var as template in an env, the value is not being replaced properly.

Example:

mcpServers:
    karakeep:
      type: stdio
      command: npx
      args:
        - "-y"
        - "@karakeep/mcp"
      env:
        KARAKEEP_API_ADDR: https://karakeep
        KARAKEEP_API_KEY: "{{API_KEY}}"
      customUserVars:
        API_KEY:
          title: "Karakeep API Key"
          description: "Enter your personal API key for the service."

When placing the API key directly in the env, everything works as expected.

I've tried to configure the API key in the MCP server's settings in an agent, as well as directly in the mcp category. Both variants lead to the issue.

Version Information

registry.librechat.ai/danny-avila/librechat-dev                latest              9cd59b495db6   4 hours ago     2.06GB
registry.librechat.ai/danny-avila/librechat-dev                <none>              d8e7752a417f   2 days ago      2.06GB
registry.librechat.ai/danny-avila/librechat-rag-api-dev-lite   latest              a05a6506b318   12 days ago     1.59GB

3ddf62c8e5511a2c30672dbe3e6e07bedff374e6

Steps to Reproduce

See description

What browsers are you seeing the problem on?

No response

Relevant log output

-

Screenshots

No response

Code of Conduct

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

[danny-avila]

The double brackets are for variable references, to be provided from the UI. For your config, you need to use ${API_KEY}

[gorootde]

But according to this example in the docs double brackets are to be used to reference a customUserVars variable of which the value was configured in the UI.

Is the documentation wrong?

[danny-avila]

Thanks for following up, I think I misread your message as I did so on my phone. I'm taking a look now.

[danny-avila]

The issue is that servers with customUserVars need startup: false in the config, without it, the server connects at the application level during startup, where per-user credentials aren't available yet, so the {{API_KEY}} placeholder is never substituted.

Adding startup: false forces the connection to happen at the user level, where your credentials are resolved:

mcpServers:
  karakeep:
    type: stdio
    command: npx
    args:
      - "-y"
      - "@karakeep/mcp"
    env:
      KARAKEEP_API_ADDR: https://karakeep
      KARAKEEP_API_KEY: "{{API_KEY}}"
    customUserVars:
      API_KEY:
        title: "Karakeep API Key"
        description: "Enter your personal API key for the service."
    startup: false

I'll improve this so that servers with customUserVars are automatically excluded from app-level connections, removing the need to remember startup: false.

[danny-avila]

Improving this here:

#12226