Proxy Command

Start STDIO proxy to connect MCP clients that only support STDIO transport to a running 1MCP HTTP server.

Synopsis

bash

npx -y @1mcp/agent proxy [options]

Description

The proxy command creates a STDIO transport proxy that forwards all MCP protocol communications to a running 1MCP HTTP server. This enables MCP clients that only support STDIO transport (like Claude Desktop) to connect to centralized 1MCP HTTP servers with advanced features like authentication, filtering, and multi-client support.

The proxy automatically discovers running 1MCP servers using multiple methods and provides a seamless bridge between STDIO and HTTP transports while supporting tag filtering and preset configurations.

Auto-Discovery

The proxy automatically discovers running 1MCP servers in this order:

PID File - Reads server URL from ~/.config/1mcp/server.pid
Port Scanning - Scans common ports (3050, 3051, 3052) on localhost
Environment Variables - Uses ONE_MCP_HOST and ONE_MCP_PORT
User Override - Uses URL specified with --url option

Project Configuration (.1mcprc)

You can create a project-level configuration file named .1mcprc in your project directory to set default connection settings for the proxy command. This allows you to avoid repeating command-line options and share configuration across team members.

Prerequisites

Project configuration is specifically designed for MCP clients that:

Do not support HTTP or SSE (Server-Sent Events) transport
Only support STDIO transport (like Claude Desktop)
Need to connect to a running 1MCP HTTP server via proxy

Required setup:

Running 1MCP server: Must have npx -y @1mcp/agent serve running on a port
MCP client limitations: Client cannot directly connect to HTTP/SSE endpoints
Bridge requirement: Need proxy to translate STDIO ↔ HTTP communications

This configuration is not needed for MCP clients that can directly connect to HTTP/SSE endpoints.

Configuration Priority

Settings are loaded in this order (higher priority overrides lower):

Command-line options (highest priority)
Project configuration file (.1mcprc)
Default values (lowest priority)

Configuration Structure

Create a .1mcprc file in your project directory:

json

{
  // Project-level configuration for 1MCP proxy command
  // Use preset for team collaboration and configuration management

  "preset": "my-preset"
}

Recommended Approach

We recommend using presets for better configuration management and team collaboration:

Create presets for different environments (development, production, testing)
Share presets with team members for consistent configurations
Switch environments easily by changing the preset name

Example Configurations

Development Environment

json

{
  "preset": "dev-environment"
}

Production Setup

json

{
  "preset": "production"
}

Testing Environment

json

{
  "preset": "testing"
}

Copy .1mcprc.example from the project root as a starting template.

Options

Connection Options

--url, -u <url> - Override auto-detected 1MCP server URL
--timeout, -t <ms> - Connection timeout in milliseconds (default: 10000)

Filtering Options

--filter, -f <expression> - Filter expression for server selection
--preset, -P <name> - Load preset configuration (URL, filters, etc.)

Global Options

--config-dir, -d <path> - Path to the config directory for discovery
--log-level <level> - Set log level (debug, info, warn, error)
--log-file <path> - Write logs to file

Tag Filtering

Use the --filter option to limit which MCP servers are exposed through the proxy:

Simple Filtering (OR logic)

bash

--filter "web,api,database"  # Exposes servers with ANY of these tags

Advanced Filtering (Boolean expressions)

bash

--filter "web AND database"           # Servers with BOTH tags
--filter "(web OR api) AND database"  # Complex logic
--filter "web AND NOT test"           # Exclusion logic

Priority Order

--filter option (highest priority)
Preset tag query (if --preset specified)
.1mcprc configuration file (preset only)
No filtering (expose all servers)

Examples

Basic Usage

bash

# Auto-discover and connect to running 1MCP server
npx -y @1mcp/agent proxy

# Connect with debug logging
npx -y @1mcp/agent proxy --log-level=debug

# Use custom config directory for discovery
npx -y @1mcp/agent proxy --config-dir=./test-config

# Use project configuration file (.1mcprc)
npx -y @1mcp/agent proxy

Specific Server Connection

bash

# Connect to specific server URL
npx -y @1mcp/agent proxy --url http://localhost:3051/mcp

# Connect with custom timeout
npx -y @1mcp/agent proxy --url http://192.168.1.100:3051/mcp --timeout=5000

Tag Filtering

bash

# Only expose servers with web and api tags
npx -y @1mcp/agent proxy --filter "web AND api"

# Expose development servers
npx -y @1mcp/agent proxy --filter "dev OR test"

# Complex filtering logic
npx -y @1mcp/agent proxy --filter "(web OR mobile) AND NOT production"

Preset Integration

bash

# Load URL and filters from saved preset
npx -y @1mcp/agent proxy --preset my-dev-setup

# Use preset with custom config directory
npx -y @1mcp/agent proxy --preset production --config-dir ./prod-config

Development and Testing

bash

# Development with full logging
npx -y @1mcp/agent proxy \
  --log-level=debug \
  --log-file=proxy-debug.log \
  --config-dir=./dev-config

