Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.plugged.in/llms.txt

Use this file to discover all available pages before exploring further.

​
Install the Plugged.in MCP Proxy

The proxy is published as @pluggedin/pluggedin-mcp-proxy. This guide walks you through installing it with your preferred toolchain, configuring credentials, and validating the deployment.

​
1. Prerequisites

  • Node.js 20 LTS or newer (required for top-level await and the MCP SDK)
  • npm 10+ or pnpm 9+
  • Plugged.in API key with MCP access
  • Optional: Docker 24+ if you plan to containerize the proxy

​
2. Choose an installation path

PLUGGEDIN_API_KEY=pg_in_your_key \
  npx @pluggedin/pluggedin-mcp-proxy
Ideal for local testing or temporary sessions.

​
3. Configure credentials

VariableRequiredDefaultDescription
PLUGGEDIN_API_KEYRequiredRequiredAuthenticate the proxy with your Plugged.in workspace.
PLUGGEDIN_API_BASE_URLOptionalhttps://plugged.inOverride when targeting a self-hosted Plugged.in environment.
PLUGGEDIN_UUID_TOOL_PREFIXINGOptionaltrueDisable to remove server UUID prefixes from tool names.
PLUGGEDIN_DEBUGOptionalfalseEnable verbose logging (do not use in STDIO mode unless debugging).
Set them inline (VAR=value command) or export them in your shell profile.

​
4. Deployment options

  • Plugged.in Cloud (managed): Teams on the hosted Plugged.in platform can provision the MCP Proxy directly in the cloud. The managed instance stays updated automatically, scales with usage, and exposes the HTTP endpoint without any local setup. Use this when you need zero-maintenance infrastructure or want to share the proxy across your team instantly.
  • Local desktop integration: Run the proxy in STDIO mode when attaching Claude Desktop, Cursor, or any Inspector session running on the same machine. This keeps everything offline except for calls to the Plugged.in API.
  • Local or on-prem HTTP service: Use Streamable HTTP mode on a server you control (VM, bare metal, container, or serverless environment) when multiple users or remote IDEs need to reuse the proxy. Pair it with --require-api-auth for authenticated access.
  • Hybrid setups: Mix approaches by running STDIO for developer workstations and deploying a hardened HTTP instance (or the cloud version) for production workloads.

​
5. Run the proxy locally

​
STDIO mode (default)

PLUGGEDIN_API_KEY=pg_in_your_key \
  npx @pluggedin/pluggedin-mcp-proxy
  • STDIO mode is best for desktop clients and the MCP Inspector.
  • The process stays attached to stdin/stdout; avoid printing extra logs unless debugging.

​
Streamable HTTP mode

PLUGGEDIN_API_KEY=pg_in_your_key \
  npx @pluggedin/pluggedin-mcp-proxy \
  --transport streamable-http --port 12006 --require-api-auth
  • --port defaults to 12006; change it if the port is busy.
  • --require-api-auth enforces Authorization: Bearer <PLUGGEDIN_API_KEY> for tool/resource calls.
  • --stateless creates a new transport per request (set this for serverless or load-balanced deployments).
Health check: GET http://localhost:12006/health

​
6. Containerized deployment

Build your own image (optional): 
docker build -t pluggedin-mcp-proxy:latest .
Run it: 
docker run --rm -it \
  --name pluggedin-mcp-proxy \
  -e PLUGGEDIN_API_KEY=pg_in_your_key \
  -e PLUGGEDIN_API_BASE_URL=https://plugged.in \
  -p 12006:12006 \
  pluggedin-mcp-proxy:latest \
  --transport streamable-http --port 12006 --require-api-auth
Attach the MCP Inspector to the live container: 
npx @modelcontextprotocol/inspector docker://pluggedin-mcp-proxy
(Replace the container name if you chose a different one.)

​
7. Validate the installation

PLUGGEDIN_API_KEY=pg_in_your_key \
  npx @modelcontextprotocol/inspector npx:@pluggedin/pluggedin-mcp-proxy
Inside the Inspector, run tools/list to confirm Plugged.in static tools and your registered servers appear. Call pluggedin_ask_knowledge_base to verify document access.

​
8. Development and testing scripts

The project package.json exposes scripts that simplify local builds, testing, and inspector workflows:
ScriptPurpose
pnpm run buildCompile TypeScript to dist/ and make the binaries executable.
pnpm run watchRebuild automatically when source files change (helpful during development).
pnpm test, pnpm run test:watch, pnpm run test:coverage, pnpm run test:uiExecute Vitest test suites in standard, watch, coverage, or UI modes.
pnpm run test:no-apiRun tests that cover behaviour when no API key is provided.
pnpm run inspector and pnpm run inspector:autoLaunch scripted MCP Inspector sessions that automatically connect to a local build for smoke testing.
pnpm run inspector:manualStart the Inspector in manual mode, loading environment variables from .env.local so you can step through tool calls yourself.
pnpm run inspector:auth, pnpm run inspector:staging, pnpm run inspector:prodConnect the Inspector to different environments by reading the appropriate API keys and base URLs. Useful when validating staging or production workspaces.
pnpm run inspector:no-apiVerify the proxy’s behaviour when no API key is present.
pnpm run reportGenerate a capabilities report by running dist/index.js --report with dotenv-loaded credentials.
All inspector commands rely on the published dist output, so run pnpm build first or use the version shipped on npm via npx @pluggedin/pluggedin-mcp-proxy.

​
9. CLI flags reference

FlagDescription
`—transport <stdiostreamable-http>`Switch between STDIO (default) and Streamable HTTP modes.
--port &lt;number&gt;Port for Streamable HTTP mode (default 12006).
--statelessStart a fresh transport for every HTTP request instead of reusing sessions.
--require-api-authEnforce Bearer-token authentication in Streamable HTTP mode.
--pluggedin-api-key &lt;key&gt;CLI alternative to the PLUGGEDIN_API_KEY environment variable.
--pluggedin-api-base-url &lt;url&gt;CLI alternative to the PLUGGEDIN_API_BASE_URL environment variable.

​
10. Next steps

  1. Follow the Setup Guide to connect your MCP clients.
  2. Explore the Overview to understand the proxy architecture and built-in capabilities.