mcp-server

# @chamade/mcp-server

[![npm version](https://img.shields.io/npm/v/@chamade/mcp-server.svg)](https://www.npmjs.com/package/@chamade/mcp-server)
[![npm downloads](https://img.shields.io/npm/dm/@chamade/mcp-server.svg)](https://www.npmjs.com/package/@chamade/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

MCP (Model Context Protocol) server for [Chamade](https://chamade.io) — a voice and chat gateway that lets your AI agent join meetings and DMs on Discord, Microsoft Teams, Google Meet, Telegram, SIP, Zoom, Nextcloud Talk, Slack, and WhatsApp.

**The recommended voice path is hosted STT/TTS with bring-your-own-key.** Drop your own ElevenLabs / Deepgram / OpenAI / Cartesia API key in [your dashboard](https://chamade.io/dashboard/voice) once — Chamade runs the full speech pipeline on its side using that key. Transcripts flow in as `call_transcript` events, `chamade_call_say` speaks into the meeting. Free on Chamade's side; you only pay your provider. Your agent stays fully text-driven.

Already have a voice pipeline you want to keep (OpenAI Realtime, LiveKit Agents, Pipecat, Deepgram Voice Agent, a manual cascade)? Chamade also exposes the call's raw-PCM audio as a bidirectional WebSocket — BYO audio, Chamade transports, you run the speech layer. Either mode, same MCP tools for control.

File attachments work out of the box on DMs and meeting chat for Discord, Telegram, Slack, WhatsApp (incl. voice notes), and Nextcloud Talk. Use `chamade_file_upload_url` to mint a pre-signed no-auth upload URL, then pass the returned `file_id` in `attachments` on `chamade_dm_chat` or `chamade_call_chat`. Inbound files arrive on `chamade_inbox` as Chamade-signed URLs — your agent can `curl` them with no extra auth. Teams + Meet support is code-ready but gated until the respective platform certifications complete.

Chamade is currently in early access: free, no subscription, no quota.

## v4: hosted MCP + thin stdio shim

**The Chamade MCP server is now hosted at `https://mcp.chamade.io/mcp/` and speaks the Streamable HTTP transport.** That's the single source of truth — every tool, every resource, every push event lives there.

- If your MCP client supports **Streamable HTTP** (Claude Desktop recent, Claude Code, Cursor, Windsurf, …), configure it directly against the hosted endpoint. You don't need this npm package.
- If your MCP client is **stdio-only**, install this package. Since v3 it's a ~160-line wrapper that spawns `mcp-remote` under the hood to bridge stdio to the hosted HTTP endpoint. Same tools, same push events, same latency. Zero drift because there is no parallel stdio implementation.

### What changed in v4

v4 is a server-side wire-shape change picked up automatically by the shim. Headline items, full detail in [docs/AGENTS.md](https://chamade.io/docs/agents):

- **Channels are now Agents.** Per-bearer scoping is unchanged; the noun is `agent` everywhere on the wire and in tool descriptions.
- **`account_id` is the canonical join key.** Used identically in `chamade_dm_chat`, `chamade_call_join`, event payloads, and reply XML tag attributes.
- **Event payload v2.** `data` carries `account_id` + `from` + `from_name` (sender_* fields removed) and a pre-stuffed `agent_context.{accounts, active_calls}` snapshot so the agent always knows what it's on without an extra round-trip.
- **Explicit-target XML tags.** Reply XML can now address conversations / calls outside the current reply context (`<dm platform=…>`, `<call_say call_id=…>`, …) for cross-target initiation.
- **Auto-MCP attachment.** Providers with native MCP-as-tool support (OpenAI Responses, Anthropic Managed Agents, Foundry) receive the Chamade MCP server pre-injected with a per-agent bearer.

Earlier versions of this package (v2.x and below) shipped a full native stdio server that implemented the 13 tools locally in TypeScript against Chamade's REST API. v3+ replaces that with a shim — please upgrade to avoid maintaining two surfaces that slowly diverge.

## Quick start

### Option A — HTTP direct (preferred)

If your client speaks Streamable HTTP, skip this package entirely:

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

### Option B — stdio shim (this package)

For stdio-only clients:

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

**`CHAMADE_API_KEY` is required.** Get a real one at https://chamade.io/dashboard → API keys and paste the full `chmd_…` value (≥ 40 chars after the prefix). If the env var is missing, empty, or still contains a placeholder like `chmd_...`, the shim refuses to start instead of silently falling back to OAuth — that fallback path loops on refresh-and-revoke and is not a viable auth method for this server.

## Configuration

### Claude Desktop

`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows). Use Option A or B above.

### Claude Code

`.mcp.json` at the root of your project. Use Option A (HTTP direct) for the best experience.

For real-time push events (transcripts, incoming DMs, ringing calls, WhatsApp `dm_delivered` flush), launch Claude Code with the channel flag every time:

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

The flag is a per-launch client-side opt-in mandated by Claude Code for MCP channels not yet on the Anthropic allowlist — it's not dangerous, it's just the standard opt-in for experimental channels during the research preview. The server name after `server:` must match the key in your `.mcp.json`. Without the flag, tools still work but push events are silently ignored — you have to poll `chamade_inbox` and `chamade_call_status` to see new activity.

### Cursor / Windsurf / OpenClaw

Same format. Path varies by client: `.cursor/mcp.json`, `~/.codeium/windsurf/mcp_config.json`, `~/.openclaw/config.json`. Use Option A if the client supports HTTP, otherwise Option B.

## Tools

| Tool | Description |
|------|-------------|
| `chamade_call_join` | Join a voice meeting (platform + meeting_url). |
| `chamade_call_say` | Speak text aloud via TTS in the meeting. |
| `chamade_call_chat` | Send a text chat message in the meeting. Optional `attachments: [{file_id} \| {url} \| {bytes_b64, name, mime}]` to send files along with the text; `text` becomes the caption when both are set. 25 MB cap per attachment. |
| `chamade_call_status` | Get call state and new transcript lines (delta pattern). |
| `chamade_call_accept` | Answer a ringing inbound call (SIP, etc.). |
| `chamade_call_refuse` | Refuse/reject a ringing inbound call. |
| `chamade_call_typing` | Send a typing indicator in meeting chat. |
| `chamade_call_leave` | Hang up and leave the meeting. |
| `chamade_call_list` | List all active calls. |
| `chamade_inbox` | Check DM conversations (Discord, Telegram, Teams, WhatsApp, Slack, NC Talk). Shows WhatsApp 24h window state inline. Inbound file attachments arrive as `attachments[]` on each message, with Chamade-signed URLs. |
| `chamade_dm_chat` | Send a DM message by platform. Optional `attachments: [{file_id} \| {url} \| {bytes_b64, name, mime}]` to send files; `text` becomes the caption. On WhatsApp outside the 24h window, returns 202 queued and auto-fires a re-engagement template. |
| `chamade_dm_typing` | Send a typing indicator in DM by platform. |
| `chamade_file_upload_url` | Mint a short-lived (5 min) pre-signed upload URL. Your shell / agent `curl -F file=@path <url>` with **no auth header** (URL itself is the auth), then pass the returned `file_id` in `attachments: [{file_id}]` on a subsequent send. Recommended path for any non-trivial local file — a shell-streamed upload keeps the tool call tiny instead of forcing every base64 character through the model's output budget. |
| `chamade_account` | Check account status, plan, credit/quota, and per-platform readiness (incl. a `files` bool per platform). |

## Resources

| URI template | Description |
|--------------|-------------|
| `chamade://calls/{call_id}/transcript` | Live transcript. Each read returns only new lines since the last read (delta pattern). Channel-mode clients also receive push notifications for every new line. |

## Channel mode (push events)

Channel mode pushes DM messages, incoming SIP calls, transcript lines, call state changes, and WhatsApp `dm_delivered` flush events directly into the agent's context — no polling.

**Server side — nothing to configure.** The hosted Chamade MCP server always declares the `experimental.claude/channel` capability during the initialize handshake. The v2.x `--channel` arg / `CHAMADE_CHANNEL=1` env var are gone.

**Client side — Claude Code needs a per-launch flag.** Claude Code only processes `notifications/claude/channel` from MCP servers you've explicitly opted in:

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

Required every launch. Without it, Chamade tools still work but push events are silently dropped client-side — the agent has to poll `chamade_inbox` and `chamade_call_status` to see new activity.

Other MCP clients (Claude Desktop, Cursor, Windsurf) currently do not have a channel receiver and will silently ignore push notifications. They still work in polling mode via `chamade_inbox` with `last_message_cursor` + optional `wait` for long-polling.

## Environment variables (shim only)

Only the stdio shim uses these. Direct HTTP config has everything in JSON.

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `CHAMADE_API_KEY` | **Yes** | — | API key (`chmd_*`, ≥ 40 chars of entropy) from chamade.io/dashboard. The shim validates