Catalog of the MCP tool surface and HTTP routes. For call-contract footguns, use the wire descriptions in src/tools/ (mirrored on the site tool reference). For behavioral depth, follow the links to architecture models.
When the server starts with --transport=http (or TRANSPORT=http / npm run start:http), it exposes these routes. stdio mode does not open an HTTP listener.
| Method / path |
Purpose |
GET /health |
Liveness — process is up |
GET /ready |
Readiness — workflowDir, schemasDir, and workspaceDir exist; engineeringDir when split from workspace (--repo layout); and sessionKeyWritable (HMAC key directory is usable) |
POST /mcp |
MCP Streamable HTTP (client → server messages) |
GET /mcp |
MCP Streamable HTTP (server → client stream when the session uses GET) |
DELETE /mcp |
MCP Streamable HTTP (end session) |
/ready returns 503 when any check is false. A green /health alone does not mean start_session can run — verify sessionKeyWritable: true (Docker non-root with HOME=/ historically failed here; see http.md and WORKFLOW_SERVER_KEY_DIR).
Responses include an x-request-id header (echoed when the client supplies one). Place the listener behind network access control or a reverse proxy; the server does not implement application-level authentication. Local mcp-remote clients may probe OAuth well-known URLs (/.well-known/oauth-*) and receive 404s; that is expected without auth and is logged as info, not error. See setup.md, http.md / stdio.md (transports), and development.md for process env (developers).
Most tools take a session_index from start_session. Bootstrap tools do not. Each authenticated response includes session_index and advisory _meta.validation where applicable.
| Tool |
Parameters |
Returns |
Description |
discover |
— |
Server info, bootstrap stub |
First call: how to start a session. Always pass repo on start_session. |
list_workflows |
— |
Workflow list (id, title, version, tags) |
Catalog of available workflows. |
health_check |
— |
Status, version, workflow count, uptime |
Process health. |
| Tool |
Parameters |
Returns |
Description |
start_session |
agent_id, workflow_id?, planning_folder?, repo?, context_mode? |
session_index, planning path, workflow info, optional repo |
Open or resume a top-level session (default workflow: meta). Always pass repo: "owner/repo" — written to session.json#repo (multi-root plans under $HOST_PROJECTS_ROOT/<repo>/.engineering/…). State · Reference delivery |
dispatch_child |
session_index, workflow_id, agent_id?, planning_slug?, repo?, context_mode? |
Child session_index |
Start a nested workflow under the current session. Uses session.repo; optional repo binds if missing (must match if set). Dispatch |
get_workflow_status |
session_index |
Status, current/completed activities, checkpoint hint |
Snapshot of where the session is. |
inspect_session |
session_index, view?, child_index?, variable? |
Compact projection |
Read-only view of session state (usable while blocked). |
Require session_index. Workflow identity comes from the session.
| Tool |
Parameters |
Returns |
Description |
get_workflow |
session_index |
Orchestrator technique bundle + workflow stubs |
Orchestrator load: rules, variables, initialActivity, activity list. Resolution |
next_activity |
session_index, activity_id, manifests? |
activity_id, name; trace in _meta |
Advance to an activity (does not return its body). Fidelity |
get_activity |
session_index, context_tokens, bundle? |
Worker bundle + activity body |
Worker load for the current activity. context_tokens is required. Bundling |
yield_checkpoint |
session_index, checkpoint_id |
yielded or replayed |
Pause for a user decision (or replay a prior answer). Checkpoints |
resume_checkpoint |
session_index |
Status |
Worker continues after the checkpoint is resolved. |
present_checkpoint |
session_index |
Message, options, effects |
Load the active checkpoint for the user. |
respond_checkpoint |
session_index, one of option_id / auto_advance / condition_not_met |
Resolution + effects |
Clear the active checkpoint. |
| Tool |
Parameters |
Returns |
Description |
get_technique |
session_index, step_id?, full? |
Composed technique (or unchanged marker) |
Load one technique on demand. Resolution |
get_resource |
session_index, resource_id, full? |
Resource body (or unchanged marker) |
Load reference material by slug (workflow/id or #section). |
| Tool |
Parameters |
Returns |
Description |
get_trace |
session_index, trace_tokens? |
Trace events |
Decode accumulated trace tokens or return the in-memory session trace. Fidelity |