> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enagrams.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> The 26 MCP tools your agents use to coordinate

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that lets AI agents call structured tools. Enagrams ships an MCP server bundled with the `enagrams` npm package. Every tool below is callable from any MCP-compatible client (Cursor, Claude Code, Codex, Windsurf, custom).

## Install

`npx enagrams init` writes the MCP config for every supported IDE automatically. If you're setting up by hand:

```json theme={null}
{
  "mcpServers": {
    "enagrams": {
      "command": "npx",
      "args": ["-y", "enagrams", "--mcp"],
      "env": {
        "ENAGRAMS_API_KEY": "...",
        "ENAGRAMS_WORKSPACE": "your-workspace-slug"
      }
    }
  }
}
```

The server speaks stdio to your IDE and HTTP to the Enagrams API.

## Tools by Category

### Coordination and Context

Core tools every agent calls several times a session.

| Tool                    | Purpose                                                                                                           |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
| [`sync`](/mcp/sync)     | Report what you're working on; get teammate activity, decisions, conflicts, and learnings back in one round-trip. |
| [`decide`](/mcp/decide) | Record an architectural choice (with rationale) so every other agent sees it.                                     |
| [`search`](/mcp/search) | Semantic search over past decisions.                                                                              |
| [`learn`](/mcp/learn)   | Share a gotcha, workaround, or pattern you just discovered.                                                       |
| [`ask`](/mcp/ask)       | Ask a question against the workspace knowledge base.                                                              |

### Contracts

Interface contracts let one agent publish a shape — API response, type definition, function signature — and other agents query it.

| Tool                      | Purpose                               |
| ------------------------- | ------------------------------------- |
| [`publish`](/mcp/publish) | Register or update a shared contract. |

Contract changes surface in everyone's next `sync`. Use `ask` (free-form) or `search` to discover existing contracts.

### Workstreams

Workstreams map 1:1 to shared git branches `ena/<slug>` and enable symbol-level coordination with other participants.

| Tool                                              | Purpose                                                              |
| ------------------------------------------------- | -------------------------------------------------------------------- |
| [`workstream_start`](/mcp/workstream-start)       | Create a workstream and its branch.                                  |
| [`workstream_join`](/mcp/workstream-join)         | Join an existing workstream.                                         |
| [`workstream_leave`](/mcp/workstream-leave)       | Leave without ending it for others.                                  |
| [`workstream_end`](/mcp/workstream-end)           | Abandon a workstream for the whole team.                             |
| [`workstream_complete`](/mcp/workstream-complete) | Wrap up — returns a squash-merge plan, then finalizes with `pr_url`. |
| [`workstream_list`](/mcp/workstream-list)         | List active or completed workstreams.                                |

### The Test Gate

Gate changes before they land on a workstream. Two-phase: first call returns affected tests, second call submits results.

| Tool                                  | Purpose                                                                             |
| ------------------------------------- | ----------------------------------------------------------------------------------- |
| [`confirm_ready`](/mcp/confirm-ready) | Tier-A/B gate. On pass writes a `sync_log` receipt.                                 |
| [`sync_commit`](/mcp/sync-commit)     | Record that you pushed a commit. Prefer passing `sync_log_id` from `confirm_ready`. |
| [`sync_retract`](/mcp/sync-retract)   | Retract a previously synced commit so watchers revert locally.                      |

### Negotiation

When two agents want the same symbol, `negotiate_*` runs a bounded-turn state machine with auto-resolution.

| Tool                                          | Purpose                                          |
| --------------------------------------------- | ------------------------------------------------ |
| [`negotiate_open`](/mcp/negotiate-open)       | Open a negotiation over contested symbols.       |
| [`negotiate_respond`](/mcp/negotiate-respond) | Respond: yield / hold / defer / counter / split. |
| [`negotiate_list`](/mcp/negotiate-list)       | See whether anyone is waiting on you.            |

### Tasks

Delegate follow-up work inside a workstream with dependency-based auto-unblocking.

| Tool                                  | Purpose                                             |
| ------------------------------------- | --------------------------------------------------- |
| [`delegate_task`](/mcp/delegate-task) | Create (and optionally assign) a task.              |
| [`task_claim`](/mcp/task-claim)       | Claim a queued task.                                |
| [`task_update`](/mcp/task-update)     | Update status (triggers unblock cascade on `done`). |
| [`task_list`](/mcp/task-list)         | List tasks by workstream, assignee, or status.      |

### Conventions and Decision Staleness

Living conventions layer on top of decisions. `must`-tier conventions are hard gates on PreToolUse. Stale decisions get surfaced for review when their linked code drifts.

| Tool                                            | Purpose                                                 |
| ----------------------------------------------- | ------------------------------------------------------- |
| [`convention_propose`](/mcp/convention-propose) | Record a `must`/`should`/`may` convention.              |
| [`convention_list`](/mcp/convention-list)       | List conventions, optionally filtered by tier or files. |
| [`decisions_stale`](/mcp/decisions-stale)       | List decisions whose linked code has drifted.           |
| [`decision_reaffirm`](/mcp/decision-reaffirm)   | Mark stale decisions fresh again.                       |

## How Agents Use Them

A typical session looks like:

```
sessionStart (hook)        → briefing injected
sync                       → get team state
workstream_start/join      → claim branch
decide / publish           → record new choices / contracts
[edit files]               → hook calls file_lock on PreToolUse
convention_list (on block) → understand why an edit was denied
delegate_task              → hand off follow-up to another agent
confirm_ready (no results) → get affected tests
[run tests locally]
confirm_ready (results)    → gate pass → sync_log receipt
sync_commit                → notify watchers of the new commit
sessionEnd (hook)          → release reservations
```

Most tools accept an optional `session_id`; the MCP server also automatically scopes each call to your workspace.