A lightweight gateway that exposes local stdio-based MCP servers via Streamable HTTP
npm install mcpbox
MCPBox is a lightweight gateway that exposes local stdio-based MCP servers via Streamable HTTP, enabling Claude and other AI agents to connect from anywhere.
- Runs multiple servers behind a single HTTP endpoint
- Supports Tools, Resources & Prompts
- Namespaces with servername__ prefix to avoid collisions
- Per-server tool filtering to limit AI access and reduce context usage
- OAuth or API key authentication

Create mcpbox.json:
``json`
{
"mcpServers": {
"memory": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-memory"]
}
}
}
Run with:
npx
`bash`
npx mcpboxuvx
MCP server commands (e.g., , docker) must be available where the box runs.
Docker
`bash`
docker run -v ./mcpbox.json:/config/config.json -p 8080:8080 ghcr.io/kandobyte/mcpboxnpx
The Docker image includes Node.js and Python, supporting MCP servers launched via and uvx.
The box starts on http://localhost:8080. Connect an agent by adding this to your MCP client config:
`json`
{
"mcpServers": {
"mcpbox": {
"type": "http",
"url": "http://localhost:8080"
}
}
}
For remote access with authentication, see Deployment and Connect Your AI.
See mcpbox.example.jsonc for all options. All string values support ${VAR_NAME} environment variable substitution.
Authentication — none (default), API key, or OAuth.
To expose MCPBox remotely, put it behind a TLS-terminating reverse proxy.
Before deploying with OAuth:
- [ ] Use sqlite storage for persistence across restarts
- [ ] Set issuer to your public URL
- [ ] Use bcrypt hashes for local passwords
> [!NOTE]
> MCPBox is single-instance only — don't run multiple instances behind a load balancer.
Use cloudflared to expose a local instance (no account required):
`bash`
cloudflared tunnel --url http://localhost:8080
Then update your config with the generated public URL:
`json`
{
"auth": {
"type": "oauth",
"issuer": "https://
"identityProviders": [
{ "type": "local", "users": [{ "username": "admin", "password": "${MCPBOX_PASSWORD}" }] }
],
"dynamicRegistration": true
},
"storage": {
"type": "sqlite",
"path": "/data/mcpbox.db"
},
"mcpServers": { ... }
}
Run with a persistent data volume:
`bash`
docker run -v ./mcpbox.json:/config/config.json -v ./data:/data -p 8080:8080 ghcr.io/kandobyte/mcpbox
Settings → Connectors → Add Custom Connector → enter your URL → Connect
Requires dynamicRegistration: true in your config.
`bash`
claude mcp add --transport http mcpbox https://your-mcpbox-url.com
Requires dynamicRegistration: true in your config.
With dynamic registration (OAuth) — just provide the URL:
`json`
{
"mcpServers": {
"mcpbox": {
"type": "http",
"url": "https://your-mcpbox-url.com"
}
}
}
With API key:
`json``
{
"mcpServers": {
"mcpbox": {
"type": "http",
"url": "https://your-mcpbox-url.com",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}