npm package: @mcpbay/agent
Description: MCPBay Agent - Connect internal MCP servers to MCPBay Proxy
Author: MCPBay
Latest version: 1.0.3

# @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

```bash
npm install -g @mcpbay/agent
```

Or run directly with npx:

```bash
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:**

```bash
# 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:

```env
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:

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

### Streamable HTTP

For MCP servers using the streamable HTTP transport:

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

### Stdio

For MCP servers that communicate via stdin/stdout:

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

## Programmatic Usage

```typescript
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`:

```ini
[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
```

```bash
sudo systemctl enable mcpbay-agent
sudo systemctl start mcpbay-agent
```

### Docker

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

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

### PM2

```bash
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