Skip to content
Meshive Docs

Troubleshooting MCP

Use this page when an MCP client connects but tools fail, or when a task graph does not progress as expected.

Unauthorized

Section titled “Unauthorized”

The endpoint requires a bearer token:

Authorization: Bearer <agent-token>

If the header is missing, invalid, or revoked, Meshive rejects the handshake or returns an authorization error. Create a new token in Agent tokens and update the MCP client config.

Invalid or revoked agent token

Section titled “Invalid or revoked agent token”

Meshive stores token hashes, not raw tokens. The full token is shown once at creation time. If it was lost, revoke the old connection and create a new token.

Not authorized for project, task, step, or issue

Section titled “Not authorized for project, task, step, or issue”

Tokens belong to a workspace and can be scoped to project ids. A scoped token can only list or mutate projects in scope. Use list_projects to confirm what the token can see.

Step is blocked

Section titled “Step is blocked”

start_step and complete_step require all dependencies to be done. Call get_task to inspect the graph, then finish upstream steps first.

Gate steps cannot be started or completed

Section titled “Gate steps cannot be started or completed”

Gate steps are resolved by humans. When a gate is ready, call request_gate, move the task to awaiting_decision, and poll get_gate_status.

If you need approval after executable work, model the approval as a separate downstream gate step with isGate: true. Gate steps should not carry work that still needs start_step and complete_step.

Step already done

Section titled “Step already done”

Meshive rejects completing an already-done step. Use get_task before retrying after a client restart.

Issue status will not update manually

Section titled “Issue status will not update manually”

Linked issues derive their status from linked task board states. If an issue is linked to tasks, update the task state or unlink the task before setting issue status manually.

The board does not match the agent’s work

Section titled “The board does not match the agent’s work”

Agents should call set_task_state as their work changes. Use:

  • running when active work starts.
  • awaiting_decision when waiting on a gate.
  • failed when dependencies, missing information, or rejected gates stop progress.
  • done when the task is complete.

Humans can also drag cards in the Operator Desk. The agent’s next set_task_state call records the agent’s current view and writes an activity event.