Connecting Claude Desktop

Claude Desktop and claude.ai connect to Meshly Build as a remote connector, over OAuth. You do not edit a config file, and you do not need an API key.

This is a different integration from Connecting Claude Code, and it is for a different job. Claude Code is where an agent does the work — it claims tasks, reports them complete, and runs against your repo. Claude Desktop is where you think about the work: read the board, search decisions, capture new tasks, plan a milestone. It deliberately cannot claim or complete tasks.

Requires OAuth to be enabled on your instance. An administrator has to switch it on before the connector will work. Until then the URL is refused. If that is you, see Enabling the connector at the end of this page.

Connect

1. In Claude Desktop or claude.ai, open Settings → Connectors.

2. Choose Add custom connector.

3. Paste your instance's MCP URL:

   https://your-instance.example.com/api/mcp/
   

   Keep the trailing slash. Without it the request is redirected, and some clients turn the redirected handshake into a different kind of request — which fails with no useful explanation.

4. Click Add. Claude registers itself with your instance automatically; there is no client ID or secret to copy.

5. Sign in when prompted, using the same account you use for Meshly Build.

6. Approve the request on the consent screen.

The consent screen names which instance and which account you are granting access to. If you have access to more than one Meshly Build instance, check that line before approving — it is the only place the distinction is visible.

Choose a project

A Desktop conversation is scoped to one project. Pick it whichever way suits you:

• Type / and choose meshly.project.focus. With nothing typed it lists your projects; with a name it selects that one and shows a briefing.
• Use the attachment menu. Your projects appear as attachable items; opening one focuses it.
• Just ask. "What projects do I have?" then "let's talk about Meshly Build."

Your choice is remembered for that connector, including across restarts. Two connectors — say Desktop and claude.ai — can sit on different projects at once.

If you ask about tasks before choosing, the answer lists your projects so you can pick one and carry on.

What Desktop can and cannot do

You can: browse projects, tasks, milestones and epics; search knowledge and decisions; read the dashboard and worklog; create and update tasks; move them between columns; comment on them; and assign them to a milestone or epic.

You cannot: start_task, complete_task, block_task, approve_task or reject_task.

That is deliberate, not an oversight. Meshly Build enforces one in-progress task per agent per project, so a task claimed from a chat window would collide with the coding agent actually working on it — or silently take the claim away from it. If you want work started, hand it to an agent. Desktop is for deciding what should be started.

Infrastructure tools (the MDS and portal proxies) are also unavailable in Desktop.

Troubleshooting

"Page not found" after approving, or the connector never finishes. The OAuth endpoints are not reachable. An administrator should run:

bash deploy/check-oauth-routing.sh https://your-instance.example.com

That reports any endpoint being served by the web app instead of the API — the most common cause, since the reverse proxy needs explicit rules for them.

The connector rejects the URL immediately. OAuth is not enabled on the instance. See below.

Tools appear but every call says no project is selected. Choose a project — see Choose a project above. The error itself lists what is available.

start_task is missing. Working as intended — see What Desktop can and cannot do.

Enabling the connector (administrators)

Three things are required, and a deploy only does the first:

1. Ship a build with the connector — v3.2.0 or later.
2. Set OAUTH_ENABLED=true in the instance's environment file, then recreate the API container. A plain restart is not enough: the environment file is read when the container is created, so a restarted container keeps its old settings.
3. Add reverse-proxy rules for /.well-known/oauth-* and /oauth/{authorize,token,register,revoke} on the host nginx config. A deploy regenerates only the per-instance container config, so the host file is edited by hand. /oauth/consent must keep going to the frontend — it is a page, not an API.

Verify all three at once:

bash deploy/check-oauth-routing.sh https://your-instance.example.com

On a shared-mode instance serving several customer subdomains, each subdomain needs its own proxy rules, and the OAuth issuer is derived per subdomain. Confirm tenant isolation before enabling it for customers.

Managing connected clients

Anyone who can sign in can register a connector — that is how the protocol works, and it is why the consent screen exists. Registration is rate-limited and capped per instance.

Revoking a client currently requires a database change; the admin screen for it is not yet built. Access tokens are short-lived and refresh tokens rotate on every use, so a stolen refresh token invalidates the whole grant the moment the real client next refreshes.