Agent integration

Connect any coding agent over MCP — the three tool families, get_map, and the just-in-time guide model.

Altitude has one core with three front doors: the CLI, the Web UI, and MCP (any external agent). A click, a CLI command, and an agent tool call all invoke the same action and read the same state. Altitude is agent-agnostic — it never bundles or mandates an agent.

Connect

Run the board in your worktree, then point your agent at Altitude over the Model Context Protocol:

claude mcp add altitude -- altitude mcp --allow-ui-control

Or configure the MCP server directly:

{
  "mcpServers": {
    "altitude": {
      "command": "altitude",
      "args": ["mcp", "--cwd", "/abs/path/to/your/worktree", "--allow-ui-control"]
    }
  }
}

The server is a per-worktree stdio process — there is no global daemon. Read-only tools are always allowed; every mutating tool needs --allow-ui-control. The session token that authorizes it is owner-only on disk — that filesystem permission is the trust boundary.

The three tool families

Domain tools — stateless, server-side, work with no UI open:

Session tools — run inside the open browser tab (get_current_view, select_scope, set_query, navigate_to_scope, get_selection). With no tab open they return no_active_session.

Canvas tools — tab-free file writes. The agent reads the map, proposes on the board, discards an unwanted proposal per item, reports completion (the flip to built), and extends the type system (create_template). Examples: create_proposed_scope, create_connection, delete_proposed_scope, set_scope_status, set_connection_status, commit_agreement.

get_map — orient here first

get_map returns the architecture map — one scopes array (every scope, whether it’s a folder-backed manifest or a folder-less record), the connections, and any errors. A scope or connection in status: proposed is a blueprint.

Beside the map it carries the recovery surface so a fresh agent can always re-orient:

• drift — built items whose code drifted underneath them (facts).
• notes — forgot-to-flip heuristics (e.g. a proposed scope whose source already exists).
• pending — built items the map moved ahead of; the code must follow.
• uninstructed — code changes since the last agreement that no claim explains.
• recovery — a summary of counts across all of the above.

The just-in-time guide

MCP clients truncate or ignore a server’s instructions field, so nothing load-bearing lives there. Altitude ships only a compact router note (a pinned preamble under 1,500 characters) whose one job is to send the agent to get_map.

The full working guide arrives on the tool-result channel instead — get_map’s guide field, picked for the project’s current state:

• an empty map returns the fresh-repo setup guide,
• a mapped repo returns the build-loop guide (orient → light up under-construction → implement → flip to built).

This is progressive disclosure: the guide reaches the agent just in time, on the one channel that reliably arrives.

The build loop over MCP

1. get_map to orient (and read the guide).
2. create_proposed_scope / create_connection (status: proposed) to sketch the work in blueprint state — it appears on the human’s board live.
3. set_scope_building / set_connection_building to signal presence while you implement.
4. set_scope_status: built / set_connection_status: built to report each item done — it turns solid on the board.
5. commit_agreement as the turn’s last act — stage board and code and commit them as one.

A connection is first-class buildable: it stays proposed until you write its code and flip it, never inferred from its endpoints.

Add-to-chat handoff

When the human multi-selects scopes and connections on the board and hits Add to chat, call get_selection to receive the precise sub-graph they pointed at — the selected scopes, the connections internal to that selection, and any explicitly selected connections — never a screenshot.

Full contract

The complete state-and-action contract lives in the repo’s docs/core-interface.md, kept honest by a manifest test. This page is the public summary of it.