agent-breadcrumbs

Agent Breadcrumbs is a lightweight MCP server that centralizes and standardizes logging across multiple agents and clients. It provides a single log_work tool that aggregates work performed by different agents for one or many users, with support for custom schemas or built-in profiles. You can configure various sinks to store or forward logs, including local JSONL files, webhooks, or Postgres databases, and you can view the results via a simple dashboard. The server enforces a consistent payload format via MCP schemas, making it easy for clients to emit correctly structured log records without repeatedly explaining payload details.

To use it, run the MCP server using the npx-based quick-start or install it locally from the repository. You can run with defaults or specify a server-config.json to tailor schema and sink settings. The server supports predefined profiles (agent insights, delivery tracking, audit trail, knowledge capture) and lets you define your own logging structures if you need custom data models. For cron-driven or scheduled workflows, you can instruct agents to call log_work at regular intervals and include contextual information in each log entry. The included dashboard app lets you view and analyze the logged work, and the CLI/config examples show how to wire the MCP server into client configurations.

Prerequisites:

• Node.js and npm (or use npx to run without a global install)
• Access to the MCP repository or npm registry where agent-breadcrumbs is published

Install and run (quick start):

1. Install and run with defaults using npx: npx -y agent-breadcrumbs

2. If you want to specify a config file, use: npx -y agent-breadcrumbs --config /absolute/path/to/server-config.json

Install from repository (advanced):

1. Clone the repository or navigate to the packages/mcp directory in the repo.
2. Install dependencies: npm install
3. Build (if required by the repo setup): npm run build:mcp
4. Run the MCP server with a sample config: node packages/mcp/dist/index.js --config packages/mcp/examples/server-config.agent-insights.sample.json

Run the dashboard locally (optional): npm run build:dashboard npm run dev:dashboard -- --config apps/dashboard/examples/dashboard-config.sample.json

Prerequisites recap:

• Node.js and npm installed
• Access to a config file or the ability to pass inline config through environmental setup
• Optional: a sink (jsonl, webhook, postgres) configured per your deployment needs

Tips and common considerations:

• The default sink is jsonl to ~/.agent-breadcrumbs/logs.jsonl unless overridden by the server config.
• When using npx, you’re running the latest published tool version; for reproducible environments, pin to a specific version if available or install locally.
• If you enable a non-file sink (webhook or Postgres), ensure network access and credentials are correctly configured in the server-config.json.
• The MCP Config Model supports either a custom schema or a built-in schema_profile; avoid setting both simultaneously.
• The dashboard app is separate from the MCP server package; ensure you have the corresponding config file to visualize the logged data.
• When integrating with agents like Codex, Claude Desktop, or OpenClaw, provide the correct config path to ensure log_work calls are emitted in the expected format.