harmony-mcp

An MCP (Model Context Protocol) server that connects your local workspace to the Harmony backend for codebase indexing and context retrieval. It exposes tools over stdio that let an MCP-compatible coding agent authenticate, index your project, and pull back precise, ranked code context instead of blindly reading or grepping the whole repo.

Requirements

• Node.js >= 18 (ships with npx, which is how the server is run below)

Check whether you have it:

node -v

If this prints v18.x.x or higher, you're set. If you see command not found or a lower version, install/upgrade Node first:

• macOS: brew install node (or brew upgrade node if already installed)
• Windows/macOS: download the LTS installer from nodejs.org
• Linux: use your distro's package manager (e.g. sudo apt install nodejs npm on Debian/Ubuntu), or NodeSource for a newer version
• Any OS (recommended for managing multiple versions): install nvm, then run:

  nvm install --lts
  nvm use --lts

Re-run node -v afterwards to confirm before continuing.

Installation

The server is published as @codeconductorai/harmony-mcp and run via npx, so no local build step is required. The commands below pin an exact version (@1.0.28) rather than a floating tag — this lets npx reuse its local cache instead of re-resolving the package from the registry on every agent startup, which otherwise makes MCP initialization noticeably slower (and occasionally hang). Bump the pinned version deliberately when you want to upgrade.

Claude Code

claude mcp add harmony -- npx -y @codeconductorai/[email protected]

Antigravity

Open MCP Servers → Manage MCP Servers → View raw config from the agent panel, or edit the config file directly:

• Global: ~/.gemini/config/mcp_config.json
• Workspace-local: .agents/mcp_config.json

{
  "mcpServers": {
    "harmony": {
      "command": "npx",
      "args": ["-y", "@codeconductorai/[email protected]"]
    }
  }
}

Restart Antigravity (or reload MCP servers) after saving.

Codex CLI

codex mcp add harmony -- npx -y @codeconductorai/[email protected]

This writes the entry to ~/.codex/config.toml. To add it by hand instead:

[mcp_servers.harmony]
command = "npx"
args = ["-y", "@codeconductorai/[email protected]"]

Aria

In the Aria Code panel, click the settings icon → MCP Servers, then scroll down and click Edit Global MCP (applies everywhere, via mcp_settings.json) or Edit Project MCP (this project only, writes .Aria/mcp.json). Add:

{
  "mcpServers": {
    "harmony": {
      "command": "npx",
      "args": ["-y", "@codeconductorai/[email protected]"]
    }
  }
}

Save the file — Aria Code picks up the new server automatically, no restart needed.

Other MCP clients

