MCP quickstart

The MCP endpoint lets an agent work against the same task graph the Operator Desk shows in the browser.

Connect

Configure your MCP client with:

POST https://app.meshive.io/api/mcp
Authorization: Bearer <agent-token>

Tokens are created in Agent tokens inside the Operator Desk. A token belongs to one workspace and may be scoped to specific projects.

Discover work

Start by listing projects:

list_projects

Then list tasks for a project:

list_tasks({ "projectId": "web-app" })

Use get_task to inspect a task’s full graph:

get_task({ "taskId": "WEB-7" })

Create a task

When no task exists yet, create one as a DAG of steps:

{
  "projectId": "web-app",
  "title": "Add retry handling to MCP calls",
  "description": "Make transient MCP transport failures recoverable.",
  "branch": "feat/mcp-retries",
  "steps": [
    {
      "id": "plan",
      "category": "Plan",
      "title": "Plan the change",
      "dependsOn": [],
      "objective": "Identify where retry behavior belongs.",
      "acceptanceCriteria": ["Plan names affected modules and tests."],
      "expectedArtifactKind": "plan_doc"
    },
    {
      "id": "exec",
      "category": "Implement",
      "title": "Implement retry handling",
      "dependsOn": ["plan"],
      "objective": "Add bounded retry behavior for transient failures.",
      "acceptanceCriteria": ["Retries are bounded.", "Permanent auth errors are not retried."],
      "expectedArtifactKind": "diff"
    },
    {
      "id": "test",
      "category": "Test",
      "title": "Verify retry behavior",
      "dependsOn": ["exec"],
      "objective": "Prove retry behavior with focused checks.",
      "acceptanceCriteria": ["Tests cover success after retry and no retry on auth failure."],
      "expectedArtifactKind": "test_report"
    },
    {
      "id": "gate",
      "category": "Human approval",
      "isGate": true,
      "gatePrompt": "Approve the retry handling before downstream work continues.",
      "title": "Human approval",
      "dependsOn": ["test"]
    }
  ]
}

create_task returns the assigned task id and a mapping from local step ids to Meshive step ids, such as WEB-7.1.

Run ready steps

Ask Meshive what can run now:

next_ready_steps({ "taskId": "WEB-7" })

For a normal ready step:

1. Call get_step_brief for the step id.
2. Call start_step.
3. Do the work in the local workspace.
4. Call complete_step with an artifact.

Example completion:

{
  "stepId": "WEB-7.2",
  "artifactKind": "diff",
  "artifactTitle": "Retry handling implementation",
  "artifactBody": "Implemented bounded retries in the MCP client path and added focused tests."
}

Completing a step automatically readies dependent steps whose dependencies are all done.

Prefer modeling approval as its own gate step after the work that needs review. Set isGate: true and, when useful, gatePrompt for the text shown to the operator.

Keep the board honest

Use set_task_state as work moves:

• running when an agent starts active work.
• awaiting_decision when a gate has been requested and the task is waiting on a human.
• failed when the agent cannot proceed or needs a replan.
• done when the task is complete.

Humans can also move cards in the Operator Desk. The next agent call should report the agent’s current view of the task state.

Handle human gates

When next_ready_steps returns a gate step, do not call start_step or complete_step.

Call:

request_gate({ "stepId": "WEB-7.4" })

Then poll:

get_gate_status({ "stepId": "WEB-7.4" })

Continue only when the gate is approved. If it is rejected, stop and replan or ask for operator direction.