Fusion MCP Proxy

WebSocket proxy server that bridges browser-based clients to local stdio-based MCP (Model Context Protocol) servers with AI agent execution capabilities.

Features

🔌 MCP Server Proxy

• Runs on your local machine
• Spawns MCP server processes using stdio
• Exposes WebSocket interface for browser clients
• Enables testing local servers from deployed web apps

🤖 AI Agent Execution (New in v0.3.0)

• Run entire LangGraph ReAct agents on the proxy
• Direct MCP server access - no browser bridge needed
• Synchronous tool execution - eliminates timing issues
• Supports OpenAI, Anthropic, and IBM Watsonx models
• Reads server configs from your local mcp.json
• Streams responses including tool calls and results

Why Use Agent Execution on Proxy?

Problem with browser-based agents:

• Tools execute asynchronously via browser bridge
• Agent finishes before tool results return
• Causes hallucinations and incorrect responses

Solution with proxy-based agents:

• Agent runs on proxy with direct MCP access
• Tools execute synchronously before agent continues
• Agent sees actual results before generating response
• No hallucinations, accurate responses every time

Installation

npm install -g fusion-mcp-proxy

The package provides two commands:

• fusion-mcp-proxy (full name)
• fmcp-proxy (short alias) ⚡

Quick Start

Basic Proxy Mode

1. Start the proxy server:

   fmcp-proxy start
   # or
   fusion-mcp-proxy start

