plugged.in MCP Proxy Server

📋 Overview

The plugged.in MCP Proxy Server is a powerful middleware that aggregates multiple Model Context 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

Configuration: The proxy fetches server configurations from the plugged.in App
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
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=...
Request Routing: Requests are routed to the appropriate underlying MCP server
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

🤝 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 Model Context Protocol

Plugged.in