mcpd

mcpd is a daemon that manages MCP servers for you, spawning each server as a subprocess and exposing a clean HTTP API to interact with them. It uses a declarative configuration file (.mcpd.toml) to define which MCP servers you want to run, how they should be started, and how secrets and environment variables should be injected. Once running, you can call tools and endpoints exposed by those MCP servers through the unified HTTP API, enabling you to orchestrate multiple agent runtimes (Python, JavaScript, Docker-based containers, etc.) without launching them manually on every host.

To get started, install mcpd and initialize a project with a .mcpd.toml configuration. You can add individual MCP servers (for example a time service or a data-fetching service) and then start the daemon in dev mode for debugging. The API is accessible at the daemon’s HTTP endpoint (e.g., http://localhost:8090/docs for API docs). You’ll then be able to invoke tools provided by each MCP server via HTTP POST requests to the /api/v1/servers/{server-name}/tools/{tool-name} path, supplying the required JSON payload (input schema depends on the tool).

mcpd handles lifecycle management, secret injection from your local secrets store, and environment promotion, so your agents run with the proper context across local and containerized environments through a single, consistent HTTP interface.

Prerequisites

• Docker (for running MCP servers via containers) or a locally installed Go-based binary as provided by the project (see installation options below)
• Optional: npx (Node.js) and uvx for specific development workflows

Installation options

1. Homebrew (recommended on macOS/Linux for binary installation)

   • Add the Mozilla AI tap and install mcpd: brew tap mozilla-ai/tap brew install mcpd
   • Or install from the cask: brew install --cask mozilla-ai/tap/mcpd
   • For more installation variants (GitHub releases or local Go binary), refer to the docs: GitHub releases or local Go binary build pages

2. Direct binaries via GitHub releases or Go binary (as documented by the project)

   • Follow the official installation guide to download the appropriate binary for your OS and place it in your PATH

3. Quick start after installation

   • Initialize a new project and configuration file: mcpd init
   • Add an MCP server to the configuration: mcpd add time
   • Optionally configure the server (timezone, etc.): mcpd config args set time -- --local-timezone=Europe/London
   • Run the daemon (dev mode with debug logging): mcpd daemon --dev --log-level=DEBUG --log-path=$(pwd)/mcpd.log

Notes

• The exact command used to start MCP servers can vary depending on your deployment method. If you’re using Docker, your mcpd_config can reference a docker run invocation (as shown in the example).
• If you are using other runtimes (Python, JS, containers), ensure their runtimes are installed and available to the daemon so that MCP servers can be launched via the unified HTTP API.

Tips and common issues:

• Ensure Docker is running and you have permission to run containers when using docker-based server definitions.
• Use mcpd config to customize per-server environment variables and secrets; keep sensitive data out of version control and rely on the local secrets store referenced by mcpd.
• The API docs are served at /docs (e.g., http://localhost:8090/docs). Use the provided endpoints to list servers, start/stop servers, and call tools.
• When adding or updating .mcpd.toml, commit changes to version control to keep your infrastructure-as-code in sync across environments.
• If you run into port conflicts, adjust the API port via your mcpd configuration or environment to avoid clashes with other services.