What is Pluggedin Mcp Proxy

The plugged.in MCP Proxy Server is a middleware that consolidates multiple Machine Conversation Protocol (MCP) servers into a single interface, enabling efficient management and routing of requests.

Use cases

Use cases include managing multiple AI models, facilitating data exchanges between different MCP clients, and providing a centralized interface for developers to interact with various MCP servers.

How to use

To use plugged.in MCP Proxy, set up the server by configuring it to connect with your desired MCP clients. Utilize the unified interface to manage requests and access various MCP functionalities seamlessly.

Key features

Key features include universal MCP compatibility, multi-server support, namespace isolation, multi-workspace layer, simplified architecture, and an API-driven proxy for enhanced performance.

Where to use

plugged.in MCP Proxy can be utilized in various fields such as AI development, data exchanges, and any application requiring integration of multiple MCP servers for streamlined communication.

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

🚀 Core Capabilities

• 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
• 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

🔔 New in v1.0.0

• Real-Time Notifications: Track all MCP activities with comprehensive notification support
• RAG Integration: Support for document-enhanced queries through the plugged.in App
• Enhanced Security: Industry-standard input validation and sanitization
• Inspector Scripts: Automated testing tools for debugging and development
• Health Monitoring: Built-in ping endpoint for connection monitoring

🚀 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 (latest v1.0.0)
npx -y @pluggedin/mcp-proxy@latest --pluggedin-api-key YOUR_API_KEY

🔄 Upgrading to v1.0.0

For existing installations, see our Migration Guide for detailed upgrade instructions.

# Quick upgrade
npx -y @pluggedin/[email protected] --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

🔒 Security Features

The plugged.in MCP Proxy implements comprehensive security measures to protect your system and data:

Input Validation & Sanitization

• Command Injection Prevention: All commands and arguments are validated against allowlists before execution
• Environment Variable Security: Secure parsing of .env files with proper handling of quotes and multiline values
• Token Validation: Strong regex patterns for API keys and authentication tokens (32-64 hex characters)

Network Security

• SSRF Protection: URL validation blocks access to localhost and private IP ranges
• Rate Limiting:
  • Tool calls: 60 requests per minute
  • API calls: 100 requests per minute
• Error Sanitization: Prevents information disclosure by sanitizing error messages

Process Security

• Safe Command Execution: Uses execFile() instead of exec() to prevent shell injection
• Argument Sanitization: Removes shell metacharacters and control characters from all arguments
• Environment Variable Validation: Only allows alphanumeric keys with underscores

Security Utilities

A dedicated security-utils.ts module provides:

• Bearer token validation
• URL validation with SSRF protection
• Command argument sanitization
• Environment variable validation
• Rate limiting implementation
• Error message sanitization

For detailed security implementation, see SECURITY.md.

🧩 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
• Model Context Protocol (MCP) Specification
• Claude Desktop Documentation
• Cline Documentation

🤝 Contributing

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

📝 Recent Updates

Version 1.0.0 (June 2025)

🎯 Major Features

• Real-Time Notification System: Track all MCP activities with comprehensive notification support
• RAG Integration: Support for document-enhanced queries through the plugged.in App
• Inspector Scripts: New automated testing tools for debugging and development
• Health Monitoring: Built-in ping endpoint for connection monitoring

🔒 Security Enhancements

• Input Validation: Industry-standard validation and sanitization for all inputs
• URL Security: Enhanced URL validation with SSRF protection
• Environment Security: Secure parsing of environment variables with dotenv
• Error Sanitization: Prevents information disclosure in error responses

🐛 Bug Fixes

• Fixed JSON-RPC protocol interference (stdout vs stderr separation)
• Resolved localhost URL validation for development environments
• Fixed API key handling in inspector scripts
• Improved connection stability and memory management

🔧 Developer Tools

• New inspector scripts for automated testing
• Improved error messages and debugging capabilities
• Structured logging with proper stderr usage
• Enhanced TypeScript type safety

See Release Notes for complete details.

📄 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