Skip to main content

​
Plugged.in MCP Proxy

The Plugged.in MCP Proxy is your single connection point to every MCP server defined in your Plugged.in workspace. It pulls configuration from the Plugged.in API, normalises capability names, and adds knowledge-base and notification tooling so any MCP client can act on your data.
Use the proxy when you want Claude, Cline, Cursor, Smithery, or any other MCP-compatible client to talk to multiple servers without bespoke configuration.

​
Core responsibilities

  • Fetch server definitions, instructions, and static prompts from Plugged.in using PLUGGEDIN_API_KEY.
  • Expose every discovered tool, resource, and prompt to the connected MCP client.
  • Provide Plugged.in-specific static tools—discovery, notifications, and document management—alongside downstream servers.
  • Prefix tool names with their server UUID to prevent collisions (override with PLUGGEDIN_UUID_TOOL_PREFIXING=false if required).
  • Run in STDIO mode for desktop clients or as a Streamable HTTP service for remote consumers.

​
Request lifecycle

1

Client request

The MCP client asks for tools/resources/prompts or invokes an operation through STDIO or HTTP.
2

Workspace lookup

The proxy validates your API key, then queries the Plugged.in API. Responses are cached for 1 second to keep calls fast while reflecting recent changes.
3

Routing

Based on the capability metadata, the proxy either calls the downstream MCP server (STDIO, SSE, Streamable HTTP) or serves a Plugged.in static tool.
4

Response shaping

Results are normalised, prefixed, and returned to the MCP client. Knowledge-base answers include document IDs and snippets; notifications include severity metadata.

​
Transport modes

Streamable HTTP supports session stickiness by default. Pass --stateless when you want a fresh transport per request (useful for serverless deployments). Add --require-api-auth to enforce Authorization: Bearer <PLUGGEDIN_API_KEY>.

​
Built-in Plugged.in tool surface

Every MCP server you add through the Plugged.in UI is surfaced alongside these static tools. In clients you will see them labeled with their UUID-prefixed names under the external tools section, complete with the instructions, prompts, and resources you configured in the dashboard. All other tools/resources/prompts originate from the MCP servers you register in the Plugged.in app. The proxy automatically maps UUID-prefixed tool names back to their original identifiers when forwarding requests.

​
Integration with the Plugged.in app

  • Create and manage servers under MCP Servers in Plugged.in; the proxy reads the API on demand.
  • The proxy sanitises environment variables and command arguments before spawning STDIO servers.
  • Server metadata includes transport type, custom headers, session IDs, and optional instructions that appear as formatted prompts in your client.
  • Knowledge-base operations respect workspace permissions, document visibility, and model attribution.

​
Security posture

  • API keys are validated for allowed characters before use. Invalid input fails fast.
  • Downstream HTTP URLs are checked to avoid localhost/SSRF exploits.
  • Command execution is allow-listed to frequently used binaries (node, npx, python, etc.).
  • Optional HTTP auth (--require-api-auth) ensures remote deployments stay private.
  • Set PLUGGEDIN_DEBUG=true to emit detailed logs during debugging; leave it false in STDIO mode to avoid polluting the MCP stream.

​
Protocol compliance

The proxy is 100% compliant with the Model Context Protocol specification:
  • ✅ MCP Protocol Version: 2024-11-05 with version negotiation
  • ✅ Header Format: Title-Case headers (Mcp-Session-Id, Mcp-Protocol-Version)
  • ✅ CORS Support: Full CORS headers with custom header exposure
  • ✅ JSON-RPC 2.0: Standardized error codes and message format
  • ✅ Session Management: Both stateful and stateless operation modes
  • ✅ 84+ Tests: Comprehensive test coverage for all protocol features
For technical details on protocol implementation, error codes, and testing, see the Protocol Compliance documentation.

​
Next steps

  • Follow the Setup Guide to configure credentials and connect your clients.
  • When you are ready to deploy, use the Installation guide for CLI, pnpm, or Docker workflows.
  • Review Protocol Compliance for technical specifications and testing details.