mcpproxy 0.2.1

# Claude Desktop Setup Guide

This guide shows how to configure Claude Desktop to use the MCP Proxy for connecting to remote MCP servers.

## Installation Methods

### Method 1: Cargo Install (Recommended for Rust users)

```bash
# Install globally from crates.io
cargo install mcpproxy

# Now you can use 'mcpproxy' command anywhere
mcpproxy --help
```

### Method 2: Install Script (Recommended for most users)

```bash
# Download and install latest release
curl -sSL https://raw.githubusercontent.com/sutterhill/agentdb/main/mcpproxy/install.sh | bash

# Or download manually
wget https://github.com/sutterhill/agentdb/releases/latest/download/mcpproxy-linux-x86_64
chmod +x mcpproxy-linux-x86_64
sudo mv mcpproxy-linux-x86_64 /usr/local/bin/mcpproxy
```

### Method 3: Build from Source

```bash
# Clone the repository
git clone https://github.com/sutterhill/agentdb.git
cd agentdb/mcpproxy

# Build the release version
cargo build --release

# Install to PATH (optional)
sudo cp target/release/mcpproxy /usr/local/bin/
```

## Claude Desktop Configuration

### 1. Find Your Claude Desktop Config Location

The Claude Desktop configuration file location depends on your operating system:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

### 2. Configure Claude Desktop

Edit your `claude_desktop_config.json` file to include the MCP proxy configuration.

**With global installation (no absolute paths needed!):**

```json
{
  "mcpServers": {
    "remote-agentdb": {
      "command": "mcpproxy",
      "args": [
        "--url", "https://your-remote-server.com/mcp",
        "--token", "your-auth-token"
      ],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}
```

### 3. Configuration Examples

#### Basic Remote Server (No Authentication)
```json
{
  "mcpServers": {
    "public-api": {
      "command": "mcpproxy",
      "args": ["--url", "https://api.example.com/mcp"]
    }
  }
}
```

#### Authenticated Remote Server
```json
{
  "mcpServers": {
    "private-api": {
      "command": "mcpproxy",
      "args": [
        "--url", "https://secure-api.example.com/mcp",
        "--token", "your-bearer-token-here"
      ]
    }
  }
}
```

#### Local Development Server
```json
{
  "mcpServers": {
    "local-dev": {
      "command": "mcpproxy",
      "args": ["--url", "http://localhost:3000/mcp"],
      "env": {
        "RUST_LOG": "debug"
      }
    }
  }
}
```

#### Multiple Remote Servers
```json
{
  "mcpServers": {
    "production-api": {
      "command": "mcpproxy",
      "args": [
        "--url", "https://prod-api.example.com/mcp",
        "--token", "prod-token"
      ]
    },
    "staging-api": {
      "command": "mcpproxy",
      "args": [
        "--url", "https://staging-api.example.com/mcp",
        "--token", "staging-token"
      ]
    }
  }
}
```

## Important Notes

### 1. Absolute Paths
Always use absolute paths for the `command` field. You can find the absolute path with:
```bash
cd mcpproxy
pwd
# Then append: /target/release/mcpproxy
```

### 2. Environment Variables
- `RUST_LOG`: Controls logging level (`error`, `warn`, `info`, `debug`, `trace`)
- Logs go to stderr and won't interfere with MCP communication

### 3. Security Considerations
- Store sensitive tokens securely
- Consider using environment variables for tokens instead of hardcoding them
- Use HTTPS URLs for production servers

### 4. Troubleshooting

#### Check if the binary works:
```bash
./target/release/mcpproxy --help
```

#### Test connection manually:
```bash
echo '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}' | \
  ./target/release/mcpproxy --url https://your-server.com/mcp
```

#### Enable debug logging:
Add to your config:
```json
"env": {
  "RUST_LOG": "debug"
}
```

### 5. Restart Claude Desktop
After modifying the configuration file, restart Claude Desktop for changes to take effect.

## Supported Remote Server Features

The proxy supports:
- ✅ JSON responses
- ✅ Server-Sent Events (text/event-stream)
- ✅ Bearer token authentication
- ✅ Multiple responses per request
- ✅ Proper error handling
- ✅ Request/response ID preservation

## Example Remote Server URLs

Replace these with your actual server URLs:
- `https://your-agentdb-instance.com/mcp`
- `https://api.yourcompany.com/mcp`
- `http://localhost:3000/mcp` (for local development)