MCP and HTTP

The same managed-job lifecycle is available over stdio MCP and a local HTTP server. A disconnected client does not stop the job; reconnect with its job_id.

MCP stdio

agent-exec mcp exposes run, status, tail, wait, and kill.

MCP run also accepts the optional completion sinks notify_command and notify_file, persisted before the workload launches. When a sink was persisted and the job is still running, the response adds an optional notification object with state set to armed, the generic sinks classes, and polling_required set to false: completion reaches the configured sink, so repeated wait, status, or tail polling is unnecessary. The object is omitted whenever no sink was persisted, and armed does not guarantee downstream delivery.

AGENT_EXEC="$(command -v agent-exec)"
"$AGENT_EXEC" mcp

HTTP server

agent-exec serve binds to 127.0.0.1:19263 by default. --port changes only the loopback port. A non-loopback --bind requires --insecure and a nonempty AGENT_EXEC_SERVE_TOKEN.

Bearer authentication protects only POST /exec and POST /kill/{id}. Read endpoints remain unprotected. Keep the default loopback bind or add a private network, firewall, or authenticating reverse proxy. Do not expose the server directly to the public internet.

--allow-origin permits one explicit CORS origin. The wildcard * is rejected.

Method	Endpoint	Equivalent
GET	`/health`	Health envelope
POST	`/exec`	`run`
GET	`/status/{id}`	`status`
GET	`/tail/{id}`	`tail`
GET	`/wait/{id}`	`wait --forever`
POST	`/kill/{id}`	`kill`

Start one HTTP job

curl -X POST http://127.0.0.1:19263/exec \
  -H 'Content-Type: application/json' \
  -d '{"command":["sh","-c","echo hello"]}'

Documented handler responses use the CLI schema_version, ok, and type envelope. POST /exec requires a nonempty command array of strings. Optional fields are cwd, env, timeout, wait, until, and max_bytes. Unknown fields are rejected.