MCP Server

The Harmonica MCP server lets AI agents create and interact with deliberation sessions. Available on npm. There are two ways to connect. The hosted endpoint needs nothing installed and is the simplest option for a client that supports remote MCP servers. The npm package runs locally over stdio and is what OSS and self-hosted instances use.

Hosted endpoint

Point any client that supports remote MCP servers at:

https://app.harmonica.chat/api/mcp/mcp

The transport is streamable HTTP. Every request must be authenticated. Send the same hm_live_... API key from Get an API key as a bearer token:

Authorization: Bearer hm_live_your_key_here

claude mcp add --transport http harmonica \
  https://app.harmonica.chat/api/mcp/mcp \
  --header "Authorization: Bearer hm_live_your_key_here"

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

Signing in with your Harmonica account instead of pasting a key is not available yet, so an API key is currently the only credential the hosted endpoint accepts. The hosted endpoint exposes the same tools as the npm package, listed below.

Setup

1. Get an API key

Sign up for Harmonica if you haven’t already (free)
Go to your Profile > API Keys > Generate API Key
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:

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

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

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

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)
`close_session`	Close a session without deleting participant threads, messages, summaries, or other data
`reopen_session`	Reopen a completed session so participants can join or continue again
`list_sessions`	Paginate sessions by status. Keys explicitly authorized by a current global admin can request platform-wide metadata; per-session content and mutations remain account-scoped.
`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
`list_meetings`	List owned calendar meetings with compact transcript currentness and processing metadata
`get_transcript`	Get one bounded transcript page with `turns` or `text` format and an optional continuation cursor
`get_meeting_restrictions`	Get effective processing restrictions and append-only history for an owned meeting
`update_meeting_restrictions`	Set owned-meeting restrictions or review a pending restriction candidate
`create_project`	Create a project (workspace) you own
`publish_sensemaking_topic`	Publish a project as a public sensemaking topic (the `/explore` hub + `/t/[slug]` page)

Meeting transcript paging

get_transcript returns one page only. It defaults to at most 100 segments and 25,000 transcript characters, with hard maxima of 200 segments and 50,000 characters. Pass pagination.next_cursor back as cursor to continue; the tool never accumulates the rest of a transcript automatically. If the transcript changes between pages, restart without a cursor. Use format: "turns" for structured speaker segments or format: "text" for a plain-text rendering. Speaker labels come from the recording provider and are not verified identities across meetings. include_speaker_email is owner-only and applies only to turns format. Complete transcript download remains an owner-only REST export and is intentionally not an MCP tool.

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 slash command for designing, creating, and managing sessions:

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`

Overview

Endpoints

Integrations

Hosted endpoint

Setup

1. Get an API key

2. Configure your AI tool

Available tools

Meeting transcript paging

Example prompts

Claude Code slash command

Environment variables

​Hosted endpoint

​Setup

​1. Get an API key

​2. Configure your AI tool

​Available tools

​Meeting transcript paging

​Example prompts

​Claude Code slash command

​Environment variables

Hosted endpoint

Setup

1. Get an API key

2. Configure your AI tool

Available tools

Meeting transcript paging

Example prompts

Claude Code slash command

Environment variables