npm package: @plingcast/mcp-proxy
Description: HTTP to stdio proxy for MCP servers (env: MCP_URL required, MCP_API_KEY optional)
Author: plingdevelop
Latest version: 1.1.2

# Pling MCP Proxy

HTTP-to-stdio proxy for remote MCP servers. Use any HTTP MCP endpoint from Claude Desktop (stdio).

---

## Package

- **Name**: `@plingcast/mcp-proxy`
- **Registry**: npm
- **Use case**: Connect Claude Desktop to HTTP MCP servers via stdio

---

## Usage

### Environment variables

| Variable      | Required | Description                        |
| ------------- | -------- | ---------------------------------- |
| `MCP_URL`     | Yes      | MCP server base URL                |
| `MCP_API_KEY` | No       | API key when the server needs auth |

### Claude Desktop config (with API key)

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "my-mcp": {
      "command": "npx",
      "args": ["-y", "@plingcast/mcp-proxy"],
      "env": {
        "MCP_URL": "https://your-mcp-server.example.com/mcp",
        "MCP_API_KEY": "your_api_key"
      }
    }
  }
}
```

### Claude Desktop config (no auth)

```json
{
  "mcpServers": {
    "my-mcp": {
      "command": "npx",
      "args": ["-y", "@plingcast/mcp-proxy"],
      "env": {
        "MCP_URL": "https://your-mcp-server.example.com/mcp"
      }
    }
  }
}
```

Omit `MCP_API_KEY` when the MCP server does not require authentication.

**Note:** For Pling MCP usage, obtain `MCP_URL` and `MCP_API_KEY` from your administrator. The stdio proxy runs automatically when Claude Desktop starts; add it to your config file only—no separate process or manual run is required.

---

## Development

### Build

```bash
npm install
npm run build
```

### Local run

```bash
MCP_URL=https://your-server.example.com/mcp \
MCP_API_KEY=your_api_key \
node dist/index.js
```

---

## Project layout

```
pling-mcp-proxy/
├── index.ts       # HTTP → stdio proxy
├── package.json
├── tsconfig.json
└── README.md
```

### Data flow

```
Claude Desktop (stdio)
    ↓ JSON-RPC via stdin/stdout
proxy (npx @plingcast/mcp-proxy)
    ↓ HTTP (Api-Key header when MCP_API_KEY is set)
MCP Server
```

---

## Troubleshooting

**npx fails or "You must supply a command"**

- Node.js >= 18.0.0 required. Check with `npx --version`.
- Some clients (e.g. Claude Desktop) may run `npx` with a different Node from PATH, which can cause errors.

**"Cannot find module 'node:path'" or npx runs with wrong Node**

- The app may be invoking `npx` with an older Node (e.g. from PATH). Use **node + full path** instead of npx so the same Node runs the proxy.

  1. Install globally: `npm install -g @plingcast/mcp-proxy`
  2. Get the script path:
     ```bash
     echo "$(npm root -g)/@plingcast/mcp-proxy/dist/index.js"
     ```
  3. In your config, set `command` to your Node binary and `args` to the path from step 2 (as a single-element array). Example:
     ```json
     "command": "/path/to/node/v24.6.0/bin/node",
     "args": ["/path/to/node/v24.6.0/lib/node_modules/@plingcast/mcp-proxy/dist/index.js"]
     ```
     Replace `/path/to/node/...` with the output of `which node` or your nvm path (e.g. `~/.nvm/versions/node/v24.6.0/bin/node`).

**401 Unauthorized**

- Verify `MCP_API_KEY` and that the key is not expired.

**Connection errors**

- Confirm `MCP_URL` is correct and reachable from your network.