Skip to content
OmnodexOmnodexOmnodex Docs

MCP Proxy for Any Client

The Omnodex MCP proxy sits between an agent and its MCP servers. The agent connects to the proxy as a single MCP server; the proxy starts your real MCP servers, forwards every call, and records each one in the Omnodex event log.

Use it for agents that have no hook system, or when you want MCP-level controls such as parameter redaction.

Where the proxy is used

Section titled “Where the proxy is used”
ClientHow the proxy is set up
CoworkThe Omnodex plugin starts it. See Cowork.
OpenAI Codex (ChatGPT Desktop, CLI, IDE)Registered as an MCP server. See Codex.
Google AntigravityRegistered as an omnodex entry in mcp_config.json. See Antigravity.
Claude CodeOptional, alongside hooks. See Configuration.
Claude Desktop (chat app)Registered as an MCP server. See below.
Any other client that supports stdio MCP serversRegistered as an MCP server. See below.

Web apps such as claude.ai and ChatGPT on the web do not run MCP servers on your machine, so the local proxy cannot see their tool calls.

Set up the proxy

Section titled “Set up the proxy”

  1. Install Omnodex on the machine where the client runs.

  2. Create the proxy configuration.

    Terminal window
    omnodex mcp-proxy install

    This creates a template omnodex-proxy.json in your Omnodex home if none exists. Move the MCP servers you want Omnodex to see out of the client’s own configuration and into upstream_servers. See MCP proxy configuration for every field.

  3. Check it.

    Terminal window
    omnodex mcp-proxy status

    Lists the configured upstream servers and their redaction settings. To confirm the upstreams start, run the proxy yourself; it waits for input, and Ctrl+C stops it:

    Terminal window
    omnodex-mcp-proxy --config ~/.omnodex/omnodex-proxy.json

  4. Register the proxy with your client as a stdio MCP server named omnodex, in place of the servers you moved. Use absolute paths; desktop apps may not share your terminal’s PATH or expand ~.

    SettingValue
    CommandAbsolute path to node (node.exe on Windows)
    ArgumentsThe proxy script (below), --config, absolute path to omnodex-proxy.json

    The proxy script is a JavaScript file that node runs, on Windows too, where Node.js cannot run npm’s .cmd wrapper:

    <global node_modules>/omnodex/bin/omnodex-mcp-proxy.js, where npm root -g prints the global node_modules folder. On Windows that is usually C:\Users\<you>\AppData\Roaming\npm\node_modules\omnodex\bin\omnodex-mcp-proxy.js.

  5. Restart the client and start a new conversation. The proxy’s own tools (omnodex_status, omnodex_connect, omnodex_connection_status) and your upstream tools appear. Upstream tools are named <server>__<tool>, for example filesystem__read_file.

Claude Desktop

Section titled “Claude Desktop”

Claude Desktop reads MCP servers from claude_desktop_config.json. The examples use the npm proxy script; for a source install, use your build’s script from step 4:

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "omnodex": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Users\\<you>\\AppData\\Roaming\\npm\\node_modules\\omnodex\\bin\\omnodex-mcp-proxy.js",
        "--config",
        "C:\\Users\\<you>\\.omnodex\\omnodex-proxy.json"
      ]
    }
  }
}

Keep any other keys already in the file, and add omnodex alongside servers you are not routing through Omnodex. Fully quit and reopen Claude Desktop after editing.

What is logged

Section titled “What is logged”

The proxy sees everything that passes between the client and your MCP servers. This is what it records:

DataLoggedNotes
Tool name and owning serverYesFor example filesystem__read_file on filesystem
Tool call parametersYes, by defaultFile paths, queries, content to write. Set redact_parameters to replace values with [REDACTED]
Tool resultsNoOnly the response size is recorded
Duration and success or errorYesError messages are recorded
Proxy session start and endYesWith the list of upstream servers
Upstream credentialsNoPass them to upstreams as environment variables; they do not appear in MCP messages
Server identity and tool listsYes, as fingerprintsEach time a server lists its tools: hashes of its configuration entry (environment variable and header names, never values) and of each tool’s name, description and input schema, the name and version the server reports, and the installed version of an npx package when it can be read. The event holds hashes and tool names only. The full tool lists are kept in your Omnodex home, the newest 200, for the drift findings before and after view

Events stay in your local Omnodex home unless you connect to the hosted dashboard. Once connected, the proxy pushes each event to the live relay as it records it, and refreshes the encrypted blob every 15 minutes and again when the agent disconnects. See Automatic sync.

Stopping calls

Section titled “Stopping calls”

In guardrails mode the proxy checks each call before forwarding it. A call your settings stop never reaches the MCP server: the agent gets an error carrying the reason, and tool.completed records which rules stopped it. The proxy cannot prompt, so a call held for confirmation is stopped too, and the agent is told to ask you first.

Limits

Section titled “Limits”
  • The proxy records only servers routed through it. Servers the client connects to directly are not recorded.
  • The agent’s built-in tools (file edits, shell commands) do not go through MCP, so the proxy does not see them. Use hooks where the agent supports them.
  • Upstream servers must use the stdio transport.
  • An upstream that is slow to start may miss the first tool listing. Claude Code picks such tools up when they arrive; clients that ignore tool-list change notifications need an app restart. Cowork keeps the same list across new tasks until you fully quit and reopen the app. Starting with omnodex 0.10.0, uncached upstreams get a 45-second discovery window, and omnodex_status reports restart guidance if they are still connecting when the first list is sent. See Sizing the discovery window.

Next steps

Section titled “Next steps”