cueport
cueport gives an MCP host or a terminal access to CueAPI, the coordination layer for agent work: schedule cues (recurring cron or one-time), fire them on demand, watch their executions, claim worker executions, keep a claim alive with heartbeats, and close the loop by reporting an outcome backed by evidence. One binary serves a command-line interface and a stdio MCP server.
An API key is required. Set CUEAPI_API_KEY to a key from your
CueAPI account; every call sends it as Authorization: Bearer <key>, and a missing key fails before any request is attempted.
Self-hosting or testing against another host? Set CUEAPI_BASE_URL
alongside the key; when it is unset, calls go to
https://api.cueapi.ai.
Install
npx @reneturcios/cueport list-cues
Or run the container image:
docker run -i ghcr.io/cloudcorprecords/cueport
The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.
CLI
cueport create-cue --name digest --schedule "0 9 * * *" --callback-url https://example.test/hook
cueport list-cues --status active --limit 5
cueport get-cue cue_abc123
cueport fire-cue cue_abc123 --payload-override '{"topic":"release notes"}'
cueport update-cue cue_abc123 --name "morning digest"
cueport pause-cue cue_abc123
cueport resume-cue cue_abc123
cueport delete-cue cue_abc123
cueport list-executions --cue-id cue_abc123 --status failed
cueport get-execution exec_123
cueport list-claimable --task digest --agent worker-a
cueport claim-execution exec_123 --worker-id worker-7
cueport claim-next --task-name digest --worker-id worker-7
cueport heartbeat exec_123 --worker-id worker-7
cueport report-outcome exec_123 --outcome succeeded --external-id ext_42 --result-url https://example.test/result
cueport --version
Commands print the upstream JSON payload. Exit codes: 0 on
success, 1 when a call fails (including a missing API key or an
upstream API error), 2 for usage errors.
Two behaviours are worth knowing. Pausing and resuming are not
separate endpoints: both are a PATCH /v1/cues/{id} carrying only a
status field (paused or active). And claim-next is a fan-out,
not a single call: the claim endpoint has no task filter, so the
tool first fetches the server-side filtered claimable list, picks
the oldest entry, and then claims that execution by id.
MCP server
One bin serves both faces. The mcp subcommand starts a stdio MCP
server:
npx -y @reneturcios/cueport mcp
MCP client configuration:
{
"mcpServers": {
"cueport": {
"command": "npx",
"args": ["-y", "@reneturcios/cueport", "mcp"],
"env": {
"CUEAPI_API_KEY": "cue_sk_..."
}
}
}
}
Add CUEAPI_BASE_URL to the env block to point the server at a
different CueAPI-compatible host.
Tools
| Tool | Input | What it does |
|---|---|---|
cueapi_create_cue | name, schedule (required); optional description, callback, method, timezone, payload, task and platform fields | Create a recurring or one-time cue. |
cueapi_list_cues | status, limit (optional) | List cues, filtered by status. |
cueapi_get_cue | cue_id | Fetch one cue. |
cueapi_fire_cue | cue_id; optional payload_override, merge_strategy (merge default, or replace) | Fire a cue immediately. |
cueapi_update_cue | cue_id plus any mutable cue fields | Sparse update; only provided fields are sent. |
cueapi_pause_cue | cue_id | Pause a cue (PATCH with status paused). |
cueapi_resume_cue | cue_id | Resume a cue (PATCH with status active). |
cueapi_delete_cue | cue_id | Delete a cue permanently. |
cueapi_list_executions | cue_id, status, limit (optional) | List executions, filtered by cue and status. |
cueapi_get_execution | execution_id | Fetch one execution, with state and outcome. |
cueapi_list_claimable_executions | task, agent, limit (optional) | List unclaimed worker executions, filtered server-side. |
cueapi_claim_execution | execution_id; optional worker_id | Atomically claim one execution. |
cueapi_claim_next_execution | task_name, worker_id (optional) | Claim the oldest claimable execution. |
cueapi_execution_heartbeat | execution_id, worker_id (both required) | Extend a claim lease; worker_id travels in the X-Worker-Id header. |
cueapi_report_outcome | execution_id, outcome (required); optional evidence fields | Report a write-once outcome with evidence. |
Development
npm install
npm run build # tsc -> dist/
npm test # node test runner over test/*.test.ts, no network (fake fetch fixtures)
npm run dev # run the CLI from source via tsx
License
MIT — see LICENSE.