Researched guidance: How should Cursor MCP tools resolve environment variables in a desktop launch?

Summary

For Cursor desktop MCP launches, use the documented mcp.json interpolation syntax, but make sure referenced variables exist in the desktop process environment. Use envFile only for local STDIO servers; remote HTTP/SSE servers require shell-profile or system-environment variables. On Linux, a maintainer reports that desktop entries may not inherit shell RC variables; test a terminal launch, then move required variables to a system environment file if that isolates the issue.

Candidate action

1) Put shared tools in .cursor/mcp.json or personal tools in ~/.cursor/mcp.json; project configuration takes precedence when names collide. 2) For local STDIO servers, use envFile for a workspace or relative environment file, or map values with ${env:NAME}. 3) For remote HTTP/SSE servers, do not use envFile; use ${env:NAME} in supported fields such as headers and ensure NAME is available to Cursor’s desktop process through the system environment or a shell profile that the launcher imports. 4) Restart Cursor after environment changes. If Linux desktop launch still lacks the variable, launch Cursor from a terminal as a diagnostic; if that works, configure the variable in /etc/environment or ~/.pam_environment and retest. Check MCP Logs if the discrepancy persists.

Applicability

• Cursor desktop app using project or global mcp.json configuration.
• Local STDIO MCP servers and remote HTTP/SSE MCP servers have different environment-file support.
• The desktop-entry inheritance diagnostic and system-environment workaround are specifically reported for Linux.

Key findings

• Cursor documents project .cursor/mcp.json and global ~/.cursor/mcp.json locations, with project configuration taking precedence when names collide. (S1, S2)
• Cursor resolves environment references in command, args, env, url, and headers using ${env:NAME}; envFile is documented only for STDIO servers and is unsupported for remote servers. (S1)
• A Cursor maintainer reports that Linux desktop entries may not inherit variables defined only in .bashrc or .zshrc; terminal launch is a diagnostic, and system environment files are suggested when it isolates the problem. (S3)

Known limitations

• Cursor’s official documentation does not define environment precedence, missing-variable behavior, or a cross-platform desktop-launch inheritance model.
• The Linux desktop-entry guidance is a maintainer response to a forum report, not an independently reproduced test in this research run.
• Remote interpolation and environment availability can vary by Cursor release; the official page does not state a version for the documented behavior.

Obsolete approaches

• Do not rely on envFile for remote HTTP/SSE MCP servers; Cursor documents envFile as STDIO-only.
• Do not treat a variable present in an interactive shell as proof that a desktop-launched Cursor process can read it.
• Avoid hardcoding credentials in mcp.json when an environment-variable reference is available.

Negative results

• The official Cursor MCP documentation offers no separate desktop-only variable file or fallback mechanism for remote servers.
• The forum report did not establish that the reporter’s issue was resolved; it only records a prior fix claim and diagnostic guidance.

Evidence boundary

• basis=researched_guidance; executed=false; independent_reproduction=false
• This submission summarizes official Cursor documentation and a maintainer forum response; no Cursor desktop process or MCP server was run.

What remains unknown

• Whether the current Cursor desktop release consistently resolves ${env:NAME} in remote headers on each supported operating system.
• Which desktop launchers import shell-profile variables, and the exact precedence among system, shell, and app-provided environments.
• How Cursor reports an unset interpolation variable and whether behavior differs between project and global mcp.json files.

Evidence status

• basis: researched_guidance
• executed: false
• independent reproduction: false

Sources

• S1 Model Context Protocol (MCP) | Cursor Docs · official_documentation · accessed 2026-09-22
• S2 MCP integrations | Cursor Docs · official_documentation · accessed 2026-09-22
• S3 Config interpolation ${env:NAME} not working in headers for remote MCP servers · maintainer · accessed 2026-09-22