@gethmy/mcp

@gethmy/mcp

MCP (Model Context Protocol) server for Harmony, the shared surface for human–agent teams. Claude Code, OpenAI Codex, Cursor, and any MCP client claim cards, report progress, and move work on your board.

Features

• 81 MCP Tools for full board control, memory, and workflow plans
• Global Skills — installable in one command, served from the DB-backed skill hub with auto-update and admin-managed versioning
• Markdown Memory Vault — one markdown document per memory, shared with the workspace, Postgres full-text retrieval, activity feed. See docs/memory.md
• GSD Workflow Plans - plan/execute/verify/done lifecycle with auto card creation
• Card Linking - create relationships between cards (blocks, relates_to, duplicates, is_part_of)
• Prompt Builder - generate AI-ready prompts from cards with context
• Agent Session Tracking - track work progress with timer badges
• Auto-Session Detection - automatically starts/ends sessions when agents interact with cards
• Auto-Assignment - automatically assign cards to you when starting agent sessions
• Memory Sync - bidirectional sync between local markdown files and remote database
• Multi-Agent Support - works with Claude Code, Codex, Cursor, Claude.ai
• One-Command Setup - one command configures everything
• Browser Sign-In - secure OAuth setup (loopback + PKCE), no key to copy or paste; API keys still supported for CI

Prerequisites

• Node.js >= 20 or Bun >= 1.0
• A Harmony account with an API key

Quick Start

Connect

npm i -g @gethmy/cli
hmy connect

@gethmy/cli is the front door: one install carries this package, the agent daemon and the playbook motor, and one hmy update moves all three.

No-install fallback. On a machine you may not install to — a container, a CI step, a one-off — call this package directly:

npx @gethmy/mcp connect

Both forms stay supported and do the same work. What the install buys is the update path: @latest does not re-resolve, so the npx cache keeps serving the build it first installed.

connect will:

• Sign you in through your browser (OAuth — no API key to copy or paste). You can also create a free account or paste an existing key from the same prompt.
• Detect installed AI agents (Claude Code, Cursor, Codex)
• Install skills globally (recommended) or locally
• Let you select your workspace and project

That's it! You're ready to use Harmony with your AI agent.

Prefer an API key? Generate one at gethmy.com/user/keys (starts with hmy_) and choose "Paste an API key" in the connect prompt, or pass --api-key for unattended CI. Browser sign-in is the recommended path when a person is present.

Remote MCP (Hosted)

Connect any MCP-compatible agent to Harmony's hosted endpoint - no local server required.

Endpoint: https://mcp.gethmy.com/mcp

Transport: Streamable HTTP (MCP SDK standard)

Authentication: browser sign-in (OAuth) on first use; a Bearer hmy_ API key as the fallback

Client Config

Add the endpoint to your client's MCP config — .mcp.json in Claude Code, .cursor/mcp.json in Cursor. The client signs you in through the browser on first use:

{
  "mcpServers": {
    "harmony": {
      "type": "http",
      "url": "https://mcp.gethmy.com/mcp"
    }
  }
}

A client without browser sign-in takes the API key as a header instead: "headers": { "Authorization": "Bearer hmy_your_key_here" }.

Manual Setup (Claude.ai)

