MCP Integration

Cacophony auto-generates MCP (Model Context Protocol) tools from CLI metadata. The CLI is canonical; MCP tools are derived, not independently implemented. Agent instructions should prefer caco_* MCP tools only when the current runtime actually exposes them; managed Pi sessions may have shell/CLI access plus Pi extensions but no first-party caco_* MCP family, in which case agents should use the equivalent caco ... CLI commands.

MCP Generation

Any command with mcp.enabled = true in its help metadata auto-exposes an mcp subcommand:

caco bd mcp stdio       # Beads MCP server
caco agent mcp stdio    # Agent MCP server
caco msg mcp stdio      # Messaging MCP server
caco test mcp stdio     # Queued test MCP server
caco build mcp stdio    # Queued build MCP server
caco file mcp stdio     # Project file-cache MCP server
caco link mcp stdio     # Project URL/link artifact MCP server
caco heartbeat mcp stdio # Managed-agent heartbeat MCP server
caco scratch mcp stdio  # Scratchpad MCP server
caco project mcp stdio  # Project MCP server
caco audio mcp stdio    # Audio/STT MCP server
caco tts mcp stdio      # TTS control MCP server
caco choices mcp stdio  # Choices MCP server
caco release mcp stdio  # Release queue MCP server
caco mcp stdio          # Aggregate MCP server

Profile-attached first-party servers

The profile mcp_servers allowlist can also register a first-party tool whose MCP server is owned by another binary.

The caravan mixin attaches cara through this generic mechanism and launches cara mcp stdio, honoring CACO_CARA_BIN when the managed runtime pins an exact Caravan binary.

Cara remains the authorization and mutation authority for its typed tools; Cacophony does not wrap those tools in a second request protocol.

Tool Naming

MCP tool names are derived from CLI command paths by replacing spaces with underscores:

Only MCP-enabled commands appear as tools. The generator still descends through non-tool parent branches so MCP-enabled grandchildren are discoverable; for example read-side daemon controls such as caco stt daemon status and caco stt daemon logs can be exposed even though the long-running foreground caco stt daemon branch itself is not a generated tool. Agent-safe filtering suppresses non-agent-usable commands when the environment indicates agent invocation.

Plugin Marketplace

Cacophony ships a Claude-compatible plugin marketplace with one plugin per CLI command family or MCP-exposing subcommand.

Directory Structure

.claude-plugin/
  marketplace.json          # Top-level marketplace manifest
plugins/
  caco/
    .claude-plugin/
      plugin.json
  caco-bd/
    .claude-plugin/
      plugin.json           # Plugin metadata + inline mcpServers
  caco-agent/
    .claude-plugin/plugin.json
  caco-msg/
    .claude-plugin/plugin.json
  caco-test/
    .claude-plugin/plugin.json
  caco-build/
    .claude-plugin/plugin.json
  caco-file/
    .claude-plugin/plugin.json
  caco-scratch/
    .claude-plugin/plugin.json
  caco-projects/
    .claude-plugin/plugin.json
  caco-audio/
    .claude-plugin/plugin.json
  caco-choices/
    .claude-plugin/plugin.json
  caco-tts/
    .claude-plugin/plugin.json
  caco-release/
    .claude-plugin/plugin.json

Marketplace Manifest

{
  "name": "caco",
  "owner": { "name": "Cacophony" },
  "plugins": [
    {
      "name": "caco",
      "source": "./plugins/caco",
      "description": "Aggregate top-level MCPs via caco mcp stdio"
    },
    {
      "name": "caco-bd",
      "source": "./plugins/caco-bd",
      "description": "Beads MCPs via caco bd mcp stdio"
    },
    {
      "name": "caco-test",
      "source": "./plugins/caco-test",
      "description": "Queued test MCPs via caco test mcp stdio"
    },
    {
      "name": "caco-build",
      "source": "./plugins/caco-build",
      "description": "Queued build MCPs via caco build mcp stdio"
    },
    {
      "name": "caco-file",
      "source": "./plugins/caco-file",
      "description": "File cache MCPs via caco file mcp stdio"
    },
    {
      "name": "caco-scratch",
      "source": "./plugins/caco-scratch",
      "description": "Scratchpad MCPs via caco scratch mcp stdio"
    },
    {
      "name": "caco-projects",
      "source": "./plugins/caco-projects",
      "description": "Project MCPs via caco project mcp stdio"
    },
    {
      "name": "caco-agent",
      "source": "./plugins/caco-agent",
      "description": "Agent MCPs plus the managed bead-worker agent"
    },
    {
      "name": "caco-audio",
      "source": "./plugins/caco-audio",
      "description": "Audio/STT MCPs via caco audio mcp stdio"
    },
    {
      "name": "caco-tts",
      "source": "./plugins/caco-tts",
      "description": "TTS control MCPs via caco tts mcp stdio"
    },
    {
      "name": "caco-release",
      "source": "./plugins/caco-release",
      "description": "Release queue MCPs via caco release mcp stdio"
    }
  ]
}

