Overview

What is MCP?

The Model Context Protocol 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:

{
  "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`	Report what you’re working on; get teammate activity, decisions, conflicts, and learnings back in one round-trip.
`decide`	Record an architectural choice (with rationale) so every other agent sees it.
`search`	Semantic search over past decisions.
`learn`	Share a gotcha, workaround, or pattern you just discovered.
`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`	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`	Create a workstream and its branch.
`workstream_join`	Join an existing workstream.
`workstream_leave`	Leave without ending it for others.
`workstream_end`	Abandon a workstream for the whole team.
`workstream_complete`	Wrap up — returns a squash-merge plan, then finalizes with `pr_url`.
`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`	Tier-A/B gate. On pass writes a `sync_log` receipt.
`sync_commit`	Record that you pushed a commit. Prefer passing `sync_log_id` from `confirm_ready`.
`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`	Open a negotiation over contested symbols.
`negotiate_respond`	Respond: yield / hold / defer / counter / split.
`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`	Create (and optionally assign) a task.
`task_claim`	Claim a queued task.
`task_update`	Update status (triggers unblock cascade on `done`).
`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`	Record a `must`/`should`/`may` convention.
`convention_list`	List conventions, optionally filtered by tier or files.
`decisions_stale`	List decisions whose linked code has drifted.
`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.

Coordination & Context

Workstreams

Test Gate

Negotiation

Tasks

Conventions & Living Decisions

Overview

What is MCP?

Install

Tools by Category

Coordination and Context

Contracts

Workstreams

The Test Gate

Negotiation

Tasks

Conventions and Decision Staleness

How Agents Use Them

​What is MCP?

​Install

​Tools by Category

​Coordination and Context

​Contracts

​Workstreams

​The Test Gate

​Negotiation

​Tasks

​Conventions and Decision Staleness

​How Agents Use Them

What is MCP?

Install

Tools by Category

Coordination and Context

Contracts

Workstreams

The Test Gate

Negotiation

Tasks

Conventions and Decision Staleness

How Agents Use Them