MCP

The hub runs a Model Context Protocol (MCP) server. The server uses streamable HTTP at /mcp, on port 7077 by default. Its tools start with drover_.

Authentication

Each MCP request requires a bearer credential. This includes initialization and tool discovery.

• Send Authorization: Bearer <credential> on each request.
• The hub refuses anonymous requests, also on loopback.
• The hub refuses a revoked credential on the next request.
• MCP uses the same credentials as the HTTP API.
• If you set [auth] enabled = false, the MCP server does not start.

What each credential can do

Credential	MCP access
Device or host	Read tools, the profile at the general tier, proposals and session close.
Profile	Only drover_profile, at the tier of its registered agent.
Preflight	None.
Shared token, when enabled	Read tools, the private profile, proposals and session close.

A caller cannot raise its tier with a parameter. Session cookies do not work for MCP.

Network

The MCP server listens on loopback only. It refuses a bind to another address.

To connect a client on another machine, use a protected tunnel to the loopback endpoint of the hub. You operate the tunnel. A private LAN or a tailnet does not replace the tunnel.

Connect a client

Set two environment variables in the environment that starts the client. Take the credential from your secret store.

export DROVER_MCP_URL=http://127.0.0.1:7077/mcp
export DROVER_MCP_TOKEN=...   # a device, host or profile credential

Do not put a credential in model context or in a file that you commit.

Codex

Add this to the Codex configuration:

[mcp_servers.drover]
url = "http://localhost:7077/mcp"
bearer_token_env_var = "DROVER_MCP_TOKEN"

Claude Code

Add this to .mcp.json:

{
  "mcpServers": {
    "drover": {
      "type": "http",
      "url": "${DROVER_MCP_URL}",
      "headers": {"Authorization": "Bearer ${DROVER_MCP_TOKEN}"}
    }
  }
}

Other clients

Register a streamable HTTP server at the MCP URL. Send the Authorization header on each request.

Check the server

The command-line client reads DROVER_MCP_TOKEN:

drover-server mcp tools

Use one hub

Connect each agent to the hub, also agents on other hosts. The hub answers recall. Hosts collect events and run sessions.

Tools

Tools are read tools unless the table shows Write.

Fleet

Tool	Result
drover_fleet_status	Live hosts and sessions.
drover_active_sessions	Sessions that run or wait.
drover_provider_quota	Provider quota for each account. Email labels are masked.

History and recall

Tool	Result
drover_search	Search of recorded agent events. Not case sensitive.
drover_recall_bundle	Matches, summaries, project briefs and open loops in one response.
drover_recall	Semantic recall from an embedding that you supply.
drover_recent_sessions	The latest session summaries for a repository.
drover_session_summary	The summary of one session.
drover_session_replay	The most recent events of one session.
drover_files_touched	File paths that a task or session changed.
drover_project_brief	The latest brief for a repository.
drover_project_activity	Counts, timeline and open items for each project.
drover_task_status	Status totals for a task.

Handoff and continuity

Tool	Result
drover_handoff	Recent summaries and active sessions for a task, repository or session.
drover_active_handoff	A brief for an open session. Requires write authority, because it can call a model.
drover_recent_contexts	Recent context containers.
drover_context_brief	One context container.
drover_open_loops	Containers with next actions or open questions.
drover_resume_context	A container and its linked summaries.

The four context tools read context containers. An opt-in worker produces them. See Context containers.

The handoff tools return context. They do not move a session. To continue a session on another host, use the continue endpoint.

Profile

Tool	Result
drover_profile	Your portable profile, at the tier of the credential. Maximum 1,500 tokens.
drover_profile_propose	Write. Proposes a profile change. The change is pending until you approve it.

Maintenance

Tool	Result
drover_session_close	Write. Queues a summary for a session.
drover_data_quality	A quality report of the context store.
drover_pipeline_observatory	The state of the summary and brief pipeline.
drover_memory_acceptance	A memory evidence report for a set of sessions.

Response contract

Each read tool follows the same contract:

• Size limits. Each text field has a limit of 4,096 bytes. Each response has a limit of 65,536 bytes. A larger result sets truncated: true.
• Deadline. Each read has a five-second deadline. A late read returns status: timeout.
• Concurrency. Four reads run at one time. The fifth read returns status: busy.
• Provenance. Each response names its store and host.
• Freshness. Each result has a data_watermark with a timestamp and its basis. An unknown watermark is null.
• No fallback. If the selected store cannot answer, the tool returns unavailable.

Install the agent skill

The repository contains a skill that tells agents how to use these tools.

1. From a checkout, link the skill:

   mkdir -p ~/.agents/skills
   ln -s "$(pwd)/skills/drover" ~/.agents/skills/drover

2. Start a new agent session.