MCP tools

Flock exposes a progressive-disclosure MCP surface: meta-tools for discovery, compact listings in tools/list, and full schemas on demand via flock_describe_tool.

Registry: crates/flock-runtime/src/mcp/registry.rs
Stdio server: flock mcp
Live episodes: flock run --mcp → FlockEngine::call_mcp_tool

Discovery flow

flowchart LR
    A[Agent starts] --> B{flock_discover_tools<br/>or flock_search_tools}
    B --> C[flock_describe_tool]
    C --> D[Invoke operational tool]
    D --> E[Governance + trace]

    class A runtime
    class B runtime
    class C substrate
    class D substrate
    class E gate

Discover — flock_discover_tools returns domain-indexed tool cards (no full schemas).
Search — flock_search_tools with query (and optional domain) narrows by intent.
Describe — flock_describe_tool with name returns full schema, preconditions, side effects, examples.
Invoke — tools/call or live mcp_tools observation payload.

Meta-tools are always listed with full schemas. Operational tools in tools/list use compact cards (call flock_describe_tool for parameters).

Meta tools

Tool	Domain	Purpose
`flock_discover_tools`	meta	Browse domains and tool names
`flock_search_tools`	meta	Keyword search over catalog
`flock_describe_tool`	meta	Full ToolSpec for one tool

Operational tools

Tool	Domain	Summary	Live (`--mcp`)	Governance
`flock_deposit_signal`	substrate	Deposit pheromone into zone	Yes	pre/post hooks
`flock_read_signal`	substrate	Read signal strength	Yes	read-only
`flock_read_blackboard`	substrate	Read blackboard slot	Yes	read-only
`flock_topology_snapshot`	substrate	Harness topology JSON	Yes	read-only
`flock_metrics`	substrate	Session counters	Yes	read-only
`flock_multiplexer_status`	multiplexer	Dashboard statusline snapshot	Yes	read-only
`flock_propose_mutation`	evolve	Verify/accept topology mutation	Yes	high-impact gate

All operational tools are in LIVE_TOOL_NAMES for flock run --mcp.

Start the server

flock mcp

Wire your MCP client to stdin/stdout JSON-RPC. Cursor config example in Cursor setup.

Example: discovery sequence

{"name": "flock_search_tools", "arguments": {"query": "deposit", "domain": "substrate"}}

{"name": "flock_describe_tool", "arguments": {"name": "flock_deposit_signal"}}

{"name": "flock_deposit_signal", "arguments": {"zone": "grid", "signal": "coordination", "amount": 2.0}}

Example: live episode

Observation payload for flock run --goal "..." --plugin gridworld --mcp:

{
  "mcp_tools": [
    {
      "tool": "flock_deposit_signal",
      "args": { "zone": "grid", "signal": "coordination", "amount": 2.0 }
    }
  ]
}

Trace JSONL emits mcp_discovery for meta-tools and mcp_tool for operational calls. Governance pre/post hooks apply on the hot path.

Design principles

Principle	Implementation
Progressive discovery	Meta-tools before full schemas
Context efficiency	Compact `tools/list` for operational tools
Live parity	Same registry for `flock mcp` and `flock run --mcp`
Description quality	Summary + preconditions + side effects per tool

Adding a tool

Add ToolSpec in registry.rs and register in all_tool_specs().
Add handler in handlers.rs and route in call_tool_with_registry.
Add name to LIVE_TOOL_NAMES if live episodes should expose it.
Update this page and run cargo test -p flock-runtime.

Keyboard shortcuts

Flock