Agent MCP reference

Fleet exposes one workspace-bound MCP server per workspace. Agents call its tools through their harness; they do not run Fleet commands. The server is a stateless Streamable HTTP MCP built with mcp-handler:

http://localhost:<port>/workspaces/<repo>/<name>/mcp

The harness starts fleet agent-mcp as an internal stdio adapter. The adapter walks up from the harness working directory to atlas.json, derives repo/name from the path, reads the ship port and the workspace token inherited from its tmux session, and forwards each MCP message to that URL. Its server name is fleet-agent. It is discovery and transport plumbing, not an agent-facing command surface.

The connection is permanently bound to the discovered workspace. No tool accepts a repo or workspace selector, so an agent cannot use it to target a neighbour.

Authentication and transport

When a workspace is activated, the ship mints an opaque bearer token, retains its repo/name binding in memory, and injects it into that workspace’s tmux session as FLEET_AGENT_MCP_TOKEN. The adapter sends it only to the matching /workspaces/:repo/:name/mcp URL. Sibling workspaces receive different tokens.

The endpoint follows Streamable HTTP and accepts JSON or server-sent-event MCP responses. It is stateless and supports no subscriptions. Tool results contain one text item whose value is formatted JSON.

Agent tools

agent_init

Registers or resets the active workspace’s agent session and seeds its status to idle.

Input	Type	Required	Meaning
model	string	yes	Model driving the agent.
provider	string	yes	Model provider.
harness	string	yes	Agent harness, such as claude-code.

All strings must be non-empty. The workspace must be active.

agent_status

Updates the session while preserving the model, provider, and harness recorded by agent_init.

Input	Type	Required	Meaning
state	idle | planning | building | verifying | awaiting	yes	Current phase.
description	string	yes	Non-empty human-readable current activity.

The tool fails until agent_init has run for the current session.

agent_status_get

Takes no input and returns the current AgentStatus, or null if no agent is attached. This tool is read-only.

Repository tools

Repository tools go from the ship to the bridge using the ship’s scoped ship-agent credential. The bridge holds the forge credentials; neither the harness nor the workspace receives them.

repo_info

Takes no input and returns the registered repository’s provider metadata. This tool is read-only.

repo_issue_list

Lists issues. Optional state is open, closed, or all; omitted means the provider’s default (open). This tool is read-only.

repo_issue_view

Takes a positive integer number and returns one issue with its comments. This tool is read-only.

repo_issue_comment

Takes a positive integer number and non-empty string body, then adds the comment through the bridge.

repo_pr_list

Lists pull requests. Optional state is open, closed, or all; omitted means the provider’s default (open). This tool is read-only.

repo_pr_view

Takes a positive integer number and returns one pull request with its comments and reviews. This tool is read-only.

repo_pr_comment

Takes a positive integer number and non-empty string body, then adds the comment through the bridge.

repo_pr_review

Submits a pull-request review.

Input	Type	Required	Meaning
number	positive integer	yes	Pull request number.
event	APPROVE | REQUEST_CHANGES | COMMENT	yes	Review disposition.
body	string	no	Review body.

repo_checks

Returns CI checks for a target. This tool is read-only.

Input	Type	Required	Meaning
pr	positive integer	no	Use the head of this pull request.
ref	non-empty string	no	Use this git ref.

Pass at most one of pr and ref. With neither, Fleet reads the current branch from the workspace. A detached HEAD requires an explicit target.

repo_failed_logs

Returns failed CI job logs for a pull request, ref, or the current branch. Its pr and ref inputs and target selection are identical to repo_checks. This tool is read-only. A failing check that is not backed by GitHub Actions has no job log for Fleet to fetch.