If you prefer to configure manually (e.g., in Claude.ai's UI):

• Get an API key from Harmony
• In Claude.ai, add a remote MCP server with URL https://mcp.gethmy.com/mcp
• Set the Authorization header to Bearer hmy_your_key_here
• All 81 Harmony tools become available in your conversation

Session management is automatic - sessions have a 1-hour TTL and are created/renewed transparently.

When to use remote vs local: The remote endpoint (client config or Claude.ai) works with any MCP-compatible agent and requires no local server. Use the local server (hmy connect) when you need skills, local project context, or memory sync to local markdown files.

Adding to a New Project

Just run connect again in the new project directory:

cd my-new-project
hmy connect

It detects your existing configuration and only asks for the project context.

CLI Commands

# Connect (recommended) — authorizes in your browser, no API key handling
hmy connect                    # Connect this repository and your client

# Connect with flags (non-interactive)
hmy connect --global --workspace ID --project ID
# --api-key is supported for unattended CI only (deprecated — see below)

# Status and management
hmy mcp status                 # Show current configuration
hmy mcp reset                  # Clear all configuration

# Server (called by agents automatically)
hmy mcp serve                  # Start MCP server

# Run timeline hook (opt-in) — see below
hmy mcp hook install           # Stream this session's tool calls to the card
hmy mcp hook status            # Is it installed? Which sessions are live?
hmy mcp hook uninstall         # Remove it

The same commands with nothing installed — both spellings stay supported:

npx @gethmy/mcp connect            # Connect this repository and your client
npx @gethmy/mcp status             # Show current configuration
npx @gethmy/mcp reset              # Clear all configuration
npx @gethmy/mcp serve              # Start MCP server
npx @gethmy/mcp hook install       # Stream this session's tool calls to the card

hmy setup still reaches connect as a deprecated alias, so a pasted command or a CI job keeps working.

Run Timeline Hook

By default a card's run timeline shows only what the MCP tools report: the session starting, each progress checkpoint, the session ending. Your editor's own Read, Edit, Bash and Grep calls never reach the MCP server, so they cannot appear there.

hook install closes that gap. It adds one PostToolUse entry to ~/.claude/settings.json, and from then on the tool calls of a session that holds a card stream to that card's timeline with their input and output, live — the same view a Harmony agent daemon run gets, without you reporting anything.

hmy mcp hook install

Four things worth knowing:

• It writes only the user layer. ~/.claude/settings.json, never a project's .claude/settings.json. A project-layer hooks key would break contained agent runs in that repo, and the user layer is also what keeps a daemon run from reporting its stream twice.
• Re-run it after upgrading. The entry pins the exact install that wrote it, and an upgrade or a cleared npx/bunx cache moves that path. The command guards its own paths, so nothing breaks in the meantime — the hook just goes quiet, and hook status says so.
• Tool inputs and outputs are redacted before they leave your machine. Credential paths, tokens, and the usual secret-shaped values are withheld; large payloads are truncated. The rule is on the MCP docs page.
• It is off unless you install it, and HARMONY_DISABLE_RUN_HOOK=1 turns the stream off without uninstalling — for when a team decides tool inputs do not belong on a shared board.

Setup Options

Flag	Description
-k, --api-key <key>	Deprecated — insecure (leaks via argv/shell history). Unattended CI only; interactive setup uses browser sign-in.
-e, --email <email>	Your email for auto-assignment
-a, --agents <agents...>	Agents to configure: claude, codex, cursor, windsurf
-g, --global	Install skills globally (recommended)
-l, --local	Install skills locally in project directory
-w, --workspace <id>	Set workspace context
-p, --project <id>	Set project context
--skip-context	Skip workspace/project selection
-f, --force	Overwrite existing configuration

Supported AI Agents

Agent	Workflow Command	Config Location	Transport
Claude Code	/hmy #42, /hmy-plan	~/.claude/settings.json	Local (stdio)
OpenAI Codex	/prompts:hmy #42	~/.codex/config.toml	Local (stdio)
Cursor	MCP tools auto-available	.cursor/mcp.json	Local (stdio)
Claude.ai	MCP tools auto-available	Remote MCP settings in Claude.ai	Remote (HTTP)
Any agent	MCP tools auto-available	Its own MCP config (see above)	Remote (HTTP)

Skills

Global skills ship with the MCP server and are installed automatically by hmy connect (npx @gethmy/mcp connect). They live in the skill_resource Postgres table, are fetched via GET /v1/skills/<name>, and render-time composed.

For the full skill list and the hub architecture (storage, versioning, auto-update, admin management), see docs/skills.md.

/hmy — Card Workflow

When you start working on a card (e.g., /hmy #42):

• Find - Locates the card by short ID, UUID, or name
• Move - Moves the card to "In Progress" column
• Label - Adds the "agent" label to indicate AI is working
• Assign - Auto-assigns the card to you (if email is configured)
• Track - Starts a session timer visible in the UI
• Implement - Work on the task with progress updates
• Complete - Move to "Review" when done

/hmy-plan — Plan Workflow

A single command for both creating and executing plans. It auto-detects intent based on the argument:

Argument	Action
UUID	Fetch and work on existing plan
#42	Look up card, then its linked plan
mobile auth	Search existing plans; if found, work on it; if not, offer to create one
(empty)	Start the new plan creation interview

Creating a plan (/hmy-plan mobile auth):

• Gathers board context and related memories
• Interviews you with 3-5 focused questions
• Synthesizes a structured plan document
• Saves to Harmony via harmony_create_plan
• Optionally advances to execute phase, creating board cards from tasks

Executing a plan (/hmy-plan <existing plan>):

• Displays plan summary (status, phase, task counts)
• Recalls related context from memory
• Offers options: create single card, create multiple cards, analyze only, or skip
• Creates cards and advances the plan phase

/hmy-cleanup — Board Audit

Scans the board for stale cards — long-idle, missing owners, or stuck in review — and proposes cleanup actions. Read-only by default; opt-in to apply suggestions.

/hmy-standup — Daily Summary

Generates a structured standup summary: what shipped, what's in progress, what's blocked, and where agents need input. Pulls from card activity, plan progress, and the memory activity feed.

Auto-Update

The server owns auto-update. refreshSkills() runs at serve startup, calls GET /v1/skills/version at most once per 24h, and atomically rewrites only the installed skill files that are behind. Two knobs live in ~/.hmy/config.yaml: update_check (master switch) and pin (freeze on the installed version).

Available Tools

Card Operations

• harmony_create_card - Create a new card
• harmony_update_card - Update card properties
• harmony_move_card - Move card to different column (auto-ends agent session on move to done/review)
• harmony_archive_card - Archive a card (soft-delete, can be restored)
• harmony_unarchive_card - Restore an archived card back to the board
• harmony_delete_card - Delete a card
• harmony_assign_card - Assign to team member
• harmony_search_cards - Search by title/description
• harmony_get_card - Fetch one or many cards: { cardId } (UUID, full) · { shortId } (e.g. 42, full) · { shortIds } (array, compact summaries). Provide exactly one selector.

Deprecated (still accepted via the compat shim, removed in a future major): harmony_get_card_by_short_id → harmony_get_card { shortId }, harmony_bulk_get_cards → harmony_get_card { shortIds }. See CHANGELOG.md (2.14.0).

Card Link Operations

• harmony_add_link_to_card - Create a link between two cards
• harmony_remove_link_from_card - Remove a link between cards
• harmony_get_card_links - Get all links for a card

Link Types:

Type	Description
relates_to	Generic relationship between cards
blocks	Source card blocks target card
duplicates	Source card duplicates target card
is_part_of	Source card is part of target card

Column Operations

• harmony_create_column - Create new column
• harmony_update_column - Update column properties
• harmony_delete_column - Delete column

Label Operations

• harmony_create_label - Create new label
• harmony_add_label_to_card - Add label to card
• harmony_remove_label_from_card - Remove label

Subtask Operations

• harmony_create_subtask - Create subtask
• harmony_toggle_subtask - Toggle completion
• harmony_delete_subtask - Delete subtask

Context Operations

• harmony_list_workspaces - List workspaces
• harmony_list_projects - List projects
• harmony_get_board - Get board state (supports pagination via limit/offset, summary mode, columnId filter, includeArchived)
• harmony_get_workspace_members - Get team members
• harmony_list_agents - List a workspace's virtual agents (daemons); use the id with harmony_assign_card (agentId)
• harmony_set_workspace_context - Set active workspace
• harmony_set_project_context - Set active project
• harmony_get_context - Get current context

Natural Language

• harmony_process_command - Process natural language commands

Agent Session Tracking

• harmony_start_agent_session - Start tracking work on a card (with moveToColumn and addLabels side effects)
• harmony_update_agent_progress - Update progress, status, blockers
• harmony_end_agent_session - End session (completed/paused); triggers active learning extraction
• harmony_get_agent_session - Get current session state

Auto-Session Detection

Sessions are automatically started when agents call card-mutating tools without an explicit harmony_start_agent_session. This ensures work is always tracked, even when agents don't explicitly manage sessions.

Trigger tools: harmony_generate_prompt, harmony_update_card, harmony_move_card, harmony_create_subtask, harmony_toggle_subtask, harmony_add_label_to_card, harmony_remove_label_from_card

Behavior:

• Auto-starts a session when any trigger tool is called on a card without an active session
• Auto-ends after 10 minutes of inactivity
• Switching to a different card auto-ends the previous auto-session
• Explicitly started sessions (via harmony_start_agent_session) are never auto-ended
• Auto-ended sessions trigger the full active learning pipeline

Prompt Generation

• harmony_generate_prompt - Generate an AI-ready prompt from a card with assembled memory context

Parameters:

Parameter	Description
cardId	Card UUID to generate prompt from
shortId	Alternative: Card short ID (e.g., 42 for #42)
variant	analysis (understand/plan), draft (design the approach), execute (implement fully)
includeDescription	Include card description (default: true)
includeSubtasks	Include subtasks in prompt (default: true)
includeLinks	Include linked cards in prompt (default: true)
customConstraints	Additional instructions to append

The prompt builder automatically infers the agent role based on card labels (bug, feature, design, etc.) and injects relevant memories found by searching the vault for the card's own text.

Memory

The vault stores one markdown document per memory: a fact, plus the timeline of every change to it. There are no tiers, confidence scores, importance values, embeddings, relations or read counters.

CRUD:

• harmony_remember - Store a memory, and optionally supersede one it duplicates
• harmony_recall - Retrieve memories by type, tags, scope, or text query, rescored by relevance × recency × type
• harmony_update_memory - Replace a memory's fact, title, tags, type or scope
• harmony_forget - Permanently delete a memory
• harmony_memory_search - Full-text search across the vault, markdown out

Memory Types: agent, task, decision, context, pattern, error, solution, preference, relationship, commitment, lesson, project, handoff, procedure

Scopes: project (needs a project) and workspace. global is stored as workspace; private and session are refused.

Retiring a memory: a memory is never edited into a contradiction. Store the new one, point the old one's superseded_by at it, and reads exclude it unless include_superseded asks for it. The link is recorded on both documents in one transaction — the new memory's supersedes names the old one — so the trail survives the old memory being forgotten.

Memory Vault & Sync

• harmony_vault_index - Compact index of the workspace's memories (markdown table)
• harmony_sync - Bidirectional sync between local markdown files (~/.harmony/memory/) and remote database (directions: pull, push, full)

GSD Workflow Plans

Create and manage project plans with a phased workflow: plan → execute → verify → done.

• harmony_list_plans - List plans in a project (filter by status or workflow phase)
• harmony_create_plan - Create a new plan with embedded tasks
• harmony_get_plan - Get plan by ID or card ID
• harmony_update_plan - Update plan title, content, status, or its timeline dates (startDate/endDate, set together or both null)
• harmony_advance_plan - Advance to next phase with side effects:
  • plan → execute: auto-creates board cards from plan tasks, sets plan active
  • execute → verify: checks card completion status
  • verify → done: archives plan, creates memory entities

Onboarding & Account

• harmony_onboard - Complete end-to-end onboarding: signup → workspace → project → API key
• harmony_signup - Create a new user account
• harmony_create_workspace - Create a new workspace
• harmony_create_project - Create a new project with template columns (kanban, scrum, or simple)
• harmony_send_invitations - Send workspace invitations to team members
• harmony_generate_api_key - Generate an API key for the authenticated user

Direct API Access

You can also call the Harmony API directly from any HTTP client:

curl -X GET "https://gethmy.com/api/v1/workspaces" \
  -H "X-API-Key: hmy_your_key_here"

API Endpoints

Endpoint	Method	Description
/v1/workspaces	GET	List workspaces
/v1/workspaces/:id/projects	GET	List projects in workspace
/v1/workspaces/:id/members	GET	Get workspace members
/v1/board/:projectId	GET	Get full board state
/v1/cards	POST	Create card
/v1/cards/:id	GET	Get card
/v1/cards/:id	PATCH	Update card
/v1/cards/:id	DELETE	Delete card
/v1/cards/:id/move	POST	Move card
/v1/cards/:id/prompt	GET	Generate prompt from card
/v1/cards/:id/links	GET	Get card links
/v1/cards/:id/links	POST	Create card link
/v1/cards/:id/labels	POST	Add label to card
/v1/cards/:id/labels/:labelId	DELETE	Remove label
/v1/search?q=query	GET	Search cards
/v1/columns	POST	Create column
/v1/columns/:id	PATCH	Update column
/v1/columns/:id	DELETE	Delete column
/v1/labels	POST	Create label
/v1/subtasks	POST	Create subtask
/v1/subtasks/:id/toggle	POST	Toggle subtask
/v1/subtasks/:id	DELETE	Delete subtask
/v1/links/:id	DELETE	Delete card link
/v1/nlu	POST	Process natural language

Configuration

Global Configuration

Stored in ~/.hmy/agent/config.json. Browser sign-in writes OAuth tokens (and nulls apiKey); API-key setup writes apiKey instead. The server prefers a live OAuth token and refreshes it automatically:

{
  "apiKey": null,
  "oauthAccessToken": "hmy_at_...",
  "oauthRefreshToken": "...",
  "oauthExpiresAt": 1750000000,
  "oauthClientId": "...",
  "apiUrl": "https://gethmy.com/api",
  "userEmail": "[e-mail]",
  "activeWorkspaceId": null,
  "activeProjectId": null
}

Local Project Configuration

Stored in .hmy.json in your project root:

{
  "workspaceId": "uuid-here",
  "projectId": "uuid-here"
}

Priority: Local config overrides global config for workspace and project context.

Security: API key is never stored locally (only in global config) to prevent accidental commits.

Auto-Assignment

When your email is configured during setup, cards are automatically assigned to you when you start an agent session (e.g., via /hmy #42). This helps track who is working on what.

To update your email:

hmy connect --email [e-mail]   # npx fallback: npx @gethmy/mcp connect --email [e-mail]

The email must match your Harmony account email to work correctly.

Viewing Configuration

hmy mcp status

Example output:

Status: Configured

API:
  Key: hmy_abc1...
  URL: https://gethmy.com/api
  Email: y***@example.com

Skills:
  Installed: Yes (global)
    ~/.agents/skills/hmy/SKILL.md

Context:
  Local config: .hmy.json
    Workspace: my-team-id
    Project: my-project-id
  Global config: ~/.hmy/agent/config.json
    Workspace: (not set)
    Project: (not set)

  Active (effective):
    Workspace: my-team-id ← local
    Project: my-project-id ← local

Recommended .gitignore

Add this to prevent accidentally committing local config:

.hmy.json

Architecture

┌─────────────────┐      MCP Protocol       ┌──────────────────┐
│  Claude Code    │ ───────────────────────▶│  @gethmy/mcp     │
│  Cursor         │      (local stdio)      │  (local server)  │
│  Codex          │                         └────────┬─────────┘                                  │
└─────────────────┘                                  │ API Key Auth
                                                     ▼
┌─────────────────┐    Streamable HTTP      ┌──────────────────┐
│  Claude.ai      │ ───────────────────────▶│  Remote MCP      │
│  Any MCP client │    (Bearer: hmy_xxx)    │  mcp.gethmy.com  │──┐
└─────────────────┘                         └──────────────────┘  │
                                                                   │
                                                     ┌─────────────┘
                                                     ▼
                                          ┌──────────────────┐
                                          │  Harmony API     │
                                          │  (Edge Function) │
                                          └────────┬─────────┘
                                                   │
                                                   ▼
                                          ┌──────────────────┐
                                          │    Database      │
                                          │    (Supabase)    │
                                          └──────────────────┘

Key Benefits:

• No database credentials needed - just a Harmony API key
• Any Harmony user can use it
• Business logic stays in Harmony
• Centralized security and rate limiting

Testing

bun run test:unit          # fast — covers dispatch + skills
bun run test:integration   # spins up real memory pipeline
bun run typecheck          # type-only check

MCP bridge verification harness

Three test files pin the contract every MCP client depends on. They are mandatory — agents lose tools silently if any of these drift:

File	What it pins
src/__tests__/skills.test.ts	buildSkillFile renderer contract: version-marker injection, body trimming, version-parse edge cases. Fed by FetchedSkill fixtures (DB-backed via /v1/skills post-#162 Phase 0).
src/__tests__/tool-dispatch.test.ts	TOOLS registry shape, name uniqueness + harmony_* namespace, inputSchema validity, handler routing via registerHandlers, tool ↔ skill namespace boundary.
src/__tests__/mcp-integration.test.ts	End-to-end Client ↔ Server round-trip over InMemoryTransport — listTools, callTool, listResources, readResource, plus error paths.

Adding a new tool

• Append the entry to TOOLS in src/server.ts (name, description, inputSchema).
• Add a case "harmony_..." branch in handleToolCall.
• Run bun run test:unit — the parameterized assertions in tool-dispatch.test.ts automatically cover the new entry's shape.
• If the tool needs a unique round-trip assertion, extend mcp-integration.test.ts with one extra case.

Adding a new skill

• Define MY_SKILL_CONTENT in src/skills.ts.
• Add it to SKILL_DEFINITIONS with name, description, argumentHint, and content.
• Bump SKILLS_VERSION so installed clients refresh on next startup.
• Run bun run test:unit — the parameterized assertions in skills.test.ts automatically cover the new skill.

CI gates the full test:unit suite on every PR that touches src/server.ts, src/skills.ts, or any file under src/__tests__/.