@gethmy/mcp

MCP (Model Context Protocol) server for Harmony. Enables AI coding agents (Claude Code, OpenAI Codex, Cursor) to interact with your Harmony boards.

Features

• 56 MCP Tools for full board control, knowledge graph, and workflow plans
• 5 Global Skills — /hmy, /hmy-plan, /hmy-cleanup, /hmy-standup, /hmy-memory-prune, served from the DB-backed skill hub with auto-update and admin-managed versioning
• Knowledge Graph Memory — Phase 1 surface: hybrid retrieval (vector + lexical + RRF), session-scoped working memory, 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
• Smart Setup - one command configures everything
• API Key Authentication - no database credentials required

Prerequisites

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

Quick Start

1. Get an API Key

1. Log into Harmony
2. Go to API Keys
3. Click "Generate New Key"
4. Copy the key (starts with hmy_)

2. Run Setup

npx @gethmy/mcp setup

The smart setup wizard will:

• Validate your API key
• 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.

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: Bearer token using your hmy_ API key

Universal Setup with add-mcp

The fastest way to connect any agent to the remote endpoint. One command configures Claude Code, Cursor, VS Code, Codex, and more:

npx add-mcp https://mcp.gethmy.com/mcp -- --header "Authorization: Bearer hmy_your_key_here"

Useful flags:

| Flag | Description | | ---- | ----------- | | -g | Install globally (not scoped to a project) | | -a <agent> | Target specific agents (e.g., -a cursor -a claude-code) | | -y | Skip interactive prompts |

Examples:

# Install for all detected agents
npx add-mcp https://mcp.gethmy.com/mcp -- --header "Authorization: Bearer hmy_your_key_here"

# Install globally for Cursor and Claude Code only
npx add-mcp https://mcp.gethmy.com/mcp -g -a cursor -a claude-code -- --header "Authorization: Bearer hmy_your_key_here"

# Non-interactive (CI-friendly)
npx add-mcp https://mcp.gethmy.com/mcp -y -- --header "Authorization: Bearer hmy_your_key_here"

Manual Setup (Claude.ai)

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

1. Get an API key from Harmony
2. In Claude.ai, add a remote MCP server with URL https://mcp.gethmy.com/mcp
3. Set the Authorization header to Bearer hmy_your_key_here
4. All 56 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 (via add-mcp or manual config) works with any MCP-compatible agent and requires no local server. Use the local server (npx @gethmy/mcp setup) when you need skills, local project context, or memory sync to local markdown files.

Adding to a New Project

Just run setup again in the new project directory:

cd my-new-project
npx @gethmy/mcp setup

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

CLI Commands

# Setup (recommended)
npx @gethmy/mcp setup              # Smart setup wizard

# Setup with flags (non-interactive)
npx @gethmy/mcp setup --api-key KEY --global --workspace ID --project ID

# Status and management
npx @gethmy/mcp status             # Show current configuration
npx @gethmy/mcp reset              # Clear all configuration

# Server (called by agents automatically)
npx @gethmy/mcp serve              # Start MCP server

Setup Options

| Flag | Description | | -------------------------- | ---------------------------------------------------- | | -k, --api-key <key> | API key (skips prompt) | | -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 | Auto-configured via npx add-mcp | Remote (HTTP) |

Skills

Five global skills ship with the MCP server and are installed automatically by npx @gethmy/mcp setup. They live in the skill_resource Postgres table, are fetched via GET /v1/skills/<name>, and render-time composed with a shared auto-update preamble.

For the full skill 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):

1. Find - Locates the card by short ID, UUID, or name
2. Move - Moves the card to "In Progress" column
3. Label - Adds the "agent" label to indicate AI is working
4. Assign - Auto-assigns the card to you (if email is configured)
5. Track - Starts a session timer visible in the UI
6. Implement - Work on the task with progress updates
7. 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):

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

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

1. Displays plan summary (status, phase, task counts)
2. Recalls related context from memory
3. Offers options: create single card, create multiple cards, analyze only, or skip
4. 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

Every skill ships with an hmy-update-check preamble that fires on invocation. It compares local versions against /v1/skills/version and prompts (or silently auto-installs, if ~/.hmy/config.yaml has auto_upgrade: true). Snooze levels: 24h / 48h / 7d.

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 - Get card details by UUID
• harmony_get_card_by_short_id - Get card by short ID (e.g., #42)

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_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 solution), 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 memory context using the context assembly engine.

Memory / Knowledge Graph

Store and retrieve persistent knowledge across sessions. Memories have types, tiers, scopes, confidence scores, and can be linked via typed relations.

CRUD:

• harmony_remember - Store a memory entity (markdown with YAML frontmatter)
• harmony_recall - Retrieve memories by type, tags, scope, or text query
• harmony_update_memory - Update an existing memory entity
• harmony_forget - Archive or delete a memory entity
• harmony_memory_search - Full-text search across the knowledge base
• harmony_relate - Create a typed relationship between two memory entities

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

Memory Tiers: draft (working notes) → episode (session summaries) → reference (durable knowledge)

Scopes: private, project, workspace, global

Relation Types: learned_from, resolved_by, contradicts, supports, depends_on, part_of, caused_by, relates_to

Memory Vault & Sync

• harmony_vault_index - Compact index of all memory entities (markdown table)
• harmony_resolve_links - Batch-scan for [[wiki-links]] and auto-create relations
• 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 phase
• harmony_advance_plan - Advance to next phase with side effects:
  • plan → execute: auto-creates Kanban 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 ~/.harmony-mcp/config.json:

{
  "apiKey": "hmy_...",
  "apiUrl": "https://gethmy.com/api",
  "userEmail": "[email protected]",
  "activeWorkspaceId": null,
  "activeProjectId": null
}

Local Project Configuration

Stored in .harmony-mcp.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:

npx @gethmy/mcp setup --email [email protected]

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

Viewing Configuration

npx @gethmy/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: .harmony-mcp.json
    Workspace: my-team-id
    Project: my-project-id
  Global config: ~/.harmony-mcp/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:

.harmony-mcp.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

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

Adding a new skill

1. Define MY_SKILL_CONTENT in src/skills.ts.
2. Add it to SKILL_DEFINITIONS with name, description, argumentHint, and content.
3. Bump SKILLS_VERSION so installed clients refresh on next startup.
4. 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__/.