mcp-echo-env

mcp-echo-env

This repository provides an MCP server that simply echoes selected environmentvariables. It exists to verify that an MCP client propagates workspace context(PWD and WORKSPACE_SLUG) into the serverprocess. The canonical distribution is the published npm packagemcp-server-echo-env, andthat page should be treated as the project homepage for end users.

Project links:

• Repository: https://github.com/PabloLION/mcp-echo-env
• Issues / feedback: https://github.com/PabloLION/mcp-echo-env/issues
• npm package: https://www.npmjs.com/package/mcp-server-echo-env

For installation, local development, and distribution details seeinstructions.md. The remainder of this README focuses onhow to exercise the server when testing an MCP client or agent.

Workspace .env files

On startup the server loads environment variables from a .env file in thecurrent working directory (if present) and otherwise derives sensible defaults.In particular, when WORKSPACE_SLUG is not already defined it automaticallyfalls back to the basename of the workspace directory, and PWD defaults to thecurrent working directory.

Example .env placed at the workspace root:

# .env
WORKSPACE_SLUG=my-workspace
PWD=/custom/path/override

Values exported in the real environment still take precedence, so you canoverride per run via WORKSPACE_SLUG=demo pnpm start when needed.

For mono-repos with multiple workspaces, place a dedicated .env file in eachworkspace root and launch mcp-server-echo-env from inside that directory. Theserver recomputes both PWD and WORKSPACE_SLUG on every start, so simplychanging directories and re-running the binary is enough to validate how an MCPclient handles workspace-specific variables. You can also override per runwithout editing files by supplying inline exports:WORKSPACE_SLUG=staging PWD=/path/to/workspace mcp-server-echo-env.

Logging controls

Set MCP_ECHO_ENV_LOG_LEVEL to adjust how verbose the server is on stderr:

• silent – suppress all log output.
• error – only report failures (recommended for scripted smoke tests).
• info (default) – emit lifecycle messages such as readiness and shutdown.
• debug – include argument payloads and structured responses.

All logs stay on stderr so they never interfere with the JSON content returnedto clients on stdout.

Available tool

env_echo

Echo environment variables back to the caller.

• Default behaviour: returns PWD and WORKSPACE_SLUG.
• Arguments: none. The tool intentionally ignores user-supplied keys so onlythe workspace path and slug are ever exposed.

The tool responds with both a formatted text block and structured JSON:

{
  "tool": "env_echo",
  "variables": {
    "PWD": "/Users/me/projects/demo",
    "WORKSPACE_SLUG": "my-demo-workspace"
  },
  "workspace_slug": "my-demo-workspace",
  "pwd": "/Users/me/projects/demo"
}

The variables map always contains just these two keys. Lowercase aliases(workspace_slug, pwd) make the commonly inspected values easy to read.

MCP client capability check

Use this server as a quick sanity test to confirm that an MCP client or agentforwards environment variables:

1. Launch mcp-server-echo-env from the workspace you want the client toinspect. For ad-hoc checks you can run npx mcp-server-echo-env (requires noprior installation) or pnpm dlx mcp-server-echo-env.
2. Connect your MCP client to the running server (see the Codex CLI instructionsbelow for one example).
3. Invoke the env_echo tool and ensure the reported PWD and WORKSPACE_SLUGvalues match the workspace where you started the server. A mismatch indicatesthe client is not relaying the expected environment context.

Example trigger sequence

1. In one terminal, start the server from the target workspace:

   WORKSPACE_SLUG=demo mcp-server-echo-env
   

   Leave this running; it prints a single readiness message and then waits forrequests.

2. In a second terminal, ask Codex CLI (or another MCP client) to call thetool. For Codex CLI, run:

   codex 'Call env_echo with the default arguments and show the JSON response.'
   

   Ensure you previously registered the server with codex mcp add; Codex willlaunch mcp-server-echo-env, call the tool, and include the JSON payload inits response, confirming the client relayed PWD and WORKSPACE_SLUG.

3. When finished, stop the server with Ctrl+C in the first terminal.

Codex CLI example

There are two ways to make the server available to Codex CLI.

Option 1: CLI registration

codex mcp add mcp-echo-env mcp-server-echo-env

Ensure mcp-server-echo-env is discoverable on your $PATH (see “Distribution /installation” below). After registering, launch Codex with your desired prompt:

codex 'Call env_echo with the default arguments and show the JSON response.'

Codex will spawn the server automatically, stream the tool output, and includethe JSON payload in its reply. When you are done testing, remove the serverregistration with codex mcp remove mcp-echo-env. Pair it with other servers(for example the Jina web search MCP) through additional codex mcp add calls.

Option 2: Manual config entry

Edit ~/.codex/config.toml and add:

[mcp_servers.mcp-echo-env]
command = "mcp-server-echo-env"

You can then launch Codex with the same mcp_servers override shown above, ormake mcp-echo-env part of a profile in the TOML file. Add an optional[mcp_servers.mcp-echo-env.env] section only if you want to enforce a globaloverride; otherwise the server will infer WORKSPACE_SLUG from the activeworkspace.The server requires no authorization or credentials—the goal is simply toreflect whatever environment variables the client provides.

Other MCP clients

The same mcp-echo-env binary works with any MCP client that supports stdioservers. Below are sample configurations for two popular options.

Playwright MCP runner

Install the Playwright MCP package and register mcp-echo-env alongside it:

pnpm dlx @playwright/mcp@latest --version

Add the server to the JSON config Playwright recommends (usually~/.config/mcp/clients/playwright.json):

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    },
    "mcp-echo-env": {
      "command": "mcp-server-echo-env"
    }
  }
}

Restart the Playwright MCP runner and run a quick tool call (for example):

playwright mcp call mcp-echo-env env_echo

The JSON payload printed by Playwright should mirror the workspace where youstarted the runner.

Jina MCP tools

The jina-mcp-tools package exposes web search and reader capabilities. Add theecho server next to it in the shared MCP configuration (for example~/.config/mcp/clients/jina.json):

{
  "mcpServers": {
    "jina-mcp-tools": {
      "command": "npx",
      "args": ["jina-mcp-tools"]
    },
    "mcp-echo-env": {
      "command": "mcp-server-echo-env"
    }
  }
}

You can now ask Jina’s client to verify context transfer (for example):

gina mcp call mcp-echo-env env_echo

If the response lists the expected PWD and WORKSPACE_SLUG, the client iscorrectly forwarding environment variables to the server.