---
title: "Connecting Claude"
description: "Connect Claude Code, Claude Desktop or claude.ai to Maestro — and why Claude Code needs two paste steps rather than one."
canonical: "https://help.sitesmojo.com/kb/getting-started/connecting-claude/"
---

The portal builds your connection details for you. Sign in at
`maestromojo.com/workspaces/`, open the user-chip menu top right, and choose
**Connect Claude**. Then pick the tab for your client.

## Claude Code

Two paste steps, in this order.

**Step 1** goes into a session's chat. It carries the exact
`claude mcp add --scope user …` command plus follow-up instructions, so Claude
adds the server, health-checks it, and reports the real error instead of
improvising a different URL.

**Then restart Claude Code.** This is not optional — Claude Code reads MCP
configuration only at session start, which is the entire reason there are two
steps.

**Step 2** goes into the new session. It calls `whoami()` to prove the key
works, and offers to install the Maestro work skills.

`--scope user` matters. The CLI default is `local`, which files the server under
the current directory only — Maestro then disappears in every other repository.
See [Maestro vanished in another repository](../maestro-not-in-this-repo/).

## Claude Desktop and claude.ai

These clients cannot send an `Authorization` header, so the key rides in the
URL instead. Copy the connector URL — it looks like
`https://maestromojo.com/mcp/k/<token>` — then in your client go to
**Settings → Connectors → Add custom connector** and paste it.

Treat that URL as a credential. Anyone holding it is you.

## Connecting from inside Claude, with no portal

If you are starting from a client already pointed at the hosted server,
registration is self-contained. Ask Claude to run:

```
register(email="you@example.com")
```

A six-digit code arrives by email. Then:

```
verify(email="you@example.com", code="847291")
```

The reply carries your API key, your personal connector URL, and setup
instructions. This works identically for brand-new and existing users.

## The dialog says "Connected ✓" only after a tool call

Adding the server does not move it. The dialog is waiting on the first real
*tool* call — which is what step 2's `whoami()` is for. If it still reads
disconnected, the server was added but nothing has called it yet.

## Rotating a key, deliberately

Re-running `verify()` **rotates** the key: the previous token and connector URL
stop working immediately. The portal and MCP flows manage the same single key,
so either side can re-show or rotate it.

Rotate on purpose. Do not rotate as a diagnostic — see
[whoami() fails](../whoami-fails/) for why that usually makes things worse.