2. Open your playground (e.g., https://your-app.vercel.app/playground)

3. Add a local MCP server that uses stdio transport

4. The browser will connect to ws://localhost:8080 and the proxy will handle the rest!

Agent Execution Mode (Recommended)

1. Configure your MCP servers in your local mcp.json (see Configuration section)

2. Start the proxy:

   fmcp-proxy start

3. In your playground, select "Proxy Agent" execution mode

4. Chat naturally - the agent runs on the proxy with direct tool access!

Usage

Start Server

# Start with default settings (auto-detects config from any supported client)
fmcp-proxy start

# Start with specific MCP client config
fmcp-proxy start --client claude
fmcp-proxy start --client bob
fmcp-proxy start --client copilot

# Custom config file path
fmcp-proxy start --config /path/to/mcp.json

# Custom port
fmcp-proxy start --port 9000

# With authentication
fmcp-proxy start --token your-secret-token

# Custom host (e.g., for Docker)
fmcp-proxy start --host 0.0.0.0

# Enable debug logging
fmcp-proxy start --log-level debug

# You can also use the full command name
fusion-mcp-proxy start

Options

| Option | Description | Default | |--------|-------------|---------| | -p, --port <port> | WebSocket server port | 8080 | | -h, --host <host> | Host to bind to | localhost | | -c, --client <client> | MCP client type: claude, bob, copilot, or custom | custom | | --config <path> | Custom config file path (overrides --client) | None | | --token <token> | Authentication token (optional) | None | | --cors <origins> | CORS allowed origins (comma-separated) | * | | --log-level <level> | Log level (error, warn, info, debug) | info |

How It Works

┌──────────────────────────────────────────────────┐
│ Browser (Deployed Web App on Vercel/Cirrus)     │
│                                                   │
│  [Playground UI]                                 │
│         │                                         │
│         │ WebSocket (ws://localhost:8080)        │
│         ▼                                         │
└──────────────────────────────────────────────────┘
         │
         │
┌────────▼──────────────────────────────────────────┐
│ Your Local Machine                                │
│                                                    │
│  [Fusion MCP Proxy]                               │
│         │                                          │
│         │ Spawns process & uses stdio             │
│         ▼                                          │
│  [Local MCP Server Process]                       │
│    - Reads from stdin                             │
│    - Writes to stdout                             │
│    - Executes tools                               │
│                                                    │
└───────────────────────────────────────────────────┘

Agent Execution Architecture (v0.3.0+)

When using Proxy Agent mode, the entire AI agent runs on the proxy server:

┌──────────────────────────────────────────────────┐
│ Browser (Playground UI)                          │
│                                                   │
│  User: "Explain IncentiveProcess apex class"    │
│         │                                         │
│         │ WebSocket: agent/execute                │
│         │ (messages, servers, modelConfig)        │
│         ▼                                         │
└──────────────────────────────────────────────────┘
         │
         │
┌────────▼──────────────────────────────────────────┐
│ Proxy Server (Your Local Machine)                │
│                                                    │
│  [LangGraph ReAct Agent]                          │
│    ├─ Reads mcp.json config                      │
│    ├─ Spawns MCP servers (stdio)                 │
│    ├─ Creates tools from MCP servers             │
│    ├─ Runs reasoning loop                        │
│    │                                              │
│    ├─ Agent: "I need the Apex code..."           │
│    ├─ → Calls salesforce_read_apex               │
│    ├─ ← Returns actual code synchronously        │
│    ├─ Agent: "Based on this code..."             │
│    └─ Generates accurate response                │
│         │                                         │
│         │ Streams: content + tool calls           │
│         ▼                                         │
│  Browser receives final response                  │
└───────────────────────────────────────────────────┘

Key Benefits

✅ Synchronous Execution: Tools complete before agent continues
✅ No Hallucinations: Agent sees real results before responding
✅ Better Reliability: Direct MCP access, no browser bridge
✅ Automatic Config: Reads from your existing mcp.json
✅ Multi-Model: Supports OpenAI, Anthropic, Watsonx

Supported Models

The proxy agent supports:

• OpenAI: gpt-4o, gpt-4o-mini, gpt-4-turbo, etc.
• Anthropic: claude-3-5-sonnet, claude-3-opus, etc.
• IBM Watsonx: granite models, llama models, mixtral, etc.

Model credentials are automatically populated from environment variables:

• OPENAI_API_KEY
• ANTHROPIC_API_KEY
• WATSONX_API_KEY, WATSONX_PROJECT_ID, WATSONX_URL

Configuration with mcp.json

New in v0.1.0+: The proxy automatically reads server configurations from your MCP client's config file, eliminating the need to send server configurations from the browser!

New in v0.3.0+: Agent execution uses the same mcp.json configuration for seamless integration.

Supported MCP Clients

The proxy supports configuration files from:

• Claude Desktop (--client claude)
• IBM Bob IDE (--client bob)
• GitHub Copilot Chat (--client copilot)
• Custom/Auto-detect (--client custom - default, tries all locations)

Configuration File Locations

The proxy automatically searches for MCP configuration files in these locations (in order):

GitHub Copilot Chat:

• macOS: ~/Library/Application Support/Code/User/mcp.json
• Windows: %APPDATA%\Code\User\mcp.json
• Linux: ~/.config/Code/User/mcp.json

Claude Desktop:

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

IBM Bob IDE:

• Global (macOS): ~/Library/Application Support/Bob-IDE/User/globalStorage/ibm.bob-code/settings/mcp_settings.json
• Global (Windows): %APPDATA%\Bob-IDE\User\globalStorage\ibm.bob-code/settings/mcp_settings.json
• Project: <project-root>/.Bob/mcp.json

GitHub Copilot Chat (Project):

• <project-root>/.vscode/mcp.json

Fusion MCP (Custom):

• ~/.fusion-mcp/servers/mcp.json

The proxy will use the first configuration file it finds, so if you have multiple MCP clients installed, the priority is: GitHub Copilot → Claude Desktop → Bob IDE → Custom locations.

Automatic Configuration Loading

When registering a server, use useMcpJson: true to load configuration from your local file:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "register_server",
  "params": {
    "serverId": "salesforce-mcp-server",
    "serverName": "Salesforce MCP Server",
    "useMcpJson": true,
    "mcpConfigKey": "salesforce-mcp-server"
  }
}

mcp.json File Locations

The proxy searches for mcp.json in these locations:

VS Code:

• macOS: ~/Library/Application Support/Code/User/mcp.json
• Windows: %APPDATA%\Code\User\mcp.json
• Linux: ~/.config/Code/User/mcp.json

Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Example mcp.json

{
  "mcpServers": {
    "salesforce-mcp-server": {
      "command": "node",
      "args": ["/Users/you/Downloads/salesforce-mcp-server/dist/index.js"],
      "env": {
        "SALESFORCE_CONNECTION_TYPE": "password",
        "SALESFORCE_USERNAME": "[email protected]",
        "SALESFORCE_PASSWORD": "password",
        "SALESFORCE_TOKEN": "token",
        "SALESFORCE_INSTANCE_URL": "https://login.salesforce.com"
      }
    },
    "github-mcp-server": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

Benefits

✅ Security: API keys and credentials stay in your local file
✅ Convenience: No need to configure servers in the web UI
✅ Sync: Same config works with VS Code, Claude Desktop, and the proxy
✅ Privacy: Browser never sees your sensitive configurations

WebSocket Protocol

The proxy uses JSON-RPC 2.0 over WebSocket.

Authentication (Optional)

If you start the proxy with --token, clients must authenticate:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "authenticate",
  "params": {
    "token": "your-secret-token"
  }
}

Register Server

Register a local MCP server with the proxy:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "register_server",
  "params": {
    "serverId": "my-local-server",
    "command": "node",
    "args": ["/path/to/server.js"],
    "env": {
      "API_KEY": "optional-env-var"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "success": true,
    "serverId": "my-local-server",
    "message": "Server registered successfully"
  }
}

List Tools

List available tools from a registered server:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/list",
  "params": {
    "serverId": "my-local-server"
  }
}

Call Tool

Execute a tool on a registered server:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "serverId": "my-local-server",
    "name": "read_file",
    "arguments": {
      "path": "/path/to/file.txt"
    }
  }
}

