Skip to main content
Glama
README.md
# Harmonica MCP compatibility adapter

[![npm version](https://img.shields.io/npm/v/harmonica-mcp)](https://www.npmjs.com/package/harmonica-mcp)

The hosted MCP endpoint in Harmonica Pro is the primary MCP implementation:
`https://app.harmonica.chat/api/mcp/mcp`. New integrations should use it directly.

This npm package remains supported for existing stdio clients and OSS/self-hosted
instances that expose the Harmonica REST API. It receives security and
compatibility fixes; new MCP capabilities are developed in Pro and are not
automatically backported. The package is not deprecated or scheduled for removal.

[Harmonica](https://harmonica.chat) is a structured deliberation platform where groups coordinate through AI-facilitated async conversations. Create a session with a topic and goal, share a link with participants, and each person has a private 1:1 conversation with an AI facilitator. Responses are synthesized into actionable insights. [Learn more](https://help.harmonica.chat).

## Quick Start

### 1. Get an API key

1. [Sign up for Harmonica](https://app.harmonica.chat) (free)
2. Go to [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 MCP client

For a new connection, use hosted MCP. This Claude Code example uses an
environment-variable reference, so the key stays out of configuration and CLI
arguments. Load `HARMONICA_API_KEY` into the environment that starts Claude Code
and keep it available after restarts:

```json
{
  "mcpServers": {
    "harmonica": {
      "type": "http",
      "url": "https://app.harmonica.chat/api/mcp/mcp",
      "headers": { "Authorization": "Bearer ${HARMONICA_API_KEY}" }
    }
  }
}
```

Other clients use their own configuration and environment-reference syntax; see
the [MCP connection guide](https://help.harmonica.chat/api-reference/mcp-server).
Existing stdio registrations can stay in place.

#### Standalone stdio (compatibility)

Use the npm package when your client requires stdio or you connect to a
self-hosted Harmonica REST API. Node.js 20 or newer is required. This example is
a private local client configuration; do not commit a real key:

```json
{
  "mcpServers": {
    "harmonica": {
      "command": "npx",
      "args": ["-y", "harmonica-mcp"],
      "env": {
        "HARMONICA_API_KEY": "hm_live_your_key_here"
      }
    }
  }
}
```

Set the server's `HARMONICA_API_URL` environment variable to your instance's base
URL for self-hosting (for example, `http://localhost:3000`, without `/api/v1`).
The default remains `https://app.harmonica.chat` for existing users. This adapter
calls that instance's REST API; it does not make Harmonica available offline.

### 3. Start a deliberation

Ask your AI agent to create a session:

> Create a Harmonica session about "Team Retrospective" with the goal "Review Q1 and identify improvements"

Share the join URL with participants. Once they've responded, use `get_responses` and `get_summary` to see the results.

## Standalone tools

Hosted MCP also exposes application-runtime capabilities, including onboarding
continuation and chain control, that are not available in this adapter. Consult
the [hosted tools guide](https://help.harmonica.chat/api-reference/mcp-server)
for that surface.

| Tool | Description |
|------|-------------|
| `create_session` | Create a new deliberation session and get a shareable join URL (optional: `questions`, `project_id` to file it under a project) |
| `update_session` | Update session metadata (topic, goal, context, critical, prompt; `project_id` to move it into a project or `null` to detach) |
| `close_session` | End a session without deleting its participant threads, messages, summaries, or other data |
| `reopen_session` | Reopen a completed session so participants can join again |
| `list_sessions` | Paginate session metadata with optional status/search filters; `platform` scope requires a separately authorized global-admin audit key |
| `get_session` | Get full session details (includes facilitation prompt) |
| `get_questions` | Get pre-session questions (data collection form) |
| `get_responses` | Get participant responses |
| `get_summary` | Get AI-generated summary |
| `search_sessions` | Search by topic or goal |
| `list_telegram_groups` | List Telegram groups registered to the user's account (no parameters) |
| `install_method_spec` | Install an OFL method spec (method.md) as a runnable chain template |
| `create_project` | Create a project (workspace) to group related sessions |
| `list_projects` | List the projects (workspaces) you have access to |
| `get_project` | Get a project by id, with the ids of its linked sessions |
| `list_meetings` | List owned calendar meetings with compact transcript currentness and processing metadata |
| `get_transcript` | Get one bounded transcript page in `turns` or `text` format, with an optional continuation cursor |
| `get_meeting_restrictions` | Get effective processing restrictions, pending candidates, and history for an owned meeting |
| `update_meeting_restrictions` | Set restrictions or review a pending transcript-derived candidate for an owned meeting |
| `update_project` | Rename a project or update its description (editor access) |
| `delete_project` | Soft-delete a project; its sessions are left intact (owner access) |
| `create_unconference_topic` | Create a draft topic in an Unconference project and mirror it to the connected brain repository (editor access) |
| `publish_sensemaking_topic` | Publish a project as a public sensemaking topic (`/explore` + `/t/[slug]`) |

`get_transcript` returns one page only: 100 segments and 25,000 transcript
characters by default, with hard maxima of 200 segments and 50,000 characters.
Pass `pagination.next_cursor` back as `cursor` to continue. Complete transcript
download is owner-only through REST and is intentionally not an MCP tool.

## From Source

```bash
git clone https://github.com/harmonicabot/harmonica-mcp.git
cd harmonica-mcp
npm install && npm run build
```

Then use `node /path/to/harmonica-mcp/dist/index.js` instead of `npx -y harmonica-mcp` in your config.

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `HARMONICA_API_KEY` | Yes | — | Your Harmonica API key |
| `HARMONICA_API_URL` | No | `https://app.harmonica.chat` | API base URL |

## Maintenance policy

- Fix security issues, regressions, and compatibility problems affecting the
  package's supported transports and existing REST API integrations.
- Develop new MCP product capabilities in Pro. Feature parity with hosted MCP is
  not a release requirement for this package.
- Keep existing stdio and self-hosted setups working. Any future deprecation
  requires identifying affected clients and publishing a migration path first;
  no retirement date is set.

## See Also

- **[harmonica-chat](https://github.com/harmonicabot/harmonica-chat)** — Conversational Harmonica companion for Claude Code — design, create, and manage sessions (`/harmonica-chat`)
- **[Harmonica docs](https://help.harmonica.chat)** — Full platform documentation and API reference

## License

MIT

TDQS

A3.9/5.0

Scored across 21 tools

Disambiguation5/5

Each tool targets a distinct resource and action (e.g., get_summary vs generate_summary are clearly read vs write; get_session vs get_responses vs list_participants have different purposes). The descriptions reinforce the boundaries, making misselection unlikely.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (e.g., list_sessions, create_session, delete_project, publish_sensemaking_topic). There are no mixed conventions or vague verbs, making the API predictable.

Tool Count3/5

With 21 tools, the set is on the heavier side but still scoped to the Harmonica platform's features (sessions, projects, templates, participants, messaging, publishing). It borders the 'heavy' threshold but remains functional.

Completeness4/5

The toolset covers most lifecycle needs: sessions have create/read/search/update, projects have full CRUD, summaries have get/generate, and participation via chat_message. Minor gaps exist (e.g., no session deletion, no explicit participant management), but these are workable.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues