plugged.in MCP Proxy Server

📋 Overview

The plugged.in MCP Proxy Server is a powerful middleware that aggregates multiple Machine Conversation Protocol (MCP) servers into a single unified interface. It fetches tool, prompt, and resource configurations from the plugged.in App and intelligently routes requests to the appropriate underlying MCP servers.

This proxy enables seamless integration with any MCP client (Claude, Cline, Cursor, etc.) while providing advanced management capabilities through the plugged.in ecosystem.

✨ Key Features

• Universal MCP Compatibility: Works with any MCP client including Claude Desktop, Cline, and Cursor
• Multi-Server Support: Connect both STDIO (command-line) and WebSocket (HTTP-based) MCP servers
• Namespace Isolation: Keep joined MCPs separate and organized with proper prefixing
• Multi-Workspace Layer: Switch between different sets of MCP configurations with one click
• Simplified Architecture: Streamlined codebase with improved startup time and reduced complexity
• API-Driven Proxy: Fetches capabilities from plugged.in App APIs rather than direct discovery
• Full MCP Support: Handles tools, resources, resource templates, and prompts
• Custom Instructions: Supports server-specific instructions formatted as MCP prompts

🚀 Quick Start

Prerequisites

• Node.js 18+ (recommended v20+)
• An API key from the plugged.in App (get one at plugged.in/api-keys)

Installation

# Install and run with npx
npx -y @pluggedin/mcp-proxy@latest --pluggedin-api-key YOUR_API_KEY

Configuration for MCP Clients

Claude Desktop

Add the following to your Claude Desktop configuration:

{
  "mcpServers": {
    "pluggedin": {
      "command": "npx",
      "args": ["-y", "@pluggedin/mcp-proxy@latest"],
      "env": {
        "PLUGGEDIN_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Cline

Add the following to your Cline configuration:

{
  "mcpServers": {
    "pluggedin": {
      "command": "npx",
      "args": ["-y", "@pluggedin/mcp-proxy@latest"],
      "env": {
        "PLUGGEDIN_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Cursor

For Cursor, you can use command-line arguments instead of environment variables:

npx -y @pluggedin/mcp-proxy@latest --pluggedin-api-key YOUR_API_KEY

⚙️ Configuration Options

Environment Variables

Variable	Description	Required	Default
PLUGGEDIN_API_KEY	API key from plugged.in App	Yes	-
PLUGGEDIN_API_BASE_URL	Base URL for plugged.in App	No	https://plugged.in

Command Line Arguments

Command line arguments take precedence over environment variables:

npx -y @pluggedin/mcp-proxy@latest --pluggedin-api-key YOUR_API_KEY --pluggedin-api-base-url https://your-custom-url.com

For a complete list of options:

npx -y @pluggedin/mcp-proxy@latest --help

🐳 Docker Usage

You can also build and run the proxy server using Docker.

Building the Image

Ensure you have Docker installed and running. Navigate to the pluggedin-mcp directory and run:

docker build -t pluggedin-mcp-proxy:latest .

A .dockerignore file is included to optimize the build context.

Running the Container

Run the container, providing the necessary environment variables:

docker run -it --rm \
  -e PLUGGEDIN_API_KEY="YOUR_API_KEY" \
  -e PLUGGEDIN_API_BASE_URL="YOUR_API_BASE_URL" \
  --name pluggedin-mcp-container \
  pluggedin-mcp-proxy:latest

Replace YOUR_API_KEY and YOUR_API_BASE_URL (if not using the default https://plugged.in).

Testing with MCP Inspector

While the container is running, you can connect to it using the MCP Inspector:

npx @modelcontextprotocol/inspector docker://pluggedin-mcp-container

This will connect to the standard input/output of the running container.

Stopping the Container

Press Ctrl+C in the terminal where docker run is executing. The --rm flag ensures the container is removed automatically upon stopping.

🏗️ System Architecture

The plugged.in MCP Proxy Server acts as a bridge between MCP clients and multiple underlying MCP servers:

sequenceDiagram
    participant MCPClient as MCP Client (e.g. Claude Desktop)
    participant PluggedinMCP as plugged.in MCP Proxy
    participant PluggedinApp as plugged.in App
    participant MCPServers as Underlying MCP Servers

    MCPClient ->> PluggedinMCP: Request list tools/resources/prompts
    PluggedinMCP ->> PluggedinApp: Get capabilities via API
    PluggedinApp ->> PluggedinMCP: Return capabilities (prefixed)

    MCPClient ->> PluggedinMCP: Call tool/read resource/get prompt
    alt Standard capability
        PluggedinMCP ->> PluggedinApp: Resolve capability to server
        PluggedinApp ->> PluggedinMCP: Return server details
        PluggedinMCP ->> MCPServers: Forward request to target server
        MCPServers ->> PluggedinMCP: Return response
    else Custom instruction
        PluggedinMCP ->> PluggedinApp: Get custom instruction
        PluggedinApp ->> PluggedinMCP: Return formatted messages
    end
    PluggedinMCP ->> MCPClient: Return response

    alt Discovery tool
        MCPClient ->> PluggedinMCP: Call pluggedin_discover_tools
        PluggedinMCP ->> PluggedinApp: Trigger discovery action
        PluggedinApp ->> MCPServers: Connect and discover capabilities
        MCPServers ->> PluggedinApp: Return capabilities
        PluggedinApp ->> PluggedinMCP: Confirm discovery complete
        PluggedinMCP ->> MCPClient: Return discovery result
    end

🔄 Workflow

1. Configuration: The proxy fetches server configurations from the plugged.in App
2. Capability Listing: The proxy fetches discovered capabilities from plugged.in App APIs
   • tools/list: Fetches from /api/tools (returns prefixed names)
   • resources/list: Fetches from /api/resources
   • resource-templates/list: Fetches from /api/resource-templates
   • prompts/list: Fetches from /api/prompts and /api/custom-instructions, merges results
3. Capability Resolution: The proxy resolves capabilities to target servers
   • tools/call: Parses prefix from tool name, looks up server in internal map
   • resources/read: Calls /api/resolve/resource?uri=... to get server details
   • prompts/get: Checks for custom instruction prefix or calls /api/resolve/prompt?name=...
4. Request Routing: Requests are routed to the appropriate underlying MCP server
5. Response Handling: Responses from the underlying servers are returned to the client

🧩 Integration with plugged.in App

The plugged.in MCP Proxy Server is designed to work seamlessly with the plugged.in App, which provides:

• A web-based interface for managing MCP server configurations
• Centralized capability discovery (Tools, Resources, Templates, Prompts)
• Custom instructions management
• Multi-workspace support for different configuration sets
• An interactive playground for testing MCP tools
• User authentication and API key management

📚 Related Resources

• plugged.in App Repository
• Machine Conversation Protocol (MCP) Specification
• Claude Desktop Documentation
• Cline Documentation

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgements

• Inspired by the MCP Proxy Server
• Built on the Machine Conversation Protocol