@mcpbay/agent

Connect your internal MCP servers to MCPBay Proxy without opening firewall ports.

Overview

The MCPBay Agent creates a secure outbound tunnel from your network to MCPBay, allowing your AI assistants to access internal MCP servers through MCPBay Proxy.

┌─────────────────────────────────────────────────────────────┐
│  Your Network                                               │
│                                                             │
│  ┌─────────────┐      ┌─────────────┐                      │
│  │ Internal    │      │ MCPBay      │ ──── outbound ────── │ ───▶ MCPBay Proxy
│  │ MCP Server  │ ◀──▶ │ Agent       │      tunnel          │
│  └─────────────┘      └─────────────┘                      │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Installation

npm install -g @mcpbay/agent

Or run directly with npx:

npx @mcpbay/agent --api-key <key> --mcp-url <url>

Quick Start

1. Create an Agent in the MCPBay Dashboard (Agents tab)
2. Copy your API key - it's only shown once!
3. Run the agent:

# For SSE/HTTP-based MCP servers
mcpbay-agent --api-key mcpbay_agent_xxx --mcp-url http://localhost:3000/sse

# For stdio-based MCP servers
mcpbay-agent --api-key mcpbay_agent_xxx --transport stdio --mcp-command python --mcp-args "-m,my_mcp_server"

Configuration

Command Line Options

| Option | Environment Variable | Description | |--------|---------------------|-------------| | -k, --api-key <key> | MCPBAY_API_KEY | MCPBay Agent API key (required) | | -u, --mcp-url <url> | MCP_SERVER_URL | Internal MCP server URL | | -t, --transport <type> | MCP_TRANSPORT | Transport type: sse, streamable-http, stdio | | -c, --mcp-command <cmd> | MCP_COMMAND | Command to run MCP server (stdio) | | -a, --mcp-args <args> | MCP_ARGS | Comma-separated command arguments | | --tunnel-url <url> | MCPBAY_TUNNEL_URL | Tunnel service URL (default: wss://tunnel.mcpbay.ai/connect) | | -d, --debug | - | Enable debug logging |

Environment Variables

Create a .env file:

MCPBAY_API_KEY=mcpbay_agent_xxxxxxxxxxxx
MCP_SERVER_URL=http://localhost:3000/sse
MCP_TRANSPORT=sse

Transport Types

SSE (Server-Sent Events)

For MCP servers that expose an SSE endpoint:

mcpbay-agent --api-key $KEY --mcp-url http://localhost:3000/sse

Streamable HTTP

For MCP servers using the streamable HTTP transport:

mcpbay-agent --api-key $KEY --transport streamable-http --mcp-url http://localhost:3000/mcp

Stdio

For MCP servers that communicate via stdin/stdout:

mcpbay-agent --api-key $KEY --transport stdio --mcp-command python --mcp-args "-m,my_mcp_server"

Programmatic Usage

import { Agent } from "@mcpbay/agent";

const agent = new Agent({
  apiKey: "mcpbay_agent_xxxxxxxxxxxx",
  mcpServerUrl: "http://localhost:3000/sse",
  mcpServerTransport: "sse",
  debug: true,
});

agent.on("authenticated", (agentId, agentName) => {
  console.log(`Connected as ${agentName}`);
});

agent.on("toolsDiscovered", (tools) => {
  console.log(`Found ${tools.length} tools`);
});

agent.on("mcpRequest", (requestId, method) => {
  console.log(`Forwarding: ${method}`);
});

await agent.start();

// Later...
await agent.stop();

Running as a Service

systemd (Linux)

Create /etc/systemd/system/mcpbay-agent.service:

[Unit]
Description=MCPBay Agent
After=network.target

[Service]
Type=simple
User=mcpbay
EnvironmentFile=/etc/mcpbay-agent.env
ExecStart=/usr/bin/mcpbay-agent
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

sudo systemctl enable mcpbay-agent
sudo systemctl start mcpbay-agent

Docker

FROM node:20-alpine
RUN npm install -g @mcpbay/agent
CMD ["mcpbay-agent"]

docker run -d \
  -e MCPBAY_API_KEY=mcpbay_agent_xxx \
  -e MCP_SERVER_URL=http://host.docker.internal:3000/sse \
  mcpbay-agent

PM2

pm2 start mcpbay-agent -- --api-key $KEY --mcp-url $URL
pm2 save
pm2 startup

Security

• Outbound only: The agent makes outbound WebSocket connections. No inbound ports required.
• API key authentication: Each agent has a unique API key.
• TLS encryption: All tunnel traffic is encrypted with TLS.
• E2E encryption (optional): Enable end-to-end encryption for sensitive data.

Troubleshooting

Agent won't connect

1. Check your API key is correct
2. Verify network allows outbound WebSocket connections to tunnel.mcpbay.ai:443
3. Check firewall/proxy settings

Tools not discovered

1. Ensure your MCP server is running and accessible
2. Check the MCP server URL/command is correct
3. Verify the MCP server implements tools/list

Requests timing out

1. Check your internal MCP server is responding
2. Increase timeout settings if needed
3. Check for network latency issues

License

MIT