# MCP Proxy CLI Usage Guide

This guide demonstrates how to use the MCP Proxy command-line interface.

## Installation

The proxy is installed as a Python package with a command-line entry point:

```bash
pip install -e .
```

This creates the `mcp-proxy` command that can be run from anywhere.

## Basic Usage

### Show Help

```bash
mcp-proxy --help
```

### Show Version

```bash
mcp-proxy --version
```

## Configuration

The proxy can be configured in two ways:

1. **Environment Variables** (recommended for production)
2. **Command-Line Arguments** (useful for testing and overrides)

Command-line arguments take precedence over environment variables.

### Using Environment Variables

Create a `.env` file (see `examples/.env.example`):

```bash
# .env
MCP_SERVER_URL=https://d3phcl5fqkzz01.cloudfront.net/mcp/
OAUTH_PROVIDER_URL=https://your-oauth-provider.com
MCP_CLIENT_NAME=my-proxy-client
MCP_LOG_LEVEL=info
```

Then run the proxy:

```bash
# Load environment variables and run
export $(cat .env | xargs)
mcp-proxy
```

Or use a tool like `python-dotenv`:

```bash
# Install python-dotenv if not already installed
pip install python-dotenv

# Run with environment variables
python -c "from dotenv import load_dotenv; load_dotenv()" && mcp-proxy
```

### Using Command-Line Arguments

```bash
mcp-proxy \
  --mcp-server-url "https://d3phcl5fqkzz01.cloudfront.net/mcp/" \
  --oauth-provider-url "https://your-oauth-provider.com" \
  --client-name "my-proxy-client" \
  --log-level info
```

### Mixing Environment Variables and CLI Arguments

CLI arguments override environment variables:

```bash
# Set base configuration via environment
export MCP_SERVER_URL="https://d3phcl5fqkzz01.cloudfront.net/mcp/"
export OAUTH_PROVIDER_URL="https://your-oauth-provider.com"

# Override specific settings via CLI
mcp-proxy --log-level debug --client-name "debug-client"
```

## Configuration Options

### Required Options

- `--mcp-server-url URL` (env: `MCP_SERVER_URL`)
  - URL of the HTTP MCP server to connect to
  - Example: `https://d3phcl5fqkzz01.cloudfront.net/mcp/`

- `--oauth-provider-url URL` (env: `OAUTH_PROVIDER_URL`)
  - URL of the OAuth provider for Dynamic Client Registration
  - Example: `https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX`

### Optional Options

- `--client-name NAME` (env: `MCP_CLIENT_NAME`, default: `mcp-proxy-client`)
  - OAuth client name for DCR
  - Example: `my-custom-client`

- `--scopes SCOPE1,SCOPE2` (env: `MCP_SCOPES`, default: `mcp:read,mcp:write`)
  - Comma-separated list of OAuth scopes
  - Example: `read,write,admin`

- `--connection-timeout SECONDS` (env: `MCP_CONNECTION_TIMEOUT`, default: `30`)
  - HTTP connection timeout in seconds
  - Example: `60`

- `--retry-attempts COUNT` (env: `MCP_RETRY_ATTEMPTS`, default: `3`)
  - Number of retry attempts for failed requests
  - Example: `5`

- `--max-backoff SECONDS` (env: `MCP_MAX_BACKOFF_SECONDS`, default: `60`)
  - Maximum backoff time in seconds for retries
  - Example: `120`

- `--log-level LEVEL` (env: `MCP_LOG_LEVEL`, default: `info`)
  - Logging level: `debug`, `info`, `warn`, or `error`
  - Example: `debug`

## Utility Commands

### Validate Configuration

Check if your configuration is valid without starting the proxy:

```bash
mcp-proxy --validate-config \
  --mcp-server-url "https://example.com/mcp" \
  --oauth-provider-url "https://oauth.example.com"
```

Output:
```
Configuration is valid ✓
MCP Proxy Configuration
============================================================
MCP Server URL:        https://example.com/mcp
OAuth Provider URL:    https://oauth.example.com/
Client Name:           mcp-proxy-client
Scopes:                mcp:read, mcp:write
Connection Timeout:    30s
Retry Attempts:        3
Max Backoff:           60s
Log Level:             info
============================================================
```

### Show Effective Configuration

Display the effective configuration (after merging environment variables and CLI arguments):

```bash
export MCP_SERVER_URL="https://example.com/mcp"
export OAUTH_PROVIDER_URL="https://oauth.example.com"

mcp-proxy --show-config --log-level debug
```

This is useful for debugging configuration issues.

## Running the Proxy

### Standard Mode

Run the proxy with environment variables:

