Skip to main content
Glama

Harmonica MCP compatibility adapter

npm version

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

  1. Sign up for Harmonica (free)

  2. Go to 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:

{
  "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_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

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 — 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 tools
chat_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

    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

    Related MCP Connectors

    Related MCP Servers