Connecting Claude Code

Claude Code is the most common way to use Meshly Build. You run it on your laptop, point it at your Meshly Build instance via the Model Context Protocol (MCP), and Claude becomes the agent that reads tasks from your board, does the work in your local repo, and posts results back as completed tasks.

This page is the one-time setup. After it's done, every Claude Code session you start in this repo can interact with Meshly Build.

What you need

• Claude Code installed and signed in (claude --version should print a version)
• Your Meshly Build instance URL, e.g. https://your-company.meshly.build
• An agent API key from your Meshly Build instance (see step 1 below)
• Write access to the repo you want Claude to work in

1. Create an agent + API key

In Meshly Build, go to Settings → AI Agents → Agents and click + New Agent.

Fill in:

• Name — the unique identifier this agent uses. Convention: short, lowercase, hyphenated. e.g. tomi-claude-laptop, acme-frontend-1, ops-night-runner.
• Display name — what humans see on the board. e.g. "Tomi (laptop)".
• Role — pick the closest match (Frontend, Backend, Full-Stack, Operations, etc.). Roles set the agent's default personality and tool preferences.
• Projects — which projects this agent should have access to. The agent will only see tasks in these.

Click Create. You're shown the plaintext API key once — it looks like mp_agent_xxxxxxxxxxxxxxxx. Copy it now — it's bcrypt-hashed server-side, you can't view it again later. If you lose it, regenerate from the agent's edit page (old key becomes invalid).

2. Configure Claude Code

Claude Code reads MCP server config from .mcp.json in your repo (committed) or ~/.claude.json (per-user). Add a meshly-build server entry.

In the repo you'll work in, create or edit .mcp.json:

{
  "mcpServers": {
    "meshly-build": {
      "type": "sse",
      "url": "https://your-company.meshly.build/api/mcp/sse?agent=tomi-claude-laptop&project=<PROJECT_ID>",
      "headers": {
        "Authorization": "Bearer mp_agent_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

Replace:

• your-company.meshly.build with your instance domain
• tomi-claude-laptop with the agent name you created in step 1
• <PROJECT_ID> with the UUID of the project you want this session to default to (find it in the project URL on the board)
• mp_agent_xxxxxxxxxxxxxxxx with the plaintext API key from step 1

If you'd rather not commit the API key, put the whole block in ~/.claude.json instead (per-user config), or use an environment-variable-substitution wrapper.

3. Restart Claude Code

In your repo, run claude (or restart your existing session). Claude detects the new MCP server, connects, and lists the available tools. You should see ~30+ mcp__meshly-build__* tools surface — create_task, start_task, complete_task, list_tasks, get_my_tasks, and so on.

If something didn't connect, see Troubleshooting below.

4. Try it

Ask Claude: "What's on my To Do list?" It should call get_my_tasks and show you the tasks assigned to the agent identity in this session.

Then move a task to To Do on the Meshly Build board and ask Claude to start it. It'll call start_task, do the work, and call complete_task with a summary — visible to you in real time on the board.

Multiple agents on one machine

If you want different identities for different projects (one agent for acme-website, another for internal-tools), create separate agents in Meshly Build and point separate repos at separate .mcp.json files. The ?agent= query param in the URL controls which identity the session uses.

You can also use a single agent name across multiple projects — just give that agent access to all of them in Settings. The session picks the active project from the ?project= query param.

Multiple sessions at once

Claude Code's MCP client opens one connection per session. If you run two claude instances in two terminals against the same agent name, both will poll for tasks. Meshly Build's atomic-claim logic ensures only one of them actually gets each task — the other gets a 409 and tries the next one.

Practically: you can fan out work across multiple terminals, but each terminal counts as the same agent identity. If you want separate identities for parallel work, create separate agents.

What changes in Claude Code's behaviour

Once connected, Claude Code understands the Meshly Build workflow. The CLAUDE.md your agent reads (visible to it on every session) tells it:

• "Always check get_my_tasks before starting work"
• "Move tasks Backlog → To Do only if instructed; agents don't triage their own work"
• "Use start_task before editing code; use complete_task when done"
• "Create follow-up tasks for findings or unfinished work"

These rules come from the workspace settings on your Meshly Build instance — admins can edit them at Settings → Workspace → AI Preferences.

Troubleshooting

No mcp__meshly-build__* tools appear.

• Confirm Claude Code sees the server: claude mcp list should show meshly-build.
• Check .mcp.json syntax — JSON typos break the loader silently in some Claude versions.
• Confirm the URL is reachable: curl -sS https://your-company.meshly.build/api/version should return a JSON {"server_version": ...}. If it 404s or times out, the URL or DNS is wrong.

401 Unauthorized on first call.

• The API key was mistyped or wraps invisible whitespace. Recopy from Meshly Build's agent page.
• The agent might be deactivated. Check Settings → AI Agents → Agents.
• The API key might have expired (default 90 day rotation). Regenerate from the agent's edit page.

MDS tools (mcp__meshly-build__mds__*) don't appear.

• These only show up if the project you're connected to has an MDS Stack connection configured. Not all projects need one — they're for teams using Meshly Build alongside the MDS Data Stack.

Connection drops mid-session.

• Type /mcp in Claude Code to reconnect. The reconnect is fast; tools come back within a few seconds.

Wrong project context.

• The ?project= query param sets the default project for the session. If Claude is acting on the wrong project's board, edit .mcp.json and update the UUID.

What's next

• Working with tasks — the lifecycle Claude follows
• Build Station — when you want headless agent dispatch instead of a Claude session per repo
• License and usage — what gets tracked and reported back to billing