> ## Documentation Index
> Fetch the complete documentation index at: https://help.harmonica.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect AI agents to Harmonica via Model Context Protocol

The [Harmonica MCP server](https://github.com/harmonicabot/harmonica-mcp) lets AI agents create and interact with deliberation sessions. Available on [npm](https://www.npmjs.com/package/harmonica-mcp).

## Setup

### 1. Get an API key

1. [Sign up for Harmonica](https://app.harmonica.chat) if you haven't already (free)
2. Go to your [Profile](https://app.harmonica.chat/profile) > **API Keys** > **Generate API Key**
3. Copy your `hm_live_...` key — it's only shown once

### 2. Configure your AI tool

Add the server to your AI tool's MCP config:

<CodeGroup>
  ```json Claude Code (~/.claude.json) theme={null}
  {
    "mcpServers": {
      "harmonica": {
        "command": "npx",
        "args": ["-y", "harmonica-mcp"],
        "env": {
          "HARMONICA_API_KEY": "hm_live_your_key_here"
        }
      }
    }
  }
  ```

  ```json Cursor (.cursor/mcp.json) theme={null}
  {
    "mcpServers": {
      "harmonica": {
        "command": "npx",
        "args": ["-y", "harmonica-mcp"],
        "env": {
          "HARMONICA_API_KEY": "hm_live_your_key_here"
        }
      }
    }
  }
  ```

  ```json Windsurf (~/.codeium/windsurf/mcp_config.json) theme={null}
  {
    "mcpServers": {
      "harmonica": {
        "command": "npx",
        "args": ["-y", "harmonica-mcp"],
        "env": {
          "HARMONICA_API_KEY": "hm_live_your_key_here"
        }
      }
    }
  }
  ```
</CodeGroup>

## Available tools

| Tool                   | Description                                                      |
| ---------------------- | ---------------------------------------------------------------- |
| `create_session`       | Create a new deliberation session and get a shareable join URL   |
| `update_session`       | Update session metadata (topic, goal, context, critical, prompt) |
| `list_sessions`        | List your sessions (filter by status, search by keywords)        |
| `get_session`          | Get full details of a session (includes facilitation prompt)     |
| `get_questions`        | Get pre-session questions (data collection form)                 |
| `get_responses`        | Get participant responses                                        |
| `get_summary`          | Get the AI-generated summary                                     |
| `search_sessions`      | Search sessions by topic or goal                                 |
| `list_telegram_groups` | List Telegram groups registered to your account                  |

## Example prompts

Once connected, try these prompts with your AI agent:

* *"Create a Harmonica session about team retrospective with the goal of reviewing Q1"*
* *"List my active Harmonica sessions"*
* *"Show me the summary for session \[id]"*
* *"What did participants say in the remote work session?"*
* *"Search my sessions about governance"*
* *"Show me the facilitation prompt for session \[id]"*
* *"Update the prompt for session \[id] to be more concise and avoid excessive praise"*

## Claude Code slash command

If you use Claude Code, you can also install the [harmonica-chat](https://github.com/harmonicabot/harmonica-chat) slash command for designing, creating, and managing sessions:

```bash theme={null}
curl -fsSL https://raw.githubusercontent.com/harmonicabot/harmonica-chat/main/install.sh | bash
```

Then run `/harmonica-chat` for guided session design, or `/harmonica-chat "Topic"` for quick creation.

## Environment variables

| Variable            | Required | Default                      |
| ------------------- | -------- | ---------------------------- |
| `HARMONICA_API_KEY` | Yes      | —                            |
| `HARMONICA_API_URL` | No       | `https://app.harmonica.chat` |