Unregister Server

Clean up when done:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "unregister_server",
  "params": {
    "serverId": "my-local-server"
  }
}

Agent Execution (v0.3.0+)

Execute an AI agent with MCP tool access on the proxy:

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "agent/execute",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": "Explain the IncentiveProcess apex class"
      }
    ],
    "servers": [
      {
        "serverId": "salesforce-mcp-server",
        "serverName": "Salesforce MCP Server",
        "useMcpJson": true,
        "mcpConfigKey": "salesforce-mcp-server",
        "selectedTools": ["salesforce_read_apex", "salesforce_query_records"]
      }
    ],
    "modelConfig": {
      "provider": "watsonx",
      "modelId": "meta-llama/llama-3-3-70b-instruct",
      "temperature": 0.7,
      "maxTokens": 4096
    }
  }
}

Response stream (multiple messages):

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "content": "Let me read that Apex class for you...",
    "toolCalls": [],
    "isDone": false
  }
}

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "content": "",
    "toolCalls": [
      {
        "id": "call_123",
        "name": "salesforce_read_apex",
        "arguments": { "className": "IncentiveProcess" },
        "result": { "content": [{ "text": "public class IncentiveProcess { ... }" }] },
        "duration": 2357
      }
    ],
    "isDone": false
  }
}

{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "content": "The IncentiveProcess class is a parent class that handles...",
    "toolCalls": [],
    "isDone": true
  }
}

Integration with Playground

Basic Proxy Mode

The playground frontend automatically:

1. Detects local servers without HTTP/WebSocket support
2. Switches to "proxy" connection mode
3. Connects to ws://localhost:8080
4. Registers the server with command/args from config
5. Forwards tool list and call requests through the proxy

Agent Execution Mode (v0.3.0+)

When "Proxy Agent" execution mode is selected:

1. Playground sends agent/execute request with messages and server list
2. Proxy reads mcp.json and spawns MCP servers
3. Agent runs LangGraph ReAct loop with direct tool access
4. Results stream back to browser in real-time
5. No browser bridge - all execution on proxy

No manual configuration needed!

Troubleshooting

Connection Refused

Problem: Browser shows "Failed to connect to proxy"

Solution: Make sure the proxy is running:

fusion-mcp-proxy start

Authentication Failed

Problem: "Authentication required" error

Solution:

• Check if proxy was started with --token
• Verify the token matches in your config

Server Registration Failed

Problem: "Failed to register server" error

Possible causes:

• Invalid command or path
• Missing dependencies for the MCP server
• Insufficient permissions

Debug: Start proxy with --log-level debug to see detailed errors

Port Already in Use

Problem: "EADDRINUSE: address already in use"

Solution:

• Check if another proxy is running: lsof -i :8080
• Kill the process or use a different port: --port 9000

Security Considerations

Local Only (Default)

By default, the proxy binds to localhost and is only accessible from your machine. This is the recommended setup.

Authentication

If you need extra security, use the --token option:

fusion-mcp-proxy start --token $(openssl rand -hex 32)

Save the token and configure it in your playground.

Network Access

Only expose the proxy to your network if you trust all devices on it:

# ⚠️  Use with caution
fusion-mcp-proxy start --host 0.0.0.0

Development

Build from Source

git clone <repo>
cd fusion-mcp-proxy
npm install
npm run build

Run in Dev Mode

npm run dev

Link Globally

npm link
fusion-mcp-proxy start

License

MIT

Support

• GitHub Issues: Report bugs or request features
• Documentation: Full API reference

Made with ❤️ for the MCP community