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

Run on demand (npx)
Global npm install
Project dependency (pnpm)
From source

PLUGGEDIN_API_KEY=pg_in_your_key \
  npx @pluggedin/pluggedin-mcp-proxy

Ideal for local testing or temporary sessions.

npm install -g @pluggedin/pluggedin-mcp-proxy
PLUGGEDIN_API_KEY=pg_in_your_key pluggedin-mcp-proxy

Use this when you want a stable binary on your PATH (e.g., Claude Desktop integrations).

pnpm add -D @pluggedin/pluggedin-mcp-proxy
PLUGGEDIN_API_KEY=pg_in_your_key pnpm exec pluggedin-mcp-proxy

Adds the proxy to your project for scripting or CI jobs.

git clone https://github.com/VeriTeknik/pluggedin-mcp.git
cd pluggedin-mcp
pnpm install
pnpm build
PLUGGEDIN_API_KEY=pg_in_your_key node dist/index.js

Use this when contributing to the proxy or testing unreleased changes.

3. Configure credentials

Variable	Required	Default	Description
`PLUGGEDIN_API_KEY`	Required	Required	Authenticate the proxy with your Plugged.in workspace.
`PLUGGEDIN_API_BASE_URL`	Optional	`https://plugged.in`	Override when targeting a self-hosted Plugged.in environment.
`PLUGGEDIN_UUID_TOOL_PREFIXING`	Optional	`true`	Disable to remove server UUID prefixes from tool names.
`PLUGGEDIN_DEBUG`	Optional	`false`	Enable 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:

Script	Purpose
`pnpm run build`	Compile TypeScript to `dist/` and make the binaries executable.
`pnpm run watch`	Rebuild automatically when source files change (helpful during development).
`pnpm test`, `pnpm run test:watch`, `pnpm run test:coverage`, `pnpm run test:ui`	Execute Vitest test suites in standard, watch, coverage, or UI modes.
`pnpm run test:no-api`	Run tests that cover behaviour when no API key is provided.
`pnpm run inspector` and `pnpm run inspector:auto`	Launch scripted MCP Inspector sessions that automatically connect to a local build for smoke testing.
`pnpm run inspector:manual`	Start 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:prod`	Connect 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-api`	Verify the proxy’s behaviour when no API key is present.
`pnpm run report`	Generate 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

Flag	Description
`—transport <stdio	streamable-http>`	Switch between STDIO (default) and Streamable HTTP modes.
`--port <number>`	Port for Streamable HTTP mode (default `12006`).
`--stateless`	Start a fresh transport for every HTTP request instead of reusing sessions.
`--require-api-auth`	Enforce Bearer-token authentication in Streamable HTTP mode.
`--pluggedin-api-key <key>`	CLI alternative to the `PLUGGEDIN_API_KEY` environment variable.
`--pluggedin-api-base-url <url>`	CLI alternative to the `PLUGGEDIN_API_BASE_URL` environment variable.

10. Next steps

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

​Install the Plugged.in MCP Proxy

​1. Prerequisites

​2. Choose an installation path

​3. Configure credentials

​4. Deployment options

​5. Run the proxy locally

​STDIO mode (default)

​Streamable HTTP mode

​6. Containerized deployment

​7. Validate the installation

​8. Development and testing scripts

​9. CLI flags reference

​10. Next steps