> ## 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.
# MCP Proxy Installation
> Install and run the Plugged.in MCP Proxy in STDIO or Streamable HTTP mode.
# 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
```bash theme={null}
PLUGGEDIN_API_KEY=pg_in_your_key \
npx @pluggedin/pluggedin-mcp-proxy
```
Ideal for local testing or temporary sessions.
```bash theme={null}
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).
```bash theme={null}
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.
```bash theme={null}
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)
```bash theme={null}
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
```bash theme={null}
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 ` 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):
```bash theme={null}
docker build -t pluggedin-mcp-proxy:latest .
```
Run it:
```bash theme={null}
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:
```bash theme={null}
npx @modelcontextprotocol/inspector docker://pluggedin-mcp-proxy
```
(Replace the container name if you chose a different one.)
## 7. Validate the installation
```bash theme={null}
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 \\` | 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
1. Follow the [Setup Guide](/setup-guide) to connect your MCP clients.
2. Explore the [Overview](/mcp-proxy/overview) to understand the proxy architecture and built-in capabilities.