MCP tools

@quarry-systems/agora-mcp is a stdio MCP server that exposes a deliberately narrow, run-time-safe tool surface over an AgoraClient (and, when configured, an OperationsApi). Privileged deploy-time operations (register, assign) and privileged/service orchestrator operations never appear here — see The privilege boundary.

The tools

The server registers nine tools, in declaration order (the AGORA_TOOL_NAMES tuple in tools.ts):

Catalog reads (metadata only)

These return metadata only — never file contents, system-prompt bodies, secret values, or secret ARNs.

Tool	Purpose	Inputs
agora_capabilities_list	List registered capabilities (name, registeredAt, contentHash).	none
agora_subagents_list	List registered subagents (name, registeredAt, contentHash).	none
agora_envs_list	List registered env bundles (name, registeredAt, contentHash).	none

Dispatch operations

Tool	Purpose	Inputs
agora_dispatch	Dispatch a unit of work to a registered subagent on a configured target. Returns a DispatchResult.	Required: target, subagent, workerImage. Optional: env, capabilities, addCapabilities, secrets, input, callback, timeoutSeconds, defaultDispatchTimeoutSeconds, retentionDays, resources, dispatchId. (additionalProperties allowed.)
agora_dispatch_describe	Look up a previously-sealed dispatch record by id. Returns the full DispatchResult. Throws if purged by retention.	Required: dispatchId.
agora_dispatch_cancel	Request cancellation of an in-flight dispatch by id.	Required: dispatchId.

Orchestrator operations

These three are pure client-side translators over OperationsApi. Each requires the orch export in agora.config to be configured; without it the tool returns a clear “orchestrator surface not configured” error response.

Tool	Purpose	Inputs
agora_orchestrator_submit	Submit a Run plan to the orchestrator. Returns the run id.	Required: plan (object). Optional: actor (defaults to agent:mcp).
agora_orchestrator_status	Return the latest status OutboxRecord for a run id.	Required: runId.
agora_orchestrator_watch	Poll and wait for a run to reach a terminal state. Returns the last record seen; bounded by timeoutMs.	Required: runId. Optional: timeoutMs (default 25000).

Deliberately absent

The following are excluded by design and enforced architecturally by a CI allowlist check:

• any agora_*_register — registration is a privileged deploy-time operation.
• any agora_*_assign — capability assignment is privileged.
• agora_orchestrator_cancel — privileged.
• agora_orchestrator_audit — service-only.
• agora_orchestrator_serve — CLI-only.

Registration and assignment run through the CLI instead. The reasoning behind keeping privileged operations out of the AI loop is in The privilege boundary.

Note

The README describes the agora-mcp surface as “exactly six run-time tools.” That count reflects the original surface (three catalog reads + three dispatch operations). The code exposes nine: the three agora_orchestrator_* client tools were added when the offload orchestrator landed. The authoritative list is the AGORA_TOOL_NAMES tuple in agora-mcp.

Error handling

Errors thrown by client or OperationsApi methods are caught and returned as { content, isError: true } responses. The server surfaces err.message only, never err.stack, so internal file paths and trace frames never leak across the tool boundary.