mcp-egress
Record every host an MCP server contacts, per tool, and fail CI on new ones.
What it is
What: run a stdio MCP server behind a small recording proxy and get the exact set of hosts it contacts while you run initialize, tools/list and sample tool calls. Every host is attributed to the phase and the tool that reached it, written to egress.json, printed as a table, and printed again as two ready-to-paste blocks: Claude Code WebFetch(domain:host) permission rules and a sandbox allowed-domain list. Keep the file as a baseline and --check fails CI the day a tool starts talking to a host nobody declared.
Who it is for: anyone who installs third-party MCP servers or maintains one, and wants a reviewed list of outbound hosts instead of trusting the README; security reviewers who need the allowlist for a Claude Code sandbox.
Quick start
pipx install git+https://github.com/basitalisandhu/mcp-egress
mcp-egress run --calls calls.json --baseline egress.baseline.json -- uvx some-mcp-server # record once
mcp-egress run --calls calls.json --baseline egress.baseline.json --check -- uvx some-mcp-server # in CI
A real run against the test fixture in this repository (a local web server on port 39211 stands in for an API):
$ mcp-egress run --calls calls.json -- python fixtures/proxied_server.py
mcp-egress: python fixtures/proxied_server.py
server: proxied-fixture 0.1.0 (protocol 2025-11-25), 6 tool(s), 3 call(s), 1 host(s)
HOST PORT SCHEME FIRST SEEN TOOLS CONNS OUT IN
127.0.0.1 39211 http call:fetch fetch, ping 2 248 B 406 B
Claude Code permission rules (settings.json, permissions.allow):
"WebFetch(domain:127.0.0.1)",
Sandbox allowed domains (settings.json, sandbox.network.allowedDomains):
[
"127.0.0.1"
]
Warnings:
open-world-hint-false ping: declares openWorldHint false but reached 127.0.0.1:39211
Wrote egress.json
Project site: https://basitalisandhu.github.io/mcp-egress/. Related: mcp-tools-lint checks the same server's tools/list schemas and annotations.
Install
pipx install git+https://github.com/basitalisandhu/mcp-egress # isolated CLI install
uvx --from git+https://github.com/basitalisandhu/mcp-egress mcp-egress --help # run without installing
pip install git+https://github.com/basitalisandhu/mcp-egress # into the current environment
git clone https://github.com/basitalisandhu/mcp-egress && cd mcp-egress && uv venv && uv pip install -e ".[dev]" # development
From the README; see the full README for every option.
Links
Releases
More in MCP tooling
- dev-mcp-servers: Ten small MCP servers for everyday development and security checks.
- mcp-server-template: Secure MCP server template in TypeScript and Python, safe by default.
- mcp-tools-lint: Lint MCP tool schemas and annotations before clients reject them.
- mcp-auth-doctor: Diagnose OAuth discovery problems on remote MCP servers.
- claude-mcp-allow: Least-privilege Claude Code permission rules for MCP tools, generated from their annotations.
- agentdojo-mcp: Run the AgentDojo benchmark's user and injection tasks against a real MCP server's tools.
- garak-mcp-probes: Run garak against your own MCP servers, with detectors for denied tool calls, leaked canaries and runaway step counts.
- mcp-rc-check: MCP specification migration checker for the 2026-07-28 revision: flags removed, changed and deprecated constructs and writes a patch for mechanical fixes.
Topics: agent-security, ai-agents, allowlist, ci, claude-code, cli, devsecops, egress, hacktoberfest, llm-security, mcp, model-context-protocol, network-security, proxy, python, sandbox, security-tools, supply-chain-security