MCP Proxy

Universal proxy for connecting Claude Desktop to remote MCP servers via HTTP.

What is MCP?

Model Context Protocol (MCP) allows AI assistants like Claude to access external tools and data sources. This proxy enables Claude Desktop to connect to remote MCP servers over HTTP/HTTPS.

Installation

npm install -g @codeninjapk/mcp-proxy

Setup

Run the interactive setup wizard:

mcp-proxy install

You'll be prompted for:

• Server name: Identifier for Claude (e.g., my-tools, company-api)
• Remote server URL: Your MCP server endpoint (e.g., https://api.example.com)
• Client ID: Authentication credential
• Client Secret: Authentication credential

Usage

Once installed:

1. Restart Claude Desktop
2. Ask Claude: "What tools does [server-name] have?"
3. Use your tools: Claude can now access your remote MCP server!

Commands

# Install and configure
mcp-proxy install

# Reconfigure settings
mcp-proxy configure

# Test connection
mcp-proxy test

# Uninstall from Claude Desktop
mcp-proxy uninstall

# Complete removal
npm uninstall -g @codeninjapk/mcp-proxy

How It Works

Claude Desktop (stdio) → MCP Proxy (local) → Your Server (HTTP)

The proxy runs locally and translates between:

• stdio (Claude Desktop's protocol)
• HTTP/JSON-RPC (your remote server)

Requirements

• Node.js 16+
• Claude Desktop
• A remote MCP server with:
  • JSON-RPC endpoint (/mcp/rpc)

Server Requirements

Your remote server must implement:

1. JSON-RPC Endpoint

POST /mcp/rpc
Authorization: Bearer <token>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Supported methods:

• tools/list - List available tools
• tools/call - Execute a tool
• prompts/list - List available prompts
• prompts/get - Get a specific prompt

Configuration File

Location:

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

Example:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/proxy-server.js"],
      "env": {
        "REMOTE_MCP_URL": "https://api.example.com",
        "MCP_CLIENT_ID": "client-id",
        "MCP_CLIENT_SECRET": "client-secret",
        "MCP_SERVER_NAME": "my-server"
      }
    }
  }
}

Troubleshooting

Connection Issues

mcp-proxy test

View Logs

• Windows: %APPDATA%\mcp-proxy.log
• macOS/Linux: ~/mcp-proxy.log

Common Issues

1. "Token request failed"

   • Check server URL is correct
   • Verify client credentials
   • Ensure server is running

2. "Claude doesn't see tools"

   • Restart Claude Desktop
   • Check config file location
   • Review logs for errors

3. "RPC failed"

   • Verify /mcp/rpc endpoint exists
   • Check server implements JSON-RPC correctly
   • Review server logs

Support

• Issues: https://github.com/codeninjapk/mcp-proxy/issues
• Docs: https://github.com/codeninjapk/mcp-proxy/wiki
• Email: [email protected]

License

MIT