AI Assistants (MCP)

This is the primary way Align gets used. Your agent knows the code in front of it. It does not know what your team decided, when, or what has since replaced that decision. MCP is how it finds out.

Align speaks the Model Context Protocol. Any MCP client works - Claude Desktop, Claude Code, Cursor, VS Code Copilot Chat, Windsurf, or your own.

Two servers, and you need to know which one you are talking to

They expose different tool names, and nothing in the client tells you which answered.

	Hosted server	CLI server
What it reads	Your shared org graph	A local graph on your machine
Started by	Align (or your self-hosted deployment)	align mcp
Transport	Streamable HTTP	stdio
Tool naming	dotted - search	underscored - search
Tools	19	8
Requires	A Pro or Self-Hosted workspace	Nothing. Free, no account

If you configure both, give them distinct server names in your client config. Asking one graph a question the other holds returns a confident, correct-looking answer about the wrong data.

Option 1: the CLI (free, no account)

Fastest path. Builds a personal graph from your own tools and serves it to any agent.

npm install -g @aligndottech/cli
align import git          # or jira, github, linear, confluence, slack, notion...
align mcp --setup         # detects your editors and writes their MCP config

--setup writes this for you, but if you prefer to do it by hand:

{
  "mcpServers": {
    "align": {
      "command": "align",
      "args": ["mcp"]
    }
  }
}

Add "--env", "preview" to the args to point the CLI at a non-production workspace.

CLI tools (8)

Tool	What it does
search	Search the graph
align_ask	Natural-language question over the graph
capture	Capture a decision from a URL
check_alignment	Check a diff against the graph
check_drift	Score code or config against one decision
get_impact	Blast radius of a decision
get_conflicts	Active contradictions
get_related_decisions	Decisions related to a file path

Option 2: the hosted server (shared org graph)

Point your client at the Align MCP endpoint over streamable HTTP:

Environment	URL
Production	https://mcp.align.tech/tools
Preview	https://mcp.preview.align.tech/tools
Local / self-hosted	http://localhost:8089/tools

Cursor, VS Code Copilot Chat and Windsurf all take a URL directly. Claude Desktop and Claude Code speak stdio, so use the CLI server above, or an HTTP-to-stdio bridge.

Credentials for the hosted server are held server-side and bound to your workspace. They are not sent as request headers from the client.

Hosted tools (19)

Ask the graph

Tool	What it does
search	Natural-language search across every decision
search_decisions	The same search, tuned for IDE-shaped queries
get_related_decisions	Decisions related to a file path
get_decision_rationale	Why a decision was made
get_decision_timeline	The chronological thread around a decision
get_decision_history	The supersession chain - what replaced it, what it replaced
get_impact	Upstream and downstream blast radius
get_blocking_decisions	What is blocking a given decision
get_conflicts	Active contradictions between decisions

Check before you act

Tool	What it does
check_alignment	Check a git diff against the graph
check_proposed_action	Check a proposed PR, ticket, message or commit
check_drift	Score code or config against one decision
coach	Surface conflicts, missing context and blockers for a direction
rate_conflict	Record whether a surfaced conflict was right

Write and administer

Tool	What it does
capture	Record a new decision from text
analyze	Extract decisions and open debates from pasted messages
list_connectors	Which integrations are connected
connect	Start an integration's OAuth flow
connect_status	Whether a connector is connected

19 names, about 14 distinct behaviours

Some tools are deliberate aliases with different affordances for an agent. search, search_decisions and get_related_decisions all resolve to the same semantic search; check_alignment and check_proposed_action both resolve to the same alignment check, with the former prepending the changed file paths from a diff.

We would rather say this than let a tool count read as a capability count.

Getting the most out of it

The tools work unprompted, but agents use them far better when told when to reach for them. Add something like this to your CLAUDE.md, .cursorrules or equivalent:

- BEFORE writing or changing non-trivial code, call check_alignment with the diff.
  A "conflicting" result means a past decision opposes the change - stop and confirm.
- "unknown" means the check could not run. It is NOT a pass. Surface it.
- To answer "why did we decide X", or any question about BEHAVIOUR ("what happens when
  Y fails", "does it fail open"), call search BEFORE reading the code. The graph
  spans repositories; grepping this checkout silently misses decisions made elsewhere.
- After acting on a conflict, call rate_conflict with the check_event_id.

That last one matters more than it looks. A flag nobody judges teaches the graph nothing.

Self-hosted configuration

Variable	Default	Purpose
GATEWAY_URL	http://gateway:8080	Where the MCP server reaches the Align API
ALIGN_API_KEY	-	Workspace API key
ALIGN_TENANT_ID	-	Workspace tenant ID
MCP_TRANSPORT	http	http or stdio
PORT	8089	Listen port

Find your tenant ID under Settings → Account, and create an API key under Settings → API Tokens.

Troubleshooting

The agent answers from the code instead of the graph. Usually the instruction, not the wiring. Confirm the tools are listed in your client, then tell the agent explicitly to search the graph first.

The agent gets decisions that are not yours. You have more than one Align server configured and it picked the wrong one. Distinct server names, and name the server in the instruction.

Nothing connects. Check the port is free (lsof -i :8089), the URL ends in /tools, and for the CLI that align whoami resolves against the environment you expect.

Next steps

• Agent Alignment Layer - the check-before-you-act half
• CLI - every command and flag
• Features - what the graph holds