Skip to content
Back to search

pluggedin-mcp-proxy

Plugged.in MCP Server manages all your other MCPs in one MCP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/veriteknik--pluggedin-mcp-proxy/badge.svg)](/listings/veriteknik--pluggedin-mcp-proxy)

HTML

<a href="/listings/veriteknik--pluggedin-mcp-proxy"><img src="/api/listings/veriteknik--pluggedin-mcp-proxy/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

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

Installation

# Install and run with npx (latest v1.0.0)
npx -y @pluggedin/pluggedin-mcp-proxy@latest --pluggedin-api-key YOUR_API_KEY

๐Ÿ”„ Upgrading to v1.0.0

For existing installations, see our [Migration Guide](./MIGRATION_GUIDE_v1.0.0.md) for detailed upgrade instructions.

# Quick upgrade
npx -y @pluggedin/pluggedin-mcp-proxy@1.0.0 --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/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/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/pluggedin-mcp-proxy@latest --pluggedin-api-key YOUR_API_KEY

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md ยท README ยท 783 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # plugged.in MCP Hub โ€” Proxy ยท Knowledge ยท Memory ยท Tools
  2. <div align="center">
  3. <img src="https://plugged.in/_next/image?url=%2Fpluggedin-wl.png&w=256&q=75" alt="plugged.in Logo" width="256" height="75">
  4. <h3>The Crossroads for AI Data Exchanges</h3>
  5. <p>A unified MCP hub that gives your AI <strong>Knowledge</strong>, <strong>Memory</strong>, and <strong>Tools</strong> โ€” not just a proxy. Manage and test all MCP servers from a single connection while powering document-aware and memory-augmented workflows across clients.</p>
  6. [![smithery badge](https://smithery.ai/badge/@VeriTeknik/pluggedin-mcp)](https://smithery.ai/server/@VeriTeknik/pluggedin-mcp)
  7. [![Version](https://img.shields.io/badge/version-1.9.0-blue?style=for-the-badge)](https://github.com/VeriTeknik/pluggedin-mcp/releases)
  8. [![GitHub Stars](https://img.shields.io/github/stars/VeriTeknik/pluggedin-mcp?style=for-the-badge)](https://github.com/VeriTeknik/pluggedin-mcp/stargazers)
  9. [![License](https://img.shields.io/github/license/VeriTeknik/pluggedin-mcp?style=for-the-badge)](LICENSE)
  10. [![TypeScript](https://img.shields.io/badge/TypeScript-4.9+-blue?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org/)
  11. [![MCP](https://img.shields.io/badge/MCP-Compatible-green?style=for-the-badge)](https://modelcontextprotocol.io/)
  12. [![MCP Badge](https://lobehub.com/badge/mcp/veriteknik-pluggedin-mcp)](https://lobehub.com/mcp/veriteknik-pluggedin-mcp)
  13. </div>
  14. ## ๐Ÿ“‹ Overview
  15. 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](https://github.com/VeriTeknik/pluggedin-app) and intelligently routes requests to the appropriate underlying MCP servers.
  16. This proxy enables seamless integration with any MCP client (Claude, Cline, Cursor, etc.) while providing advanced management capabilities through the plugged.in ecosystem.
  17. ## Hub Pillars: Knowledge ยท Memory ยท Tools ยท Proxy
  18. **Knowledge (RAG v2 / AI Document Exchange)**
  19. Search and ground model outputs with unified, attributionโ€‘aware document retrieval. MCP servers can create and manage documents in your library with versioning, visibility controls, and model attribution. Use the builtโ€‘in RAG to search across all connected sources and return relevant snippets and metadata.
  20. **Memory (Persistent AI Memory)**
  21. Longโ€‘lived, workspace/profileโ€‘scoped memory that survives sessions. The hub integrates with the plugged.in App's persistent memory so agent actions and insights can be stored and recalled across tasks. Builtโ€‘in memory tools are on the roadmap to expose lowโ€‘friction `get/put/search` patterns under the same auth model.
  22. **Tools**
  23. Aggregate builtโ€‘in capabilities with downstream MCP servers (STDIO, SSE, Streamable HTTP). Tool discovery is cached and can be refreshed on demand; hubโ€‘level discovery returns a unified catalog for any MCP client. The hub supports tools, resources, resource templates, and prompts.
  24. **Proxy**
  25. One connection for every client. Run as STDIO (default) or Streamable HTTP with optional API auth and stateless mode. Works with Claude Desktop, Cline, Cursor, MCP Inspector, and more; keep your existing client configs while centralizing policies and telemetry.
  26. > โญ **If you find this project useful, please consider giving it a star on GitHub!** It helps us reach more developers and motivates us to keep improving.
  27. ## โœจ Key Features
  28. ### ๐Ÿš€ Core Capabilities
  29. - **Built-in AI Playground**: Test your MCPs instantly with Claude, Gemini, OpenAI, and xAI without any client setup
  30. - **Universal MCP Compatibility**: Works with any MCP client including Claude Desktop, Cline, and Cursor
  31. - **Multi-Server Support**: Connect to STDIO, SSE, and Streamable HTTP MCP servers
  32. - **Dual Transport Modes**: Run proxy as STDIO (default) or Streamable HTTP server
  33. - **Unified Document Search**: Search across all connected servers with built-in RAG capabilities
  34. - **AI Document Exchange (RAG v2)**: MCP servers can create and manage documents in your library with full attribution
  35. - **Notifications from Any Model**: Receive real-time notifications with optional email delivery
  36. - **Multi-Workspace Layer**: Switch between different sets of MCP configurations with one click
  37. - **API-Driven Proxy**: Fetches capabilities from plugged.in App APIs rather than direct discovery
  38. - **Full MCP Support**: Handles tools, resources, resource templates, and prompts
  39. - **Custom Instructions**: Supports server-specific instructions formatted as MCP prompts
  40. ### ๐ŸŽฏ New in v1.5.0 (RAG v2 - AI Document Exchange)
  41. - **AI Document Creation**: MCP servers can now create documents directly in your library
  42. - Full model attribution tracking (which AI created/updated the document)
  43. - Version history with change tracking
  44. - Content deduplication via SHA-256 hashing
  45. - Support for multiple formats: MD, TXT, JSON, HTML, PDF, and more
  46. - **Advanced Document Search**: Enhanced RAG queries with AI filtering
  47. - Filter by AI model, provider, date range, tags, and source type
  48. - Semantic search with relevance scoring
  49. - Automatic snippet generation with keyword highlighting
  50. - Support for filtering: `ai_generated`, `upload`, or `api` sources
  51. - **Document Management via MCP**:
  52. - Set document visibility: private, workspace, or public
  53. - Parent-child relationships for document versions
  54. - Profile-based organization alongside project-based scoping
  55. - Real-time progress tracking for document processing
  56. ### ๐ŸŽฏ Features from v1.4.0 (Registry v2 Support)
  57. - **OAuth Token Management**: Seamless OAuth authentication handling for Streamable HTTP MCP servers
  58. - Automatic token retrieval from plugged.in App
  59. - Secure token storage and refresh mechanisms
  60. - No client-side authentication needed
  61. - **Enhanced Notification System**: Bidirectional notification support
  62. - Send notifications to plugged.in App
  63. - Receive notifications from MCP servers
  64. - Mark notifications as read/unread
  65. - Delete notifications programmatically
  66. - **Trending Analytics**: Real-time activity tracking
  67. - Every tool call is logged and tracked
  68. - Contributes to trending server calculations
  69. - Usage metrics and popularity insights
  70. - **Registry Integration**: Full support for Registry v2 features
  71. - Automatic server discovery from registry
  72. - Installation tracking and metrics
  73. - Community server support
  74. ### ๐Ÿ“ฆ Features from v1.1.0
  75. - **Streamable HTTP Support**: Full support for downstream MCP servers using Streamable HTTP transport
  76. - **HTTP Server Mode**: Run the proxy as an HTTP server with configurable ports
  77. - **Flexible Authentication**: Optional Bearer token authentication for HTTP endpoints
  78. - **Session Management**: Choose between stateful (session-based) or stateless operation modes
  79. ### ๐ŸŽฏ Core Features from v1.0.0
  80. - **Real-Time Notifications**: Track all MCP activities with comprehensive notification support
  81. - **RAG Integration**: Support for document-enhanced queries through the plugged.in App
  82. - **Inspector Scripts**: Automated testing tools for debugging and development
  83. - **Health Monitoring**: Built-in ping endpoint for connection monitoring
  84. ## ๐Ÿ”ง Tool Categories
  85. The proxy provides two distinct categories of tools:
  86. ### ๐Ÿ”ง Static Built-in Tools (Always Available)
  87. These tools are built into the proxy and work without any server configuration:
  88. - **`pluggedin_discover_tools`** - Smart discovery with caching for instant results
  89. - **`pluggedin_ask_knowledge_base`** - RAG search across your documents with AI filtering capabilities
  90. - **`pluggedin_send_notification`** - Send notifications with optional email delivery
  91. - **`pluggedin_create_document`** - Create AI-generated documents in your library
  92. - **`pluggedin_list_documents`** - List documents with filtering options
  93. - **`pluggedin_search_documents`** - Search for specific documents by query
  94. - **`pluggedin_get_document`** - Retrieve a specific document's full content by ID
  95. - **`pluggedin_update_document`** - Update or append to an existing document
  96. #### ๐Ÿ“‹ Clipboard Tools (Memory System)
  97. - **`pluggedin_clipboard_set`** - Set a clipboard entry by name (semantic key) or index
  98. - **`pluggedin_clipboard_get`** - Get clipboard entries by name, index, or list all
  99. - **`pluggedin_clipboard_delete`** - Delete clipboard entries by name, index, or clear all
  100. - **`pluggedin_clipboard_list`** - List all clipboard entries with metadata
  101. - **`pluggedin_clipboard_push`** - Push a value with auto-incrementing index (stack push)
  102. - **`pluggedin_clipboard_pop`** - Pop the highest-indexed entry (LIFO behavior)
  103. ### โšก Dynamic MCP Tools (From Connected Servers)
  104. These tools come from your configured MCP servers and can be turned on/off:
  105. - Database tools (PostgreSQL, SQLite, etc.)
  106. - File system tools
  107. - API integration tools
  108. - Custom tools from any MCP server
  109. The discovery tool intelligently shows both categories, giving AI models immediate access to all available capabilities.
  110. ### ๐Ÿš€ Discovery Tool Usage
  111. ```bash
  112. # Quick discovery - returns cached data instantly
  113. pluggedin_discover_tools()
  114. # Force refresh - shows current tools + runs background discovery
  115. pluggedin_discover_tools({"force_refresh": true})
  116. # Discover specific server
  117. pluggedin_discover_tools({"server_uuid": "uuid-here"})
  118. ```
  119. **Example Response:**
  120. ```
  121. ## ๐Ÿ”ง Static Built-in Tools (Always Available):
  122. 1. **pluggedin_discover_tools** - Smart discovery with caching
  123. 2. **pluggedin_rag_query** - RAG v2 search across documents with AI filtering
  124. 3. **pluggedin_send_notification** - Send notifications
  125. 4. **pluggedin_create_document** - (Coming Soon) Create AI-generated documents
  126. ## โšก Dynamic MCP Tools (8) - From Connected Servers:
  127. 1. **query** - Run read-only SQL queries
  128. 2. **generate_random_integer** - Generate secure random integers
  129. ...
  130. ```
  131. ### ๐Ÿ“‹ Clipboard Usage Examples
  132. The clipboard system provides persistent memory for AI workflows:
  133. ```bash
  134. # Store a named entry (upserts if exists)
  135. pluggedin_clipboard_set({
  136. "name": "customer_context",
  137. "value": "{\"name\": \"John Doe\", \"account_id\": \"12345\"}",
  138. "contentType": "application/json"
  139. })
  140. # Store an indexed entry for ordered pipelines
  141. pluggedin_clipboard_set({
  142. "idx": 0,
  143. "value": "First pipeline step result",
  144. "createdByTool": "data_processor"
  145. })
  146. # Push to stack (auto-incrementing index)
  147. pluggedin_clipboard_push({
  148. "value": "Analysis result from step 1",
  149. "contentType": "text/plain"
  150. })
  151. # Get a specific entry by name
  152. pluggedin_clipboard_get({"name": "customer_context"})
  153. # Pop from stack (LIFO - returns and removes highest index)
  154. pluggedin_clipboard_pop()
  155. # List all entries with metadata
  156. pluggedin_clipboard_list({"limit": 20})
  157. # Delete specific entry
  158. pluggedin_clipboard_delete({"name": "customer_context"})
  159. # Clear all clipboard entries
  160. pluggedin_clipboard_delete({"clearAll": true})
  161. ```
  162. ### ๐Ÿ“š RAG v2 Usage Examples
  163. The enhanced RAG v2 system allows MCP servers to create and search documents with full AI attribution:
  164. ```bash
  165. # Search for documents created by specific AI models
  166. pluggedin_rag_query({
  167. "query": "system architecture",
  168. "filters": {
  169. "modelName": "Claude 3 Opus",
  170. "source": "ai_generated",
  171. "tags": ["technical"]
  172. }
  173. })
  174. # Search across all document sources
  175. pluggedin_rag_query({
  176. "query": "deployment guide",
  177. "filters": {
  178. "dateFrom": "2024-01-01",
  179. "visibility": "workspace"
  180. }
  181. })
  182. # Future: Create AI-generated documents (Coming Soon)
  183. pluggedin_create_document({
  184. "title": "Analysis Report",
  185. "content": "# Market Analysis\n\nDetailed findings...",
  186. "format": "md",
  187. "tags": ["analysis", "market"],
  188. "metadata": {
  189. "model": {
  190. "name": "Claude 3 Opus",
  191. "provider": "Anthropic"
  192. }
  193. }
  194. })
  195. ```
  196. ## ๐Ÿš€ Quick Start
  197. ### Prerequisites
  198. - Node.js 18+ (recommended v20+)
  199. - An API key from the plugged.in App (get one at [plugged.in/api-keys](https://plugged.in/api-keys))
  200. ### Installation
  201. ```bash
  202. # Install and run with npx (latest v1.0.0)
  203. npx -y @pluggedin/pluggedin-mcp-proxy@latest --pluggedin-api-key YOUR_API_KEY
  204. ```
  205. ### ๐Ÿ”„ Upgrading to v1.0.0
  206. For existing installations, see our [Migration Guide](./MIGRATION_GUIDE_v1.0.0.md) for detailed upgrade instructions.
  207. ```bash
  208. # Quick upgrade
  209. npx -y @pluggedin/pluggedin-mcp-proxy@1.0.0 --pluggedin-api-key YOUR_API_KEY
  210. ```
  211. ### Configuration for MCP Clients
  212. #### Claude Desktop
  213. Add the following to your Claude Desktop configuration:
  214. ```json
  215. {
  216. "mcpServers": {
  217. "pluggedin": {
  218. "command": "npx",
  219. "args": ["-y", "@pluggedin/pluggedin-mcp-proxy@latest"],
  220. "env": {
  221. "PLUGGEDIN_API_KEY": "YOUR_API_KEY"
  222. }
  223. }
  224. }
  225. }
  226. ```
  227. #### Cline
  228. Add the following to your Cline configuration:
  229. ```json
  230. {
  231. "mcpServers": {
  232. "pluggedin": {
  233. "command": "npx",
  234. "args": ["-y", "@pluggedin/pluggedin-mcp-proxy@latest"],
  235. "env": {
  236. "PLUGGEDIN_API_KEY": "YOUR_API_KEY"
  237. }
  238. }
  239. }
  240. }
  241. ```
  242. #### Cursor
  243. For Cursor, you can use command-line arguments instead of environment variables:
  244. ```bash
  245. npx -y @pluggedin/pluggedin-mcp-proxy@latest --pluggedin-api-key YOUR_API_KEY
  246. ```
  247. ## โš™๏ธ Configuration Options
  248. ### Environment Variables
  249. | Variable | Description | Required | Default |
  250. |----------|-------------|----------|---------|
  251. | `PLUGGEDIN_API_KEY` | API key from plugged.in App | Yes | - |
  252. | `PLUGGEDIN_API_BASE_URL` | Base URL for plugged.in App | No | `https://plugged.in` |
  253. ### Command Line Arguments
  254. Command line arguments take precedence over environment variables:
  255. ```bash
  256. npx -y @pluggedin/pluggedin-mcp-proxy@latest --pluggedin-api-key YOUR_API_KEY --pluggedin-api-base-url https://your-custom-url.com
  257. ```
  258. #### Transport Options
  259. | Option | Description | Default |
  260. |--------|-------------|---------|
  261. | `--transport <type>` | Transport type: `stdio` or `streamable-http` | `stdio` |
  262. | `--port <number>` | Port for Streamable HTTP server | `12006` |
  263. | `--stateless` | Enable stateless mode for Streamable HTTP | `false` |
  264. | `--require-api-auth` | Require API key for Streamable HTTP requests | `false` |
  265. For a complete list of options:
  266. ```bash
  267. npx -y @pluggedin/pluggedin-mcp-proxy@latest --help
  268. ```
  269. ## ๐ŸŒ Streamable HTTP Mode
  270. The proxy can run as an HTTP server instead of STDIO, enabling web-based access and remote connections.
  271. ### Basic Usage
  272. ```bash
  273. # Run as HTTP server on default port (12006)
  274. npx -y @pluggedin/pluggedin-mcp-proxy@latest --transport streamable-http --pluggedin-api-key YOUR_API_KEY
  275. # Custom port
  276. npx -y @pluggedin/pluggedin-mcp-proxy@latest --transport streamable-http --port 8080 --pluggedin-api-key YOUR_API_KEY
  277. # With authentication required
  278. npx -y @pluggedin/pluggedin-mcp-proxy@latest --transport streamable-http --require-api-auth --pluggedin-api-key YOUR_API_KEY
  279. # Stateless mode (new session per request)
  280. npx -y @pluggedin/pluggedin-mcp-proxy@latest --transport streamable-http --stateless --pluggedin-api-key YOUR_API_KEY
  281. ```
  282. ### HTTP Endpoints
  283. - `POST /mcp` - Send MCP messages
  284. - `GET /mcp` - Server-sent events stream (optional)
  285. - `DELETE /mcp` - Terminate session
  286. - `GET /health` - Health check endpoint
  287. ### Session Management
  288. In stateful mode (default), use the `mcp-session-id` header to maintain sessions:
  289. ```bash
  290. # First request creates a session
  291. curl -X POST http://localhost:12006/mcp \
  292. -H "Content-Type: application/json" \
  293. -H "Accept: application/json, text/event-stream" \
  294. -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
  295. # Subsequent requests use the same session
  296. curl -X POST http://localhost:12006/mcp \
  297. -H "Content-Type: application/json" \
  298. -H "Accept: application/json, text/event-stream" \
  299. -H "mcp-session-id: YOUR_SESSION_ID" \
  300. -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"tool_name"},"id":2}'
  301. ```
  302. ### Authentication
  303. When using `--require-api-auth`, include your API key as a Bearer token:
  304. ```bash
  305. curl -X POST http://localhost:12006/mcp \
  306. -H "Authorization: Bearer YOUR_API_KEY" \
  307. -H "Content-Type: application/json" \
  308. -H "Accept: application/json, text/event-stream" \
  309. -d '{"jsonrpc":"2.0","method":"ping","id":1}'
  310. ```
  311. ## ๐Ÿณ Docker Usage
  312. You can also build and run the proxy server using Docker.
  313. ### Building the Image
  314. Ensure you have Docker installed and running. Navigate to the `pluggedin-mcp` directory and run:
  315. ```bash
  316. docker build -t pluggedin-mcp-proxy:latest .
  317. ```
  318. A `.dockerignore` file is included to optimize the build context.
  319. ### Running the Container
  320. #### STDIO Mode (Default)
  321. Run the container in STDIO mode for MCP Inspector testing:
  322. ```bash
  323. docker run -it --rm \
  324. -e PLUGGEDIN_API_KEY="YOUR_API_KEY" \
  325. -e PLUGGEDIN_API_BASE_URL="YOUR_API_BASE_URL" \
  326. --name pluggedin-mcp-container \
  327. pluggedin-mcp-proxy:latest
  328. ```
  329. #### Streamable HTTP Mode
  330. Run the container as an HTTP server:
  331. ```bash
  332. docker run -d --rm \
  333. -e PLUGGEDIN_API_KEY="YOUR_API_KEY" \
  334. -e PLUGGEDIN_API_BASE_URL="YOUR_API_BASE_URL" \
  335. -p 12006:12006 \
  336. --name pluggedin-mcp-http \
  337. pluggedin-mcp-proxy:latest \
  338. --transport streamable-http --port 12006
  339. ```
  340. Replace `YOUR_API_KEY` and `YOUR_API_BASE_URL` (if not using the default `https://plugged.in`).
  341. ### Testing with MCP Inspector
  342. While the container is running, you can connect to it using the MCP Inspector:
  343. ```bash
  344. npx @modelcontextprotocol/inspector docker://pluggedin-mcp-container
  345. ```
  346. This will connect to the standard input/output of the running container.
  347. ### Stopping the Container
  348. Press `Ctrl+C` in the terminal where `docker run` is executing. The `--rm` flag ensures the container is removed automatically upon stopping.
  349. ## โ˜๏ธ Smithery Cloud Deployment
  350. Deploy the plugged.in MCP Proxy to [Smithery Cloud](https://smithery.ai) for hosted, always-available access to your MCP servers.
  351. ### Quick Start
  352. 1. Visit [smithery.ai](https://smithery.ai) and sign in
  353. 2. Connect your GitHub account and select the `pluggedin-mcp` repository
  354. 3. Configure your Plugged.in API key in the Smithery UI
  355. 4. Deploy and get your HTTPS endpoint
  356. ### Benefits
  357. - **24/7 Availability**: Your proxy is always running
  358. - **Zero Configuration**: Smithery auto-detects settings from `smithery.yaml`
  359. - **Automatic Scaling**: Handle multiple concurrent connections
  360. - **Web Access**: Perfect for web applications and remote clients
  361. ### Documentation
  362. For complete deployment instructions, configuration options, troubleshooting, and technical details, see:
  363. **๐Ÿ“– [Smithery Deployment Guide](docs/SMITHERY_DEPLOYMENT.md)**
  364. ## Autonomous Agents (Preview)
  365. The hub is designed to support agentic loops endโ€‘toโ€‘end:
  366. ```
  367. MCP Client โ†’ plugged.in MCP Hub โ†’ (Plan โ†’ Act โ†’ Reflect)
  368. โ†˜ Knowledge โ†˜ Memory โ†˜ Tools
  369. ```
  370. - Plan โ€” derive goals and constraints, form task graphs.
  371. - Act โ€” call tools from the unified catalog; route safely across STDIO/SSE/HTTP servers.
  372. - Reflect โ€” persist outcomes into Memory and Knowledge (documents, notes, artifacts) to improve subsequent steps.
  373. **Safety & Ops**
  374. Enable `--require-api-auth` in Streamable HTTP mode; use allowlists for commands, arguments, and env. Combine serverโ€‘level validation with clientโ€‘side prompts hardened against promptโ€‘injection. Leverage existing logging/telemetry to track tool usage and document mutations.
  375. ## ๐Ÿ—๏ธ System Architecture
  376. The plugged.in MCP Proxy Server acts as a bridge between MCP clients and multiple underlying MCP servers:
  377. ```mermaid
  378. sequenceDiagram
  379. participant MCPClient as MCP Client (e.g. Claude Desktop)
  380. participant PluggedinMCP as plugged.in MCP Proxy
  381. participant PluggedinApp as plugged.in App
  382. participant MCPServers as Underlying MCP Servers
  383. MCPClient ->> PluggedinMCP: Request list tools/resources/prompts
  384. PluggedinMCP ->> PluggedinApp: Get capabilities via API
  385. PluggedinApp ->> PluggedinMCP: Return capabilities (prefixed)
  386. MCPClient ->> PluggedinMCP: Call tool/read resource/get prompt
  387. alt Standard capability
  388. PluggedinMCP ->> PluggedinApp: Resolve capability to server
  389. PluggedinApp ->> PluggedinMCP: Return server details
  390. PluggedinMCP ->> MCPServers: Forward request to target server
  391. MCPServers ->> PluggedinMCP: Return response
  392. else Custom instruction
  393. PluggedinMCP ->> PluggedinApp: Get custom instruction
  394. PluggedinApp ->> PluggedinMCP: Return formatted messages
  395. end
  396. PluggedinMCP ->> MCPClient: Return response
  397. alt Discovery tool (Smart Caching)
  398. MCPClient ->> PluggedinMCP: Call pluggedin_discover_tools
  399. alt Cached data available
  400. PluggedinMCP ->> PluggedinApp: Check cached capabilities
  401. PluggedinApp ->> PluggedinMCP: Return cached tools/resources/prompts
  402. PluggedinMCP ->> MCPClient: Return instant results (static + dynamic)
  403. else Force refresh or no cache
  404. PluggedinMCP ->> PluggedinApp: Trigger background discovery
  405. PluggedinMCP ->> MCPClient: Return current tools + "discovery running"
  406. PluggedinApp ->> MCPServers: Connect and discover capabilities (background)
  407. MCPServers ->> PluggedinApp: Return fresh capabilities
  408. end
  409. end
  410. ```
  411. ## ๐Ÿ”„ Workflow
  412. 1. **Configuration**: The proxy fetches server configurations from the plugged.in App
  413. 2. **Smart Discovery** (`pluggedin_discover_tools`):
  414. - **Cache Check**: First checks for existing cached data (< 1 second)
  415. - **Instant Response**: Returns static tools + cached dynamic tools immediately
  416. - **Background Refresh**: For `force_refresh=true`, runs discovery in background while showing current tools
  417. - **Fresh Discovery**: Only runs full discovery if no cached data exists
  418. 3. **Capability Listing**: The proxy fetches discovered capabilities from plugged.in App APIs
  419. - `tools/list`: Fetches from `/api/tools` (includes static + dynamic tools)
  420. - `resources/list`: Fetches from `/api/resources`
  421. - `resource-templates/list`: Fetches from `/api/resource-templates`
  422. - `prompts/list`: Fetches from `/api/prompts` and `/api/custom-instructions`, merges results
  423. 4. **Capability Resolution**: The proxy resolves capabilities to target servers
  424. - `tools/call`: Parses prefix from tool name, looks up server in internal map
  425. - `resources/read`: Calls `/api/resolve/resource?uri=...` to get server details
  426. - `prompts/get`: Checks for custom instruction prefix or calls `/api/resolve/prompt?name=...`
  427. 5. **Request Routing**: Requests are routed to the appropriate underlying MCP server
  428. 6. **Response Handling**: Responses from the underlying servers are returned to the client
  429. ## ๐Ÿ”’ Security Features
  430. The plugged.in MCP Proxy implements comprehensive security measures to protect your system and data:
  431. ### Input Validation & Sanitization
  432. - **Command Injection Prevention**: All commands and arguments are validated against allowlists before execution
  433. - **Environment Variable Security**: Secure parsing of `.env` files with proper handling of quotes and multiline values
  434. - **Token Validation**: Strong regex patterns for API keys and authentication tokens (32-64 hex characters)
  435. ### Network Security
  436. - **SSRF Protection**: URL validation blocks access to:
  437. - Localhost and loopback addresses (127.0.0.1, ::1)
  438. - Private IP ranges (10.x, 172.16-31.x, 192.168.x)
  439. - Link-local addresses (169.254.x)
  440. - Multicast and reserved ranges
  441. - Common internal service ports (SSH, databases, etc.)
  442. - **Header Validation**: Protection against header injection with:
  443. - Dangerous header blocking
  444. - RFC 7230 compliant header name validation
  445. - Control character detection
  446. - Header size limits (8KB max)
  447. - **Rate Limiting**:
  448. - Tool calls: 60 requests per minute
  449. - API calls: 100 requests per minute
  450. - **Error Sanitization**: Prevents information disclosure by sanitizing error messages
  451. ### Process Security
  452. - **Safe Command Execution**: Uses `execFile()` instead of `exec()` to prevent shell injection
  453. - **Command Allowlist**: Only permits execution of:
  454. - `node`, `npx` - Node.js commands
  455. - `python`, `python3` - Python commands
  456. - `uv`, `uvx`, `uvenv` - UV Python tools
  457. - **Argument Sanitization**: Removes shell metacharacters and control characters from all arguments
  458. - **Environment Variable Validation**: Only allows alphanumeric keys with underscores
  459. ### Streamable HTTP Security
  460. - **Lazy Authentication**: Tool discovery doesn't require authentication, improving compatibility
  461. - **Session Security**: Cryptographically secure session ID generation
  462. - **CORS Protection**: Configurable CORS headers for web access
  463. - **Request Size Limits**: Prevents DoS through large payloads
  464. ### Security Utilities
  465. A dedicated `security-utils.ts` module provides:
  466. - Bearer token validation
  467. - URL validation with SSRF protection
  468. - Command argument sanitization
  469. - Environment variable validation
  470. - Rate limiting implementation
  471. - Error message sanitization
  472. For detailed security implementation, see [SECURITY.md](SECURITY.md).
  473. ## ๐Ÿงฉ Integration with plugged.in App
  474. The plugged.in MCP Proxy Server is designed to work seamlessly with the [plugged.in App](https://github.com/VeriTeknik/pluggedin-app), which provides:
  475. - A web-based interface for managing MCP server configurations
  476. - Centralized capability discovery (Tools, Resources, Templates, Prompts)
  477. - **RAG v2 Document Library**: Upload documents and enable AI-generated content with full attribution
  478. - Custom instructions management
  479. - Multi-workspace support for different configuration sets
  480. - An interactive playground for testing MCP tools with any AI model
  481. - User authentication and API key management
  482. - **AI Document Exchange**: Create, search, and manage documents with model attribution tracking
  483. ## ๐Ÿ“š Related Resources
  484. - [plugged.in App Repository](https://github.com/VeriTeknik/pluggedin-app)
  485. - [Model Context Protocol (MCP) Specification](https://modelcontextprotocol.io/)
  486. - [Claude Desktop Documentation](https://docs.anthropic.com/claude/docs/claude-desktop)
  487. - [Cline Documentation](https://docs.cline.bot/)
  488. ## ๐Ÿค Contributing
  489. Contributions are welcome! Please feel free to submit a Pull Request.
  490. ## ๐Ÿ“ Recent Updates
  491. ### Version 1.9.0 (September 2025) - Security Enhancements
  492. #### ๐Ÿ”’ Enhanced HTML Sanitization
  493. - **Industry-Standard Sanitization**: Replaced custom regex-based HTML sanitization with `sanitize-html` library
  494. - **XSS Prevention**: Comprehensive protection against cross-site scripting attacks
  495. - **HTML Attribute Security**: Enhanced sanitization for HTML attribute contexts (quotes, ampersands)
  496. - **Format String Injection**: Fixed format string injection vulnerabilities in logging
  497. - **Security Testing**: Comprehensive test coverage for all sanitization functions
  498. #### ๐Ÿ›ก๏ธ Security Improvements
  499. - **CodeQL Compliance**: Resolved all security vulnerabilities identified by GitHub CodeQL analysis
  500. - **Input Validation**: Strengthened input validation and sanitization across all functions
  501. - **Dependency Updates**: Added `sanitize-html` for robust HTML content filtering
  502. - **Test Coverage**: Enhanced security test suite with XSS attack prevention verification
  503. ### Version 1.5.0 (January 2025) - RAG v2
  504. #### ๐Ÿค– AI Document Exchange
  505. - **AI-Generated Documents**: MCP servers can now create documents in your library with full AI attribution
  506. - **Model Attribution Tracking**: Complete history of which AI models created or updated each document
  507. - **Advanced Document Search**: Filter by AI model, provider, date, tags, and source type
  508. - **Document Versioning**: Track changes and maintain version history for AI-generated content
  509. - **Multi-Source Support**: Documents from uploads, AI generation, or API integrations
  510. #### ๐Ÿ” Enhanced RAG Capabilities
  511. - **Semantic Search**: Improved relevance scoring with PostgreSQL full-text search
  512. - **Smart Filtering**: Filter results by visibility, model attribution, and document source
  513. - **Snippet Generation**: Automatic snippet extraction with keyword highlighting
  514. - **Performance Optimization**: Faster queries with optimized indexing
  515. ### Version 1.2.0 (January 2025)
  516. #### ๐Ÿ”’ Security Enhancements
  517. - **URL Validation**: Comprehensive SSRF protection blocking private IPs, localhost, and dangerous ports
  518. - **Command Allowlisting**: Only approved commands (node, npx, python, etc.) can be executed
  519. - **Header Sanitization**: Protection against header injection attacks
  520. - **Lazy Authentication**: Improved Smithery compatibility with auth-free tool discovery
  521. #### ๐Ÿš€ Performance Improvements
  522. - **Optimized Docker Builds**: Multi-stage builds for minimal container footprint
  523. - **Production Dependencies Only**: Test files and dev dependencies excluded from Docker images
  524. - **Resource Efficiency**: Designed for deployment in resource-constrained environments
  525. #### ๐Ÿ”ง Technical Improvements
  526. - Enhanced error handling in Streamable HTTP transport
  527. - Better session cleanup and memory management
  528. - Improved TypeScript types and code organization
  529. ### Version 1.1.0 (December 2024)
  530. #### ๐Ÿš€ New Features
  531. - **Streamable HTTP Support**: Connect to downstream MCP servers using the modern Streamable HTTP transport
  532. - **HTTP Server Mode**: Run the proxy as an HTTP server for web-based access
  533. - **Flexible Session Management**: Choose between stateless or stateful modes
  534. - **Authentication Options**: Optional Bearer token authentication for HTTP endpoints
  535. - **Health Monitoring**: `/health` endpoint for service monitoring
  536. #### ๐Ÿ”ง Technical Improvements
  537. - Updated MCP SDK to v1.13.1 for latest protocol support
  538. - Added Express.js integration for HTTP server functionality
  539. - Enhanced TypeScript types for better developer experience
  540. ### Version 1.0.0 (June 2025)
  541. #### ๐ŸŽฏ Major Features
  542. - **Real-Time Notification System**: Track all MCP activities with comprehensive notification support
  543. - **RAG Integration**: Support for document-enhanced queries through the plugged.in App
  544. - **Inspector Scripts**: New automated testing tools for debugging and development
  545. - **Health Monitoring**: Built-in ping endpoint for connection monitoring
  546. #### ๐Ÿ”’ Security Enhancements
  547. - **Input Validation**: Industry-standard validation and sanitization for all inputs
  548. - **URL Security**: Enhanced URL validation with SSRF protection
  549. - **Environment Security**: Secure parsing of environment variables with dotenv
  550. - **Error Sanitization**: Prevents information disclosure in error responses
  551. #### ๐Ÿ› Bug Fixes
  552. - Fixed JSON-RPC protocol interference (stdout vs stderr separation)
  553. - Resolved localhost URL validation for development environments
  554. - Fixed API key handling in inspector scripts
  555. - Improved connection stability and memory management
  556. #### ๐Ÿ”ง Developer Tools
  557. - New inspector scripts for automated testing
  558. - Improved error messages and debugging capabilities
  559. - Structured logging with proper stderr usage
  560. - Enhanced TypeScript type safety
  561. See [Release Notes](./RELEASE_NOTES_v1.0.0.md) for complete details.
  562. ## ๐Ÿงช Testing and Development
  563. ### Local Development
  564. Tests are included for development purposes but are excluded from Docker builds to minimize the container footprint.
  565. ```bash
  566. # Run tests locally
  567. npm test
  568. # or
  569. ./scripts/test-local.sh
  570. # Run tests in watch mode
  571. npm run test:watch
  572. # Run tests with UI
  573. npm run test:ui
  574. ```
  575. ### Lightweight Docker Builds
  576. The Docker image is optimized for minimal footprint:
  577. - Multi-stage build process
  578. - Only production dependencies in final image
  579. - Test files and dev dependencies excluded
  580. - Optimized for resource-constrained environments
  581. ```bash
  582. # Build optimized Docker image
  583. docker build -t pluggedin-mcp .
  584. # Check image size
  585. docker images pluggedin-mcp
  586. ```
  587. ## ๐Ÿ“„ License
  588. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  589. ## ๐Ÿ™ Acknowledgements
  590. - Inspired by the [MCP Proxy Server](https://github.com/adamwattis/mcp-proxy-server/)
  591. - Built on the [Model Context Protocol](https://modelcontextprotocol.io/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If itโ€™s helped, pass it on.