mcp-echo-env

This repository provides an MCP server that simply echoes selected environment variables. It exists to verify that an MCP client propagates workspace context (PWD and WORKSPACE_SLUG) into the server process. The canonical distribution is the published npm package mcp-server-echo-env, and that 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 see instructions.md. The remainder of this README focuses on how 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 the current working directory (if present) and otherwise derives sensible defaults. In particular, when WORKSPACE_SLUG is not already defined it automatically falls back to the basename of the workspace directory, and PWD defaults to the current 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 can override per run via WORKSPACE_SLUG=demo pnpm start when needed.

For mono-repos with multiple workspaces, place a dedicated .env file in each workspace root and launch mcp-server-echo-env from inside that directory. The server recomputes both PWD and WORKSPACE_SLUG on every start, so simply changing directories and re-running the binary is enough to validate how an MCP client handles workspace-specific variables. You can also override per run without 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 returned to 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 only the 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 agent forwards environment variables:

1. Launch mcp-server-echo-env from the workspace you want the client to inspect. For ad-hoc checks you can run npx mcp-server-echo-env (requires no prior installation) or pnpm dlx mcp-server-echo-env.
2. Connect your MCP client to the running server (see the Codex CLI instructions below for one example).
3. Invoke the env_echo tool and ensure the reported PWD and WORKSPACE_SLUG values match the workspace where you started the server. A mismatch indicates the 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 for requests.

2. In a second terminal, ask Codex CLI (or another MCP client) to call the tool. 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 will launch mcp-server-echo-env, call the tool, and include the JSON payload in its 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 include the JSON payload in its reply. When you are done testing, remove the server registration 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, or make 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 global override; otherwise the server will infer WORKSPACE_SLUG from the active workspace. The server requires no authorization or credentials—the goal is simply to reflect whatever environment variables the client provides.

Other MCP clients

The same mcp-echo-env binary works with any MCP client that supports stdio servers. 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 you started the runner.

Jina MCP tools

The jina-mcp-tools package exposes web search and reader capabilities. Add the echo 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 is correctly forwarding environment variables to the server.