Pibox

What Pibox MCP server does

The Pibox MCP server puts pi-coding-agent behind a Model Context Protocol interface. MCP clients can call run_prompt to send work to Pi, then use file tools limited to the configured workspace. Pi handles the interaction with the LLM provider selected for the container.

This fits Coding Agents workflows where one agent needs to delegate a prompt to a separate Pi runtime. It can also provide an MCP entry point alongside Pibox’s other operating modes, rather than requiring a separate application for each interface.

How it works

Pibox runs as a Docker image based on the aicodebox container and includes Pi. Enable MCP mode with PIBOX_MCP_MODE=1. The MCP endpoint uses streamable HTTP. When API mode is also enabled, MCP is available beneath /mcp/ on the API port; without API mode, Pibox starts MCP as a sidecar uvicorn process on its own port and serves it at the port root.

MCP mode is independent of the foreground mode selection. It can coexist with API, Telegram, or cron operation. The API and MCP modes can therefore share a container while retaining their separate interfaces. Authentication can be configured with PIBOX_MCP_MODE_TOKEN.

Setup and configuration

The normal entry point is the installed pibox host wrapper. The installer creates the required Pi, aicodebox, and SSH state directories, pulls the selected image, and places the wrapper on PATH. Running the wrapper from a workspace mounts that directory at the same absolute path inside the container and persists Pi and aicodebox state.

A minimal MCP setup uses environment values similar to:

environment:
  - PIBOX_MCP_MODE=1
  - PIBOX_MCP_MODE_TOKEN=your-secret

Set the LLM provider endpoint, credentials, and model according to Pi’s provider configuration. The image supports documented OpenAI, Anthropic, and Google custom HTTP APIs through PIBOX_PROVIDER_*; Anthropic-compatible deployments can also use the documented ANTHROPIC_* variables. AICODEBOX_* equivalents are accepted by the underlying image, with AICODEBOX_* taking precedence when both prefixes are set.

Tools and capabilities

The Pibox MCP server provides:

• run_prompt for sending a prompt to pi-coding-agent.
• Workspace-confined file operations for working with files in the mounted directory.
• Streamable HTTP transport for remote or local MCP client connections.
• Optional token-based access control through the MCP mode configuration.
• Coexistence with Pibox API, Telegram, and cron modes.

The workspace mount preserves the path used on the host, which allows prompts and file operations to refer to the same project location inside the container. The file tools enforce workspace boundaries rather than allowing unrestricted path traversal.

Limitations and notes

Pibox is self-hosted and requires Docker plus a configured LLM provider for Pi to produce responses. MCP mode exposes Pi and workspace operations; it does not by itself provide an independent model or workspace outside the mounted container directory.

Foreground modes are generally mutually exclusive, although Telegram and cron can run together. MCP mode is the exception because it runs independently. When API mode is enabled, clients must use the MCP path under /mcp/; in other modes, clients must use the separate MCP sidecar port.