# Connect an agent to M2

M2 is a remote MCP server. Every client needs the same three facts:

- **name**: `m2`
- **url**: `https://mcp.m2ui.ai/mcp`
- **transport**: streamable HTTP · **auth**: OAuth in the browser (no API key — never ask the user to create one)

After adding it, the `canvas_*` tools usually appear only after the client is **restarted or reconnected**. Tell the user this explicitly.

The quickest route is `npx -y @m2canvas/connect@latest --client <you>`, where `<you>` is your own client: `claude-code`, `codex`, `cursor`, `opencode` or `qoder`. It adds M2 to that client only, and needs network access to download (if your sandbox blocks the network, ask the user to allow it rather than waiting). Run from your shell (no interactive terminal), it adds the server and prints the remaining sign-in step: run it if it's a command, otherwise pass it on to the user. The sections below are for when you can't run it.

## Claude Code

```bash
claude mcp add --transport http --scope user m2 https://mcp.m2ui.ai/mcp
```

Use `--scope user`: the default scope (`local`) only applies to the current folder.
Then ask the user to type `/mcp`, pick `m2`, and choose **Authenticate** — the browser sign-in opens from there.
Don't run `claude mcp login m2` yourself or suggest it with the `!` prefix: it needs an interactive terminal and fails inside a session ("stdin isn't a terminal").
If the `canvas_*` tools still don't appear after sign-in, the user restarts Claude Code (`claude --continue` keeps the conversation).
If `claude mcp get m2` shows "Disabled for this project", the user turned it off in this folder earlier; ask them to re-enable it in `/mcp` rather than editing the config yourself.

## Codex

```bash
codex mcp add m2 --url https://mcp.m2ui.ai/mcp
codex mcp login m2
```

Both are required — without `login` the server is added but unauthorised.
These write `~/.codex/config.toml`, outside the workspace; if your sandbox blocks the write, ask the user to approve it. Restart Codex afterwards.

## Cursor

Add to `~/.cursor/mcp.json`:

```json
{ "mcpServers": { "m2": { "url": "https://mcp.m2ui.ai/mcp" } } }
```

## Qoder (CLI and desktop app)

```bash
qodercli mcp add -s user -t http m2 https://mcp.m2ui.ai/mcp
```

The CLI and the Qoder desktop app share `~/.qoder/settings.json`, so this one command covers both. If `qodercli` isn't on PATH, try `~/.local/bin/qodercli`.
There is no MCP login subcommand. Ask the user to sign in in Qoder: Extensions → Connectors → m2 → Authorize (or run `qodercli`, then `/mcp`). A running session picks it up after `/mcp reload`.

## OpenCode

Don't use `opencode mcp add`: it always writes the new nested `mcp.servers.<name>` format, and if the config already has old flat entries (`mcp.<name>`), the new server is not found afterwards.
Instead, edit `~/.config/opencode/opencode.json` and add an entry in the format the file already uses. For flat entries, or when `mcp` is empty:

```json
{ "mcp": { "m2": { "type": "remote", "url": "https://mcp.m2ui.ai/mcp", "enabled": true } } }
```

If every existing entry sits under `mcp.servers`, add `"m2": { "type": "remote", "url": "https://mcp.m2ui.ai/mcp" }` there instead. Keep all other entries. If the file is `opencode.jsonc`, keep its comments.
Then sign in with `opencode mcp auth m2`; it opens the browser and times out if the sign-in isn't finished. If `opencode` isn't on PATH, the macOS app ships it at `/Applications/OpenCode.app/Contents/Resources/opencode-cli`. Restart OpenCode afterwards.

## Any other client

If it supports remote MCP over streamable HTTP, use the three facts above.
If it only supports stdio, bridge it:

```bash
npx mcp-remote https://mcp.m2ui.ai/mcp
```

## Verify

After the restart, `canvas_*` tools (e.g. `canvas_ping`) should be listed. If they are not, report which step failed — don't guess.