# Test specific server with filtering
npx -y @1mcp/agent proxy \
  --url http://localhost:3051/mcp \
  --filter "filesystem,editing" \
  --timeout=15000

# Use project configuration in development
# Create .1mcprc file with your dev preset
echo '{"preset": "dev-setup"}' > .1mcprc
npx -y @1mcp/agent proxy

Authentication Considerations

STDIO Transport Limitations

STDIO transport does not support OAuth 2.1 authentication
STDIO clients cannot authenticate with servers that have auth enabled

Recommended Setup

For STDIO Clients (Claude Desktop, etc.)

bash

# Start server WITHOUT authentication for STDIO clients
npx -y @1mcp/agent serve --port=3051

# Start proxy (will work out of the box)
npx -y @1mcp/agent proxy

For HTTP/SSE Clients

bash

# Start server WITH authentication for web clients
npx -y @1mcp/agent serve --port=3052 --enable-auth

# HTTP/SSE clients can authenticate via OAuth
curl "http://localhost:3052/mcp?app=cursor"

Mixed Environment Strategy

Run separate server instances for different client types:

Port 3051: No auth for STDIO clients (via proxy)
Port 3052: With auth for HTTP/SSE clients

Workflow Integration

Typical Development Workflow

Start 1MCP Server
bash
```
npx -y @1mcp/agent serve --port=3051
```
1

Add MCP Servers

bash

npx -y @1mcp/agent mcp add filesystem -- npx mcp-server-filesystem
npx -y @1mcp/agent mcp add github -- npx mcp-server-github

Create Preset (Optional)

bash

npx -y @1mcp/agent preset create dev --filter "filesystem,github"

Start Proxy
bash
```
npx -y @1mcp/agent proxy --preset dev
```
1
Configure Client
- Point Claude Desktop to the proxy command
- Client communicates via STDIO to proxy
- Proxy forwards to HTTP server with filtering

Production Deployment

bash

# Production server with filtering
npx -y @1mcp/agent serve \
  --port=3051 \
  --enable-enhanced-security

# Production proxy with preset
npx -y @1mcp/agent proxy \
  --preset production \
  --log-level=info \
  --config-dir /etc/1mcp

Troubleshooting

Common Issues

Server Not Found

bash

# Check if server is running
npx -y @1mcp/agent mcp status

# Verify server URL manually
curl http://localhost:3051/mcp

Connection Timeout

bash

# Increase timeout for slow servers
npx -y @1mcp/agent proxy --timeout=30000

# Check network connectivity
netstat -an | grep 3051

Filter Not Working

bash

# Use debug logging to see filtering details
npx -y @1mcp/agent proxy --filter "web" --log-level=debug

# Verify server tags
npx -y @1mcp/agent mcp list --tags=web

Debug Information

Enable debug logging to troubleshoot issues:

bash

npx -y @1mcp/agent proxy --log-level=debug

Debug output shows:

Server discovery attempts
Connection establishment details
Tag parsing and filtering logic
MCP protocol forwarding

Proxy Command ​

Synopsis ​

Description ​

Auto-Discovery ​

Project Configuration (.1mcprc) ​

Prerequisites ​

Configuration Priority ​

Configuration Structure ​

Recommended Approach ​

Example Configurations ​

Development Environment ​

Production Setup ​

Testing Environment ​

Options ​

Connection Options ​

Filtering Options ​

Global Options ​

Tag Filtering ​

Simple Filtering (OR logic) ​

Advanced Filtering (Boolean expressions) ​

Priority Order ​

Examples ​

Basic Usage ​

Specific Server Connection ​

Tag Filtering ​

Preset Integration ​

Development and Testing ​

Authentication Considerations ​

STDIO Transport Limitations ​

Recommended Setup ​

For STDIO Clients (Claude Desktop, etc.) ​

For HTTP/SSE Clients ​

Mixed Environment Strategy ​

Workflow Integration ​

Typical Development Workflow ​

Production Deployment ​

Troubleshooting ​

Common Issues ​

Server Not Found ​

Connection Timeout ​

Filter Not Working ​

Debug Information ​

See Also ​

Proxy Command

Synopsis

Description

Auto-Discovery

Project Configuration (.1mcprc)

Prerequisites

Configuration Priority

Configuration Structure

Recommended Approach

Example Configurations

Development Environment

Production Setup

Testing Environment

Options

Connection Options

Filtering Options

Global Options

Tag Filtering

Simple Filtering (OR logic)

Advanced Filtering (Boolean expressions)

Priority Order

Examples

Basic Usage

Specific Server Connection

Tag Filtering

Preset Integration

Development and Testing

Authentication Considerations

STDIO Transport Limitations

Recommended Setup

For STDIO Clients (Claude Desktop, etc.)

For HTTP/SSE Clients

Mixed Environment Strategy

Workflow Integration

Typical Development Workflow

Production Deployment

Troubleshooting

Common Issues

Server Not Found

Connection Timeout

Filter Not Working

Debug Information

See Also