# 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.
