harmonica-mcp
OfficialHarmonica MCP is a compatibility adapter exposing Harmonica REST API actions for structured deliberation, from session setup through input collection, summaries, projects, templates, distribution, and public publishing.
Create, update, list, search, and inspect deliberation sessions, including pre-session questions.
List participants and fetch filtered full response threads; get or regenerate AI-generated summaries.
Send participant chat messages and submit pre-session answers to start facilitated conversations.
Discover session templates and install OFL method specs as runnable chain templates.
Manage projects/workspaces (create, list, get, update, soft-delete) and link sessions to them.
List Telegram groups and configure session distribution, widgets, cross-pollination, and results visibility.
Publish a project as a public sensemaking topic with slug, intro, FAQ, theme, and optional lenses.
List Telegram groups registered to the user's Harmonica account.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@harmonica-mcp Create a session about Q2 goals with the goal to align priorities."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Harmonica MCP compatibility adapter
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 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.
Quick Start
1. Get an API key
Sign up for Harmonica (free)
Go to Profile > API Keys > Generate API Key
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:
{
"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. 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:
{
"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.
Related MCP server: conclave
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 for that surface.
Tool | Description |
| Create a new deliberation session and get a shareable join URL (optional: |
| Update session metadata (topic, goal, context, critical, prompt; |
| End a session without deleting its participant threads, messages, summaries, or other data |
| Reopen a completed session so participants can join again |
| Paginate session metadata with optional status/search filters; |
| Get full session details (includes facilitation prompt) |
| Get pre-session questions (data collection form) |
| Get participant responses |
| Get AI-generated summary |
| Search by topic or goal |
| List Telegram groups registered to the user's account (no parameters) |
| Install an OFL method spec (method.md) as a runnable chain template |
| Create a project (workspace) to group related sessions |
| List the projects (workspaces) you have access to |
| Get a project by id, with the ids of its linked sessions |
| List owned calendar meetings with compact transcript currentness and processing metadata |
| Get one bounded transcript page in |
| Get effective processing restrictions, pending candidates, and history for an owned meeting |
| Set restrictions or review a pending transcript-derived candidate for an owned meeting |
| Rename a project or update its description (editor access) |
| Soft-delete a project; its sessions are left intact (owner access) |
| Create a draft topic in an Unconference project and mirror it to the connected brain repository (editor access) |
| Publish a project as a public sensemaking topic ( |
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
git clone https://github.com/harmonicabot/harmonica-mcp.git
cd harmonica-mcp
npm install && npm run buildThen use node /path/to/harmonica-mcp/dist/index.js instead of npx -y harmonica-mcp in your config.
Environment Variables
Variable | Required | Default | Description |
| Yes | — | Your Harmonica API key |
| No |
| 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 — Conversational Harmonica companion for Claude Code — design, create, and manage sessions (
/harmonica-chat)Harmonica docs — Full platform documentation and API reference
License
MIT
Available Tools
21 toolschat_messageA
Send a message in a Harmonica session conversation and get the AI facilitator response. Creates a new participant thread if first message.
Inputs: content (required), session_id (required), participant_id (required), participant_name (required).
create_projectA
Create a Harmonica project (workspace) you own. Use the returned project ID to publish it as a public sensemaking topic via publish_sensemaking_topic, or to scope sessions/templates to the project. Reuse an existing project by passing its ID to those tools instead of creating a new one.
Inputs: title (required), description.
create_sessionB
Create a new Harmonica deliberation session and get a shareable join URL
Inputs: goal (required), topic (required), prompt, context, +8 more.
delete_projectA
Soft-delete a Harmonica project (workspace): it is archived (status=deleted) and the sessions inside it are left intact, just ungrouped. Requires owner access. This never deletes any sessions.
Inputs: project_id (required).
generate_summaryA
Generate or regenerate the AI summary for a Harmonica session. Uses the session's custom summary_prompt if set, otherwise the default. Requires editor role.
Inputs: session_id (required).
get_projectA
Get a single Harmonica project (workspace) by id, including the ids of the sessions linked to it.
Inputs: project_id (required).
get_questionsA
Get pre-session questions (data collection form) for a Harmonica session
Inputs: session_id (required).
get_responsesA
Get participant responses for a Harmonica session. Returns full conversation threads. Use filters to avoid fetching all data at once for large sessions.
Inputs: session_id (required), name, sort, limit, +2 more.
get_sessionB
Get details of a specific Harmonica session
Inputs: session_id (required).
get_summaryA
Get the AI-generated summary for a Harmonica session
Inputs: session_id (required).
install_method_specA
Install an OFL method spec (the contents of a method.md file) as a runnable Harmonica chain template. Pass the full method.md text as method_md. Use dry_run to preview the generated chain_config without writing anything. Chain templates need a paid (Pro/LTD) account; Free is capped at 3 steps.
Inputs: method_md (required), force, dry_run, registry, +3 more.
list_participantsA
List participants in a Harmonica session with metadata (name, message count, timestamps) but WITHOUT full conversations. Use this first to find participants, then get_responses with filters for specific ones.
Inputs: session_id (required), name, sort, since, +1 more.
list_projectsA
List the Harmonica projects (workspaces) you have access to. A project groups related sessions and can be published as a public sensemaking topic. Returns title + id for each.
Inputs: limit, offset.
list_sessionsB
List Harmonica deliberation sessions you have access to
Inputs: limit, query, status.
list_telegram_groupsA
List Telegram groups registered to your Harmonica account for session distribution
Inputs: no named parameters.
list_templatesA
List Harmonica session templates available to your account (public global templates + templates you own / can access). Use to discover what facilitation patterns are configured in the platform — pass the returned id to create_session as template_id to launch a session with that template's stored facilitation_prompt. Returns id, title, description, and template_type (single | chain) for each.
Inputs: no named parameters.
publish_sensemaking_topicA
Author and publish a Harmonica project as a public sensemaking topic — the /explore hub entry + the /t/[slug] opinion-landscape page built from the project's sessions. Pass enabled: true with a slug (here or already saved) to publish. Requires editor access to the project. Listing on /explore is a separate admin-curated step.
Inputs: project_id (required), faq, slug, intro, +6 more.
search_sessionsA
Search Harmonica sessions by topic or goal keywords
Inputs: query (required), status.
submit_questionsA
Submit pre-session question answers and start a facilitated conversation. Returns the opening facilitator message.
Inputs: answers (required), session_id (required), participant_id (required), participant_name (required).
update_projectA
Rename a Harmonica project (workspace) or update its description. Requires editor access. Pass at least one of title / description.
Inputs: project_id (required), title, description.
update_sessionA
Update session metadata. Mirrors the v1 PATCH /api/v1/sessions/[id] ALLOWED_UPDATE_FIELDS surface. Requires editor role.
Inputs: session_id (required), goal, topic, prompt, +16 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
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.
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.
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.
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
Related MCP Connectors
MCP server for building and testing AI agents with multi-model experimentation and insights.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
MCP server for generating rough-draft project plans from natural-language prompts.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceAn MCP server that enables multi-model debate and consensus building through a single tool. It orchestrates multiple AI models from various providers to debate topics and reach validated conclusions with real-time progress tracking.41 npm3MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables an AI orchestrator to convene a council of other AIs via their CLIs, deliberate, and synthesize consensus.GPL 3.0
- AlicenseNot gradedqualityCmaintenanceMCP server that enables AI agents to run a deterministic orchestration loop with decomposition, subagent execution, and review feedback across multiple LLM backends.61MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for AI agents to conduct multi-LLM roundtable discussions, returning structured common, divergent, and unique perspectives.MIT