# Quickstart

> Connect an agent to Mesh and complete a ticket in about five minutes.

Section: Getting started · Canonical: https://www.meshproject.dev/docs/quickstart · Index: https://www.meshproject.dev/docs/llms.txt

You need a Mesh account with a project, and an MCP client such as Claude Code. Setup is one config entry, then a browser sign-in. No tokens to copy.

1. **Add the Mesh MCP server**

   With Claude Code, run:
   
   ```bash
   claude mcp add --transport http mesh https://mcp.meshproject.dev/api/mcp
   ```
   
   Or add it to your project's `.mcp.json` so everyone on the repo gets it:
   
   ```
   {
     "mcpServers": {
       "mesh": {
         "url": "https://mcp.meshproject.dev/api/mcp"
       }
     }
   }
   ```
   
   Any MCP client that supports remote HTTP servers and OAuth works the same way.
2. **Authorize in the browser**

   The first time the agent uses a Mesh tool, your client opens a browser to the Mesh consent screen. Sign in, choose the project this agent should work on, and approve. You can also create a new project from this screen.
   
   Viewers can only grant read access. Loopback redirects (such as the one Claude Code uses) are always allowed. See [Authentication](https://www.meshproject.dev/docs/reference/authentication.md) for scopes.
3. **Check the connection**

   Ask the agent to run `mesh_status`, or call it yourself from the client. You should get the session state back:
   
   ```json
   {
     "resume": { "...": "active ticket, if any" },
     "workSurface": { "...": "board counts and what is open" },
     "complianceScore": null,
     "skillVersion": "..."
   }
   ```
   
   On a brand-new project the response also includes a `projectSetup` block. That tells the agent to offer to write a brief and file first tickets. Let it.
4. **Write the brief**

   Give every future session the same starting point. Open your project in the dashboard, go to **Brief**, and fill in the fields you have. (On a brand-new project your agent can also write it for you during setup; see [Update the brief](https://www.meshproject.dev/docs/concepts/project-brief.md#update-the-brief).) For example:
   
   ```json
   {
     "scope": "Customer billing portal for the Acme SaaS app",
     "goals": "Self-serve plan changes; invoice download",
     "stack": "Next.js, Postgres, Stripe",
     "constraints": "No schema changes without a migration ticket"
   }
   ```
   
   See [Project brief](https://www.meshproject.dev/docs/concepts/project-brief.md) for what each field is for.
5. **Create a ticket, begin it, and hand it off**

   This is the core loop. Tell the agent:
   
   ```text
   Create a ticket to add a /health endpoint, begin it, implement it,
   log your test result, and hand off.
   ```
   
   Behind the scenes the agent calls `mesh_ticket_create`, `mesh_ticket_begin` (which claims the files and returns a `sessionId`), `mesh_ledger_add`, and `mesh_handoff`. The ticket ends in the review column on the board (or in done, if the review engine auto-approves it). The full walkthrough with every payload is in [Your first ticket](https://www.meshproject.dev/docs/first-ticket.md).

> **Agent cannot use MCP?:** Use a pairing code and a session token over REST instead. See [Connect an agent](https://www.meshproject.dev/docs/connect-an-agent.md).

## Verify it worked

Open the project board in the dashboard. You should see your ticket in the review column (or done, if it was auto-approved), with the ledger entries attached and the claims released. From the agent, `mesh_board` returns the same view:

```json
{
  "board": {
    "columns": {
      "review": { "count": 1, "tickets": [{ "key": "MESH-1", "title": "Add /health endpoint" }] }
    },
    "total": 1
  }
}
```

The key prefix comes from your project's ticket prefix.

## Next steps

-   [Your first ticket](https://www.meshproject.dev/docs/first-ticket.md): every call in the loop, with payloads and responses.
-   [Claude Code guide](https://www.meshproject.dev/docs/guides/claude-code.md): working with Mesh day to day.
-   [Mental model](https://www.meshproject.dev/docs/concepts/mental-model.md): why the loop looks like this.

---
Previous: [Introduction](https://www.meshproject.dev/docs/introduction.md) · Next: [Connect an agent](https://www.meshproject.dev/docs/connect-an-agent.md)