# Chamade — Setup Guide

Follow these steps IN ORDER. Do not skip any step.

## Step 1: Create .mcp.json

Create `.mcp.json` in the project root.

### If the user's MCP client speaks Streamable HTTP (Claude Desktop recent, Claude Code, Cursor, Windsurf, most 2026+ clients):

```json
{
  "mcpServers": {
    "chamade": {
      "type": "http",
      "url": "https://mcp.chamade.io/mcp/",
      "headers": {
        "Authorization": "Bearer REPLACE_WITH_YOUR_KEY"
      }
    }
  }
}
```

### If the user's MCP client is stdio-only (older Claude Desktop, OpenClaw, older Windsurf, etc.):

Use the `@chamade/mcp-server@3` stdio shim — it is a thin wrapper that bridges stdio to the same hosted HTTP endpoint:

```json
{
  "mcpServers": {
    "chamade": {
      "command": "npx",
      "args": ["-y", "@chamade/mcp-server@3"],
      "env": {
        "CHAMADE_API_KEY": "REPLACE_WITH_YOUR_KEY"
      }
    }
  }
}
```

Replace `REPLACE_WITH_YOUR_KEY` with the API key the user gave you (starts with `chmd_`).

## Step 2: Tell the user to restart Claude Code with the channel flag

For real-time push events (new DMs, incoming calls, call state changes), the user MUST launch Claude Code with this exact command:

```
claude --dangerously-load-development-channels server:chamade --continue
```

Tell the user to run this command NOW. A normal `claude` launch will NOT enable real-time push — the tools still work but events will only be visible by polling (`chamade_call_status`, `chamade_inbox`). Thanks to `--continue`, this conversation will resume automatically after restart and you will keep your full context.

About the flags:
- `--dangerously-load-development-channels server:chamade` is a CLIENT-side opt-in that tells Claude Code to process `notifications/claude/channel` messages from the MCP server named `chamade`. The "dangerously" prefix is standard Claude Code naming for flags that load MCP channels not yet on the official Anthropic allowlist — it is NOT dangerous in a security sense, it's the normal way to use channels during the research preview. Required on every launch (per-session, not persisted in any config file).
- `--continue` resumes the current conversation so you keep your context after the restart.
- The flag is transport-agnostic: required whether `chamade` in `.mcp.json` uses `"type": "http"` or the `@chamade/mcp-server@3` stdio shim. The server name after `server:` must match the key you used in Step 1.

If the user has multiple Chamade entries (e.g. `chamade` pointing at prod HTTP and `chamade-dev` pointing at dev), pass the flag once per entry:

```
claude --dangerously-load-development-channels server:chamade server:chamade-dev
```

## Step 3: Check account and platform status

Call `chamade_account` (or `GET /api/account`) to bootstrap. The response has three sections you care about:

**`features`** — what the gateway supports globally. In early access you should see:
- `transport`, `audio_in`, `audio_out`, `text_chat`, `typing_indicators`, `files` all `"ready"`
- `hosted_stt` and `hosted_tts` set to `"beta_gated"` (feature in development, contact contact@nafis.io for supervised access)

Chamade is a **voice and chat gateway**: for voice calls you bring your own STT/TTS stack and connect it to the audio WebSocket returned by `chamade_call_join`. Text conversations (DMs, group chats, in-call chat, inbox) are plug-and-play via MCP tools, no audio plumbing needed.

**`platforms`** — per-platform `{status, capabilities}` for every supported platform. Look at each `status`:
- `"ok"` / `"ok (connected)"` / `"ok (own bot)"` — already set up, do NOT re-connect
- `"available (shared bot, user account not connected)"` — works via shared bot but the user hasn't linked their personal account yet. Ask if they want to connect it.
- `"not_configured: <hint>"` — needs setup. Ask the user if they want to configure it.

And each `capabilities` array tells you what the platform exposes: `audio_in`, `audio_out`, `read`, `write`, `typing`, `files`. An agent that only needs text (chat/DM) can ignore `audio_*` entirely.

Do NOT propose to connect a platform that is already connected.

## Step 4: Connect platforms the user wants

For each platform the user wants to connect:

**Telegram (shared bot):**
1. `POST /api/telegram/connect` → returns `{"deeplink": "https://t.me/...?start=TGLINK_..."}`
2. Give the deeplink to the user — they must open it in Telegram and send `/start`
3. Once done, messages appear in the inbox (`chamade_inbox`)

**Discord:**
1. `POST /api/oauth/start/discord` → returns `{"auth_url": "..."}`
2. Give the auth_url to the user — they open it in a browser to authorize
3. To use voice: the user must also invite the bot to their Discord server (invite link in `GET /api/platforms`)

**Microsoft Teams:**
1. `POST /api/oauth/start/microsoft` → returns `{"auth_url": "..."}`
2. Give the auth_url to the user — they open it in a browser to authorize
3. The user must also install the Chamade Teams app (sideload)

**Google Meet:**
1. `POST /api/oauth/start/google` → returns `{"auth_url": "..."}`
2. Give the auth_url to the user — they open it in a browser to authorize

**Slack:**
1. `POST /api/slack/install` → returns `{"url": "..."}`
2. Give the URL to the user — they authorize the Slack app in their workspace

**Zoom (beta):**
1. The user must first be added as a beta tester on the Zoom Marketplace (contact Chamade team)
2. Install the Chamade app from the Zoom Marketplace
3. `POST /api/oauth/start/zoom` → returns `{"auth_url": "..."}`
4. Give the auth_url to the user — they open it in a browser to authorize

**WhatsApp:** No connection needed — just use it directly. Note: WhatsApp enforces a 24-hour customer service window. Outside that window, your `chamade_dm_chat` calls return HTTP 202 `{status: "queued"}` instead of 200 `{status: "delivered"}` — Chamade automatically fires a re-engagement template and flushes your queued messages when the user replies. You'll get a `dm_delivered` event on the inbox WebSocket (or the MCP channel stream) the moment the flush happens. No retry needed on your side.

**Custom bot (Discord/Telegram/Slack):**
`POST /api/bot-tokens` with `{"platform": "...", "bot_token": "...", ...}`

## Step 5: Done

The setup is complete. The user can now use Chamade tools:
- `chamade_call_join`, `chamade_call_chat`, `chamade_call_status`, `chamade_call_leave` — voice calls (see below for voice pipeline setup)
- `chamade_inbox`, `chamade_dm_chat`, `chamade_dm_typing` — DMs and text conversations (work out of the box)
- `chamade_call_accept` / `chamade_call_refuse` — inbound call handling

> **For voice calls, hosted STT/TTS (`chamade_call_say`, pushed `call_transcript` events) is currently beta-gated.** For production voice, connect your own STT/TTS stack (OpenAI Realtime, LiveKit Agents, Pipecat, Deepgram Voice Agent, or a manual Whisper/Deepgram + GPT + ElevenLabs/Cartesia cascade) to the call's audio WebSocket. The `chamade_call_join` response includes an `audio` block with the exact `stream_url`, PCM format, and sample rate — your agent's host code reads that block and connects directly. Contact contact@nafis.io to request supervised access to hosted STT/TTS.

For the full API reference and audio WebSocket protocol: https://chamade.io/llms-full.txt