Cursor MCP Environment Variables: Complete Guide

Cursor MCP Environment Variables: Complete Guide

Most Model Context Protocol (MCP) servers require more than just a command to start successfully.

They often need API keys, authentication tokens, file paths, feature flags, or other configuration values that vary between environments.

Rather than embedding these values directly into source code, MCP servers commonly receive them through environment variables.

Cursor supports passing environment variables to local MCP servers, making it easy to configure applications securely while keeping sensitive information separate from your codebase.

In this guide, you'll learn how environment variables work with Cursor MCP, how they are configured, when they should be used, and the best practices for managing them securely.

Quick Answer

Cursor can pass environment variables to local MCP servers through the env section of mcp.json. Environment variables are commonly used for API keys, authentication tokens, configuration settings, and other values that should remain outside application code.

What Are Environment Variables?

Environment variables are configuration values provided to a running application by the operating system.

Instead of hardcoding settings inside an MCP server, the application reads them when it starts.

A simplified flow looks like this:

        mcp.json
            │
     Environment Variables
            │
            ▼
      Cursor launches
      Local MCP Server
            │
            ▼
     Reads Configuration

Because the values exist outside the application's source code, the same MCP server can run with different configurations across development, testing, and production environments.

Why Use Environment Variables?

Separating configuration from code provides several important benefits.

Keep Secrets Out of Source Code

Sensitive values such as API keys should never be embedded directly in an application.

Environment variables reduce the risk of accidentally exposing credentials through version control.

Support Multiple Environments

Development, staging, and production often require different configuration values.

Environment variables allow the same application to adapt without changing its code.

Simplify Configuration

Updating a configuration value is usually easier than modifying source code and rebuilding an application.

This simplifies deployment and maintenance.

Improve Security

Although environment variables are not encryption, they provide a safer way to manage sensitive information than hardcoding credentials.

How Cursor Uses Environment Variables

When Cursor launches a local stdio MCP server, it can provide environment variables defined in mcp.json.

The overall process is straightforward.

             Cursor
                │
      Reads mcp.json
                │
      Passes env values
                │
                ▼
        Local MCP Server
                │
        Reads Variables

Cursor itself does not interpret these values.

It simply provides them to the server process, which decides how they should be used.

Environment Variables in mcp.json

Local MCP servers can define an env object inside their configuration.

A simplified example looks like this:

{
  "mcpServers": {
    "example-server": {
      "command": "...",
      "args": [],
      "env": {
        "API_KEY": "...",
        "ENVIRONMENT": "development"
      }
    }
  }
}

Each configured server may have its own independent set of environment variables.

This allows different MCP servers to use different credentials or configuration without interfering with one another.

Common Uses

Environment variables are commonly used for:

• API keys
• authentication tokens
• cloud service credentials
• database connection settings
• feature flags
• application configuration
• file locations
• logging configuration

Using environment variables keeps configuration flexible while reducing the need to modify application code.

Environment Variables and Remote MCP Servers

Remote MCP servers also use environment variables.

The difference is where they are managed.

For local stdio servers, Cursor passes the variables when launching the server.

For remote MCP servers, environment variables are configured on the server itself rather than inside Cursor.

A typical deployment looks like this:

           Cursor
              │
          HTTPS / HTTP
              │
              ▼
      Remote MCP Server
              │
      Environment Variables
              │
              ▼
      APIs • Databases • Services

The underlying concept remains exactly the same.

Only the location where the variables are configured changes.

Environment Variables and Docker

Docker works naturally with environment variables.

Containerized MCP servers frequently receive configuration through Docker's environment variable system.

Docker Container
       │
Environment Variables
       │
       ▼
   MCP Server

This approach allows the same container image to be reused across multiple environments while changing only the configuration values.

Docker itself does not interpret the variables.

It simply makes them available to the MCP server process.

Common Problems

Most environment variable issues involve configuration rather than Cursor.

Missing Variables

If a required variable is not provided, the MCP server may fail to start or operate correctly.

Always verify which variables your server expects.

Typographical Errors

Variable names are typically case-sensitive.

A small spelling mistake can prevent an application from finding the expected value.

Invalid Credentials

An incorrect API key or expired token may cause authentication failures even though the MCP server launches successfully.

Environment Differences

Configuration that works in development may fail in production if required variables have not been configured consistently.

Security Best Practices

Environment variables improve security, but they should still be managed carefully.

Follow these recommendations:

• Never commit secrets to version control.
• Store API keys outside application code.
• Rotate credentials regularly.
• Grant only the permissions required by the MCP server.
• Remove unused credentials promptly.
• Document required environment variables for your project.

For highly sensitive deployments, organizations often combine environment variables with dedicated secret management systems.

Conclusion

Environment variables are the standard way to configure MCP servers without embedding sensitive information directly into application code.

Cursor supports passing environment variables to local stdio MCP servers through mcp.json, making it easy to manage API keys, authentication tokens, and application settings securely.

As projects grow, the same principles apply to Docker containers and remote MCP servers, allowing consistent configuration across development and production environments.

Understanding how environment variables work will help you build MCP servers that are easier to deploy, maintain, and secure.

Continue learning:

• Cursor mcp.json — Learn where environment variables are configured.
• Cursor MCP Config — Understand Cursor's complete MCP configuration model.
• Cursor MCP Authentication — Protect credentials used by MCP servers.
• Cursor MCP Docker — Pass environment variables to containerized MCP servers.
• Cursor MCP stdio — Learn how Cursor launches local MCP servers.
• Cursor MCP Remote Server — Understand configuration in remote deployments.