Proxy Command

1mcp proxy is the maximum-compatibility bridge on top of a running 1MCP runtime.

It connects a local stdio transport to a running 1mcp serve HTTP runtime. In practice, this is the preferred fallback after CLI mode because most AI clients already support stdio, while fewer support streamable HTTP, SSE, or CLI mode.

Choose the Right Path

1MCP supports three different paths:

1. CLI mode for agent loops: recommended for Codex, Claude, and similar agent sessions.
2. proxy: recommended when you want the broadest client compatibility while keeping project context.
3. Direct streamable HTTP MCP attachment: use when the client can connect directly and you do not need project context.

proxy is not the main product experience. CLI mode remains the first choice for agent loops. proxy exists as the best non-CLI path when you want stdio compatibility plus .1mcprc and template-server support.

Synopsis

1mcp proxy [options]

What proxy Does

• discovers a running 1mcp serve instance
• forwards stdio MCP traffic to that runtime over HTTP
• can apply preset, filter, or tags selection before exposing the bridged inventory

The runtime still lives in serve. proxy does not replace it.

Auto-Discovery

proxy can discover a running runtime in these ways:

1. user-supplied --url
2. PID-file-based discovery
3. localhost port scan fallback

If project config is present, proxy can also merge settings from .1mcprc.

Project Configuration with .1mcprc

.1mcprc is useful when you repeatedly bridge the same project or client to the same preset or filtered runtime view.

Example:

{
  "preset": "development"
}

Priority order is:

1. command-line options
2. .1mcprc
3. defaults

Common Options

Connection

• --url, -u <url>: Override runtime auto-discovery.
• --context <name>: Use a named Runtime Target Context, including its saved bearer token when present.
• --config-dir, -d <path>: Use a specific config directory during discovery.

Exposure control

• --preset, -P <name>: Select a preset from the running runtime.
• --filter, -f <expression>: Apply a filter expression.
• --tags <tags>: Apply simple comma-separated tags.

Logging

• --log-level <level>: Set logging verbosity.
• --log-file <path>: Write logs to a file.

Examples

Appropriate use: maximum-compatibility stdio path

# shell 1
1mcp serve

# shell 2
1mcp proxy

Appropriate use: bridge to a preset

1mcp proxy --preset development

Appropriate use: bridge to a discovered runtime with filtering

1mcp proxy --filter "web AND api"

Windows MCP client configuration

Affected Windows MCP clients may not reliably pass arguments when they launch npm's 1mcp.cmd shim. For those clients, use the packaged Windows executable directly. After following the Windows binary installation instructions, set command to the absolute path where you extracted the executable:

{
  "mcpServers": {
    "1mcp": {
      "command": "C:\\Tools\\1mcp\\1mcp-win32-x64.exe",
      "args": ["proxy"]
    }
  }
}

Replace the example path with the executable's actual location. This invokes proxy directly without relying on a client to launch the npm .cmd shim. Add options such as "--preset", "development" or "--url", "http://127.0.0.1:3050/mcp" after "proxy" in the args array when needed.

The executable name and argument shape above are verified against the release packaging workflow and deterministic tests. This exact client launch path was not exercised on a live Windows host for this change.

Prefer CLI mode instead of proxy

If the client is an agent session, prefer:

1mcp cli-setup --codex
# or
1mcp cli-setup --claude --scope repo --repo-root .

Then let the agent use:

1mcp instructions
1mcp inspect <server>
1mcp inspect <server>/<tool>
1mcp run <server>/<tool> --args '<json>'

Use direct HTTP only when project context is unnecessary

If the client can talk to streamable HTTP MCP directly and you do not need project context, point it at the runtime endpoint:

http://127.0.0.1:3050/mcp?app=cursor

Authentication

proxy --context <name> resolves a named Runtime Target Context and can send its saved bearer token to the runtime. Create and authenticate the context first:

1mcp target add prod https://mcp.example.com/mcp --use
1mcp auth login --context prod --token "$TOKEN"
1mcp proxy --context prod

proxy --url <url> is an ephemeral connection. It does not load or attach saved credentials, so it remains credentialless. Stdio clients still do not receive an interactive OAuth browser flow; use a named context when the proxy must call a bearer-protected runtime.

See Also

• CLI Mode Guide
• Serve Command
• Runtime Target Context Commands
• Auth Commands
• Architecture