Summary

Add a global MCP tool registry that acts as the single source of truth for every tool available to the swarm. All agents discover tools through the registry rather than through individual server connections, giving the orchestrator a unified view of what is available, what version each tool is at, which agents are authorised to use it, and where to route calls at runtime.

Problem

As the number of MCP tools grows - built-in tools, SearXNG, external MCP servers, agent-as-tool exposures — there is no central place that tracks what tools exist, which version is active, which agents can use them, or where a call should be routed. This creates several problems:

• Discovery is implicit - each agent resolves tools independently; there is no swarm-wide view of what is registered
• No versioning - if a tool is updated or replaced, there is no mechanism to track the change or roll back
• No access control - any agent can attempt to call any tool; there is no per-agent or per-team tool whitelist enforced at the registry level
• Routing is hardcoded - tool call routing (local vs. remote MCP server vs. agent-as-tool) is resolved ad-hoc rather than from a central routing table
• No health visibility - there is no registry-level view of which tools are healthy, degraded, or unreachable

At small scale these gaps are manageable. At the scale FR8 (native MCP server) and FR5 (SearXNG) imply — many tools, multiple transports, external clients - the absence of a registry becomes a reliability and security gap.

Solution

Scope: core (registry service) + config + dashboard

The registry is a lightweight in-process service that starts with the orchestrator:

Registration - every tool (built-in, MCP server, agent-as-tool, SearXNG, external) registers itself at startup with:

• tool_id (unique slug)
• version (semver)
• transport (local / stdio / http)
• endpoint (if remote)
• input_schema (JSON Schema)
• allowed_agents (list of agent IDs or * for all)
• tags (e.g. search, code, file, comms)

Discovery - agents query the registry for available tools rather than resolving them independently. The registry returns only tools the agent is authorised to use.

Routing - when an agent calls a tool, the registry resolves the correct transport and endpoint, handles retries on transient failures, and logs the call.

Versioning - multiple versions of a tool can be registered simultaneously. The registry routes to the active version by default; operators can pin an agent to a specific version.

Health checking - the registry pings remote tool endpoints on a configurable interval and marks tools as healthy, degraded, or unreachable. Agents are not routed to unreachable tools.

Configuration in config.yaml:

tool_registry:
  enabled: true
  health_check_interval_seconds: 30
  default_policy: allowlist   # or: denylist
  tools:
    - tool_id: searxng_search
      allowed_agents: "*"
    - tool_id: file_writer
      allowed_agents:
        - sub_agent_compiler
        - sub_agent_formatter
    - tool_id: web_scraper
      allowed_agents: "*"
      version_pin: "1.2.0"

Dashboard integration - a Tools tab in the dashboard (or a section within the existing panels) shows the registry contents: tool name, version, transport, health status, call count today, and authorised agents. Operators can enable/disable tools and update access lists from the UI without restarting.

Fallback: if tool_registry.enabled is false, tool resolution falls back to the current implicit behaviour. No existing functionality changes.

Acceptance criteria

• Registry starts with orchestrator — all built-in and configured tools register themselves at startup
• Agent discovery - agents query the registry for authorised tools; the registry returns only permitted tools for that agent
• Access control - allowed_agents is enforced; calls from unauthorised agents are rejected with a structured error
• Routing - the registry resolves the correct transport and endpoint for every tool call
• Versioning - multiple versions can be registered; active version is used by default; per-agent version pinning is supported
• Health checking - remote tools are pinged on health_check_interval_seconds; unreachable tools are not routed to
• Dashboard tools tab - registry contents visible in the dashboard with health status, call count, and access list
• UI management - operators can enable/disable tools and edit access lists from the dashboard without a restart
• Config persistence - UI changes are written back to config.yaml
• Fallback - tool_registry.enabled: false restores implicit tool resolution; no existing behaviour changes
• Diff coverage ≥ 80% - the implementing PR meets the changed-lines coverage gate (Vitest + cargo-llvm-cov, enforced by .github/workflows/coverage.yml)

Related

• MCP specification: https://modelcontextprotocol.io/
• OpenHuman agent architecture: https://tinyhumans.gitbook.io/openhuman/
• Proposed: SearXNG native MCP tool (FR5)
• Proposed: Native MCP server exposure (FR8)
• Proposed: Teams and agents management panel (FR9)