MCP Echo Env

# 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`](https://www.npmjs.com/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`](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 # .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: ```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: ```bash 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: ```bash 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 ```bash 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: ```bash 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: ```toml [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: ```bash pnpm dlx @playwright/mcp@latest --version ``` Add the server to the JSON config Playwright recommends (usually `~/.config/mcp/clients/playwright.json`): ```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): ```bash 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`): ```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): ```bash 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.