```bash
export MCP_SERVER_URL="https://d3phcl5fqkzz01.cloudfront.net/mcp/"
export OAUTH_PROVIDER_URL="https://your-oauth-provider.com"

mcp-proxy
```

The proxy will:
1. Load configuration from environment variables
2. Perform OAuth Dynamic Client Registration
3. Start the stdio interface
4. Begin processing MCP requests from Kiro

### Debug Mode

Run with debug logging to see detailed information:

```bash
mcp-proxy \
  --mcp-server-url "https://d3phcl5fqkzz01.cloudfront.net/mcp/" \
  --oauth-provider-url "https://your-oauth-provider.com" \
  --log-level debug
```

### Custom Configuration

Run with custom settings:

```bash
mcp-proxy \
  --mcp-server-url "https://d3phcl5fqkzz01.cloudfront.net/mcp/" \
  --oauth-provider-url "https://your-oauth-provider.com" \
  --client-name "production-proxy" \
  --scopes "mcp:read,mcp:write,mcp:admin" \
  --connection-timeout 60 \
  --retry-attempts 5 \
  --max-backoff 120 \
  --log-level info
```

## Integration with Kiro

To use the proxy with Kiro, configure Kiro to launch the proxy as a subprocess:

```json
{
  "mcpServers": {
    "my-http-server": {
      "command": "mcp-proxy",
      "env": {
        "MCP_SERVER_URL": "https://d3phcl5fqkzz01.cloudfront.net/mcp/",
        "OAUTH_PROVIDER_URL": "https://your-oauth-provider.com",
        "MCP_CLIENT_NAME": "kiro-client",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}
```

Kiro will:
1. Launch the proxy as a subprocess
2. Communicate with it via stdio (JSON-RPC)
3. The proxy translates requests to HTTP and forwards to the backend
4. The proxy handles OAuth authentication transparently

## Troubleshooting

### Configuration Errors

If you see configuration errors, use `--validate-config` to check your settings:

```bash
mcp-proxy --validate-config \
  --mcp-server-url "your-url" \
  --oauth-provider-url "your-oauth-url"
```

### Connection Issues

Enable debug logging to see detailed connection information:

```bash
mcp-proxy --log-level debug
```

### Authentication Failures

Check that:
1. Your OAuth provider URL is correct
2. The OAuth provider supports Dynamic Client Registration (RFC 7591)
3. Network connectivity to the OAuth provider is available

### Missing Environment Variables

If required environment variables are missing, you'll see an error:

```
Error: Missing required configuration: MCP_SERVER_URL

Use --help for usage information
```

Set the required variables or provide them via CLI arguments.

## Examples

### Example 1: Basic Usage with Environment Variables

```bash
export MCP_SERVER_URL="https://d3phcl5fqkzz01.cloudfront.net/mcp/"
export OAUTH_PROVIDER_URL="https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX"

mcp-proxy
```

### Example 2: Debug Mode with Custom Client Name

```bash
mcp-proxy \
  --mcp-server-url "https://d3phcl5fqkzz01.cloudfront.net/mcp/" \
  --oauth-provider-url "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX" \
  --client-name "debug-proxy" \
  --log-level debug
```

### Example 3: Production Configuration

```bash
mcp-proxy \
  --mcp-server-url "https://d3phcl5fqkzz01.cloudfront.net/mcp/" \
  --oauth-provider-url "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX" \
  --client-name "production-proxy" \
  --scopes "mcp:read,mcp:write" \
  --connection-timeout 60 \
  --retry-attempts 5 \
  --max-backoff 120 \
  --log-level info
```

### Example 4: Validate Configuration Before Running

```bash
# First, validate the configuration
mcp-proxy --validate-config \
  --mcp-server-url "https://d3phcl5fqkzz01.cloudfront.net/mcp/" \
  --oauth-provider-url "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX"

# If valid, run the proxy
mcp-proxy \
  --mcp-server-url "https://d3phcl5fqkzz01.cloudfront.net/mcp/" \
  --oauth-provider-url "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX"
```

## Exit Codes

- `0`: Success (normal shutdown or validation passed)
- `1`: Error (configuration error, authentication failure, or runtime error)

## Signals

The proxy handles the following signals for graceful shutdown:

- `SIGTERM`: Graceful shutdown
- `SIGINT` (Ctrl+C): Graceful shutdown

During shutdown, the proxy will:
1. Stop accepting new requests
2. Complete pending requests
3. Close HTTP connections
4. Clean up resources
5. Exit

## Additional Resources

- [README.md](../README.md) - Project overview
- [ARCHITECTURE.md](../ARCHITECTURE.md) - System architecture
- [DEVELOPMENT.md](../DEVELOPMENT.md) - Development guide
- [PROXY_USAGE.md](../PROXY_USAGE.md) - Detailed proxy usage
