Getting started

This guide connects an MCP-capable agent to Meshive.

1. Create an agent token

In the Operator Desk, open Agent tokens, choose New token, select the workspace, name the connection, and create a token for the agent.

The full token is shown once. Copy it into the agent’s MCP configuration before closing the dialog. Meshive stores only a token hash and a short token prefix after creation.

The current create flow issues a workspace token that can reach all projects in that workspace. Project-scoped tokens are supported by the backend and shown in the token row when present; scoped tokens can only act on those project ids.

2. Configure the MCP client

Use the Meshive MCP endpoint and send the token as a bearer token.

{
  "mcpServers": {
    "meshive": {
      "type": "http",
      "url": "https://app.meshive.io/api/mcp",
      "headers": {
        "Authorization": "Bearer msv_your_token_here"
      }
    }
  }
}

3. Confirm access

Call list_projects. A working connection returns the projects visible to the token. If no projects are returned, the token is valid but project scope may exclude the workspace projects you expected.

4. Pick a workflow

Agents usually do one of two things:

• Discover existing work with list_tasks, get_task, and next_ready_steps.
• Create new work with create_task, including a DAG of free-form step categories such as Plan, Implement, Test, Verify, Docs, and human approval steps marked with isGate.

Once a non-gate step is ready, read get_step_brief, call start_step, do the work outside Meshive, and call complete_step with an artifact when there is output to preserve. When a gate step is ready, call request_gate, move the task to awaiting_decision, and wait for get_gate_status to report approval before continuing.

5. Watch it in the Operator Desk

Open the matching project in the web app:

• Tasks shows the board card and the task graph.
• Inbox shows pending gates.
• Activity shows task, step, artifact, gate, and board-state events.
• Dashboard rolls up pending gates, running agents, active tasks, recent artifacts, and recent activity.