The aggregate caco plugin is an operator-facing superset for caco mcp stdio. Scoped managed profiles should keep using only the narrow derived family plugins they explicitly require.

Per-Plugin MCP Wiring

Each plugin's .claude-plugin/plugin.json inlines its MCP server wiring under mcpServers. Separate sidecar files such as .mcp.json are not used.

{
  "name": "caco-bd",
  "version": "1.2.3",
  "description": "Beads MCPs via caco bd mcp stdio",
  "mcpServers": {
    "caco-bd": {
      "type": "stdio",
      "command": "caco",
      "args": ["bd", "mcp", "stdio"]
    }
  }
}

Using MCP Tools

Beads Tools

# Create a bead via MCP
caco_bd_create(title="Fix auth bug", type="bug", priority=1)

# List ready beads
caco_bd_list(ready=true)

# Claim next bead
caco_bd_claim()

# Close a bead
caco_bd_close(id="bd-abc")

Agent Tools

# Set agent status
caco_agent_status_set(status="running tests")

# List agents
caco_agent_list()

# Complete agent work
caco_agent_complete()

Messaging Tools

# Send a message
caco_msg_send(to="localhost:cacophony:sunny-owl", body="Please review")

# Broadcast
caco_msg_broadcast(body="Starting deploy")

# Speak via TTS
caco_msg_speak(text="Build complete")

File Cache Tools

# Add inline or path-backed content to the project file cache
caco_file_add(path="./artifact.log", kind="text", title="Audit log", tags="audit,logs")

# Search metadata and bounded UTF-8 content
caco_file_search(query="error fingerprint", kind="text", association="bead:bd-...")

# Retrieve bytes by id
caco_file_get(file_id="file-...")

# Update metadata or tombstone a record without losing audit history
caco_file_update(file_id="file-...", kind="text", title="Updated log", url="https://example.invalid", tags="audit,preview", associations="bead:bd-...")
caco_file_delete(file_id="file-...", reason="superseded")

# Sync local file-cache records through the project state branch
caco_file_sync(mode="pull")

The file MCP family is generated from the caco file CLI metadata. It is project-scoped, stores local runtime blobs plus append-only JSONL metadata/tombstones, tracks artifact fields such as kind/title/url/description/associations/metadata, uses first-party messaging for optional availability broadcasts, and can sync records/blobs through the project state branch with sha256 integrity checks rather than a separate file-sharing protocol.

Link Artifact Tools

# Record a URL/shareable-reference artifact
caco_link_add(url="https://example.invalid/pr/123", title="Preview build", tags="pr,preview", bead_id="bd-...")

# List, show, update, search, tombstone, and sync link records
caco_link_list(project="cacophony", tag="preview")
caco_link_show(link_id="link-...")
caco_link_update(link_id="link-...", status="ready", freshness="fresh")
caco_link_search(query="preview")
caco_link_delete(link_id="link-...")
caco_link_sync(mode="both")

The link MCP family is generated from the caco link CLI metadata. It records bounded URL/shareable-reference metadata in the project file-cache runtime root, with filters for project, host, tag, creator, bead, agent, reintegration, job, release, preview deployment, and search text plus optional bead/agent/reintegration/build/test/release/preview associations; link sync reuses the file-cache state-branch path. caco artifact and caco artefact remain reserved compatibility aliases and should not create duplicate MCP tools unless the external product contract is updated.

Choices Tools

# Present multi-choice to user
caco_choices_present(choices=[...])

# Present speech/narration
caco_choices_speak(text="Working on task")