@gethmy/mcp
Advanced tools
MCP server for Harmony, the shared surface for human–agent teams — agents claim cards, report progress, and move work on your board.
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.
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:
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-keyfor unattended CI. Browser sign-in is the recommended path when a person is present.
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
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" }.
If you prefer to configure manually (e.g., in Claude.ai's UI):
https://mcp.gethmy.com/mcpBearer hmy_your_key_hereSession 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.
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.
# 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.
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:
~/.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.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.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.| 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 |
| 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) |
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 WorkflowWhen you start working on a card (e.g., /hmy #42):
/hmy-plan — Plan WorkflowA 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):
harmony_create_planExecuting a plan (/hmy-plan <existing plan>):
/hmy-cleanup — Board AuditScans 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 SummaryGenerates 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.
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).
harmony_create_card - Create a new cardharmony_update_card - Update card propertiesharmony_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 boardharmony_delete_card - Delete a cardharmony_assign_card - Assign to team memberharmony_search_cards - Search by title/descriptionharmony_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 }. SeeCHANGELOG.md(2.14.0).
harmony_add_link_to_card - Create a link between two cardsharmony_remove_link_from_card - Remove a link between cardsharmony_get_card_links - Get all links for a cardLink 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 |
harmony_create_column - Create new columnharmony_update_column - Update column propertiesharmony_delete_column - Delete columnharmony_create_label - Create new labelharmony_add_label_to_card - Add label to cardharmony_remove_label_from_card - Remove labelharmony_create_subtask - Create subtaskharmony_toggle_subtask - Toggle completionharmony_delete_subtask - Delete subtaskharmony_list_workspaces - List workspacesharmony_list_projects - List projectsharmony_get_board - Get board state (supports pagination via limit/offset, summary mode, columnId filter, includeArchived)harmony_get_workspace_members - Get team membersharmony_list_agents - List a workspace's virtual agents (daemons); use the id with harmony_assign_card (agentId)harmony_set_workspace_context - Set active workspaceharmony_set_project_context - Set active projectharmony_get_context - Get current contextharmony_process_command - Process natural language commandsharmony_start_agent_session - Start tracking work on a card (with moveToColumn and addLabels side effects)harmony_update_agent_progress - Update progress, status, blockersharmony_end_agent_session - End session (completed/paused); triggers active learning extractionharmony_get_agent_session - Get current session stateSessions 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:
harmony_start_agent_session) are never auto-endedharmony_generate_prompt - Generate an AI-ready prompt from a card with assembled memory contextParameters:
| 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.
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 duplicatesharmony_recall - Retrieve memories by type, tags, scope, or text query, rescored by relevance × recency × typeharmony_update_memory - Replace a memory's fact, title, tags, type or scopeharmony_forget - Permanently delete a memoryharmony_memory_search - Full-text search across the vault, markdown outMemory 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.
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)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 tasksharmony_get_plan - Get plan by ID or card IDharmony_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:
harmony_onboard - Complete end-to-end onboarding: signup → workspace → project → API keyharmony_signup - Create a new user accountharmony_create_workspace - Create a new workspaceharmony_create_project - Create a new project with template columns (kanban, scrum, or simple) harmony_send_invitations - Send workspace invitations to team membersharmony_generate_api_key - Generate an API key for the authenticated userYou 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"
| 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 |
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": "you@example.com",
"activeWorkspaceId": null,
"activeProjectId": null
}
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.
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 you@example.com # npx fallback: npx @gethmy/mcp connect --email you@example.com
The email must match your Harmony account email to work correctly.
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
Add this to prevent accidentally committing local config:
.hmy.json
┌─────────────────┐ 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:
bun run test:unit # fast — covers dispatch + skills
bun run test:integration # spins up real memory pipeline
bun run typecheck # type-only check
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. |
TOOLS in src/server.ts (name, description, inputSchema).case "harmony_..." branch in handleToolCall.bun run test:unit — the parameterized assertions in tool-dispatch.test.ts automatically cover the new entry's shape.mcp-integration.test.ts with one extra case.MY_SKILL_CONTENT in src/skills.ts.SKILL_DEFINITIONS with name, description, argumentHint, and content.SKILLS_VERSION so installed clients refresh on next startup.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__/.
FAQs
MCP server for Harmony, the shared surface for human–agent teams — agents claim cards, report progress, and move work on your board.
The npm package @gethmy/mcp receives a total of 602 weekly downloads. As such, @gethmy/mcp popularity was classified as not popular.
We found that @gethmy/mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Research
/Security News
Socket uncovered two malicious VS Code themes in a GlassWorm-linked cluster with thousands of installs across VS Code Marketplace and Open VSX.
Security News
/Company News
Capital One is partnering with Socket to proactively secure its open source supply chain.
Security News
Socket CTO Ahmad Nassri discusses how to keep AI agents from bypassing package blocks, limit credential access, and monitor their actions.