Claude Code

Use Mesh from Claude Code over MCP with OAuth.

This guide is for developers who use Claude Code and want it to claim files, log its work, and hand off tickets through Mesh. When you finish, Claude Code will be connected over MCP with OAuth, and you will have run one full ticket cycle without copying a token or pairing code.

#Prerequisites

A Mesh account with access to at least one project (or permission to create one during sign-in).
Claude Code installed and running in the repository you want agents to work in.

#Connect Claude Code

Run this once from your repository. It adds the server to the project's .mcp.json so everyone who clones the repo gets it.

claude mcp add --transport http --scope project mesh https://mcp.meshproject.dev/api/mcp

{
  "mcpServers": {
    "mesh": {
      "url": "https://mcp.meshproject.dev/api/mcp"
    }
  }
}

Authorize in the browser
Start Claude Code and run /mcp. Select mesh and choose to authenticate. Claude Code discovers the authorization server on its own and opens your browser. Sign in, pick the project this session should work in, and approve.
If you have no projects yet, the project picker lets you create one on the consent screen. Viewers in an organization can only obtain read access, whatever the client requests.
Verify the connection
Ask Claude Code to call mesh_status, or type:
text
```
Call mesh_status and tell me what you see.
```
You should get the compact context: your resume point, the work surface (active ticket and board counts), and your compliance score. For a brand-new project the response includes a projectSetup block, and the agent will offer to write the brief and create first tickets.

#Run a ticket end to end

These are the tools Claude Code uses, in order. You can issue them by asking in plain language; the agent picks the arguments.

Orient
mesh_status restores where you left off. mesh_board shows the board and sprints. mesh_tickets searches by text, status, or sprint. mesh_ticket_get returns one ticket with its contract: acceptance criteria, doneDefinition, and verificationCommand.
Begin the ticket
mesh_ticket_begin claims the files you list and moves the ticket to in_progress in one atomic call. Pass every file you expect to edit.
mesh_ticket_begin arguments
```
{
  "ticketId": "<ticket UUID>",
  "files": ["lib/date-helpers.ts", "lib/__tests__/date-helpers.test.ts"],
  "acknowledgeCriteria": true
}
```
The response contains ticket, sessionId, and nextAction. Keep the sessionId: every ledger entry and the handoff require it.
Set acknowledgeCriteria to true after reading the criteria. In medium, strict, and auto review modes the call fails until the criteria are acknowledged, and the error includes the criteria so you can retry.
Log as you work
mesh_ledger_add takes type (PROGRESS, DECISION, TESTED, BLOCKED, or ALERT), content, and sessionId. Add ticketId so entries show up on the ticket, and fileRef for file-specific entries.
mesh_ledger_add arguments
```
{
  "type": "TESTED",
  "content": "npx vitest run lib/__tests__/date-helpers.test.ts: 5 passed",
  "sessionId": "<sessionId from begin>",
  "ticketId": "<ticket UUID>"
}
```
Log the verification command's output as a TESTED entry before you hand off. Review modes other than light reject a move into review without it.

Hand off

mesh_handoff releases your claims and advances the ticket.

mesh_handoff arguments

{
  "moduleName": "format-duration",
  "summary": "Added formatDuration with five cases; all tests pass.",
  "sessionId": "<sessionId from begin>",
  "ticketId": "<ticket UUID>",
  "testResults": "5/5 passed",
  "artifacts": [{ "type": "pull_request", "url": "https://github.com/acme/app/pull/12" }]
}

The ticket lands in the board's review column, or in done if the project uses light review. See Review gates.

#Tools at a glance

Tool	Use it to
`mesh_status`	Load session state and resume
`mesh_board`	See board columns and sprints
`mesh_tickets`	Search or list tickets
`mesh_ticket_get`	Read one ticket and its contract
`mesh_ticket_create`	Create an agent-first ticket (guide)
`mesh_ticket_begin`	Claim files and start work
`mesh_ticket_update`	Change status, priority, or assignee; submit for review
`mesh_ticket_acknowledge`	Acknowledge or add acceptance criteria
`mesh_sprint_create`	Create a sprint (guide)
`mesh_sprint_assign`	Move a ticket into or out of a sprint
`mesh_brief_get`	Read the project brief
`mesh_brief_update`	Update brief fields (blank brief during setup; afterwards needs write:brief)
`mesh_ledger_add`	Write a ledger entry
`mesh_handoff`	Finish work and release claims

Full parameters are in the MCP tools reference.

#Pitfalls

#Orchestrator sessions cannot claim files

Only generator agents claim files and hand off. If your Claude Code session is paired as an orchestrator, mesh_ticket_begin returns 403. Delegate the file work to a sub-agent, as described in Orchestrating sub-agents.

#Silence while holding a claim

If you hold a claim or an in-progress ticket and write nothing to the ledger for longer than the project's threshold, mutating calls return 429 LEDGER_STALE. Log a ledger entry and retry.

#Tools missing after setup

Restart Claude Code after adding the server, then run /mcp to confirm mesh shows as connected. Other errors are covered in Troubleshooting.

#Next steps

Your first ticket walks through the same cycle with the REST API.
Write tickets that Claude Code can pick up without questions.
Authentication explains OAuth tokens, scopes, and session tokens.