Any client that reads a command/args style config (e.g. Claude Desktop's claude_desktop_config.json) can use the same shape:

{
  "mcpServers": {
    "harmony": {
      "command": "npx",
      "args": ["-y", "@codeconductorai/[email protected]"]
    }
  }
}

Getting started

After adding the server and restarting your client:

1. setup_workspace — registers the current project (language and buildTool required the first time) and fully indexes it (zips and uploads the codebase) in one call. Call this first, even before logging in: some backend deployments authenticate the workspace internally with no login involved at all, so this can succeed on its own. It's idempotent, so calling it again once setup and indexing have completed is a cheap no-op; if it fails partway, calling it again retries just the incomplete step. Once indexing succeeds, a background file watcher pushes incremental updates to the backend as you edit files.
2. If setup_workspace (or any tool below) fails with a "not authenticated" error, this deployment requires login: call login, which starts a device-flow login and returns a URL to open in your browser.
3. Finish logging in, then tell the agent you're done so it can call confirm_login to complete authentication. The session is cached at ~/.harmony-mcp/session.json, so you won't need to log in again until it expires. Call setup_workspace again afterward.
4. Use context_search first to pull relevant code context for a prompt — it's Harmony's newest, best-ranked search endpoint, always available as the default entry point for every discovery need in a task, and takes precedence over locate below. Fall back to locate only if context_search comes up short or you need its line-number-only anchors — and when you do, feed it a combination of the user's original query and the symbols/identifiers/file paths context_search already surfaced, not the raw query on its own.

Workspace state (workspace ID, language, build tool, setup/upload status) is cached in a .harmony_workspace.json marker file in the project root.

Workspace-token auth and refresh

On deployments that skip login entirely (step 1 above), setup_workspace's first call gets back two credentials instead of one: a short-lived access token (used as the Bearer on every API call) and a long-lived refresh token. Both are stored in ~/.harmony-mcp/workspace-tokens.json — never in the project's .harmony_workspace.json marker, since that file has no guarantee of staying out of version control and these are bearer credentials.

This is fully automatic — no tool call or user action needed. Before every API request, the access token's expiry is checked locally; once it's expired (or close to it), the stored refresh token is exchanged for a new access token behind the scenes and the request proceeds with it. Only if the refresh token itself is missing or has expired does a call start failing with a "not authenticated" error, at which point running setup_workspace again mints a fresh pair.

Tools

login

Starts a device-flow login session and returns a loginUrl to open in the browser plus a userCode.

confirm_login

Completes authentication after the browser login. Requires userConfirmed: true, which must only be set after the user has explicitly confirmed (in chat) that they finished logging in.

• timeout (optional): max seconds to wait (default 300).

setup_workspace

Registers the current project as a workspace on the backend and fully indexes it (zips and uploads the codebase) in a single call. The zip excludes VCS/IDE directories, per-language build/dependency output (node_modules, target, dist, build, .venv, vendor, etc.), compiled/binary/media file types, common lockfiles, and the workspace marker — kept in sync with the backend's own indexing file filter, so nothing gets uploaded that the backend would just discard anyway. Starts the file watcher for incremental re-indexing once done. Safe to call again anytime — a .harmony_workspace.json marker tracks setup/upload state and the last-indexed commit, so it's a no-op if nothing has changed, and automatically re-uploads if the local commit has moved on since the last successful upload. If it fails partway (e.g. the upload step errors out after the workspace was already created), call it again — language/buildTool can be omitted on that retry since they're remembered from the marker, and only the incomplete step re-runs.

• language (required on first call): e.g. JAVA, JAVASCRIPT, TYPESCRIPT, PYTHON.
• buildTool (required on first call): e.g. MAVEN, GRADLE, NPM.

Every workspace is tagged with a scheme-aware repoId, surfaced in the response as repoId/repoIdScheme: git_url:<host/org/repo> (normalized origin remote URL — the common case), falling back to git_commit:<root sha> (Git repo with no remote), artifact:<ecosystem>:<name> (no .git at all — read from pom.xml/package.json/go.mod/Cargo.toml/pyproject.toml), or dir:<folder name> as a last resort.

context_search

PREFERRED FIRST CHOICE for any code discovery/comprehension need — Harmony's newest and best-ranked search endpoint. Given a natural-language query or exact identifier, returns ranked matching symbols as structural facts and precise file:line locations, deliberately without embedded source code. Takes precedence over locate; only fall back to it if context_search's result is empty/insufficient or you specifically need its line-number-only anchors for a targeted edit. Treat it as the always-on default entry point for every new discovery/comprehension need that comes up during a task — call it again each time, not just once. When falling back to locate afterward, its input should combine the user's original query with the symbols/identifiers/file paths this call already surfaced, rather than repeating the same raw query unchanged.

• prompt (required): natural-language query or exact identifier to find context for.
• file_path (optional): path substring to restrict results to a subdirectory, module, or specific file.
• limit (optional): max results; the backend applies its own default if omitted.
• workspaceId (optional): target a specific workspace instead of the local project's. Defaults to the local setup_workspace workspace.

locate

Given a natural-language query or exact identifier, returns lightweight symbol coordinate anchors (file path, symbol name, kind/type, whether it's a definition, line numbers, primary role) — no code snippets. Use it to find which file(s) and exact line(s) to look at or edit for a task.

• prompt (required): what to find, e.g. "where user login is handled" or "CrudController". Must be non-blank — a missing or whitespace-only prompt returns an empty list, not an error.
• file_path (optional): case-insensitive substring match against the full file path (not exact-path or prefix) to restrict results to a subdirectory, module, or specific file.
• limit (optional): max results (default 40); the result list is never padded to this size.
• workspaceId (optional): target a specific workspace instead of the local project's. Defaults to the local setup_workspace workspace.

Observability (OpenObserve)

The server ships its own logs, traces, and metrics over OTLP/HTTP using OpenTelemetry, and forwards the active trace id to every request it makes to the harmony backend (as a W3C traceparent header plus a plain X-Trace-Id header) so backend-side logs can be correlated with the MCP session that triggered them.

Telemetry is exported to the harmony backend's /api/v1/otel/{traces,metrics,logs} endpoints rather than straight to OpenObserve — the backend forwards it on to OpenObserve using a server-side-only ingestion credential. This package holds no OpenObserve credential of its own: it authenticates to the backend with whichever Bearer session or workspace token it already uses for every other API call, so nothing extra needs to be configured, and a plain npx install never needs (or can leak) an ingestion secret. If neither token is available yet (e.g. before login/setup_workspace), export calls simply fail unauthenticated against the backend and are logged, without affecting normal server operation.

Local development

npm install
npm start