AI Assistant Integration

Connect your AI coding assistant to Align's decision intelligence. Search decisions, detect drift, find conflicts, and capture new decisions - all from within your editor.

Supported Assistants

Assistant	Transport	Status
Claude Desktop	stdio	Supported
Cursor	streamable-http	Supported
VS Code (Copilot Chat)	streamable-http	Supported
Claude Code (CLI)	stdio	Supported
Windsurf	streamable-http	Supported

How It Works

Align exposes a Model Context Protocol (MCP) server that gives AI assistants direct access to your team's decision graph. When your assistant needs context about past decisions, it calls Align's tools instead of guessing.

Your AI Assistant → Align MCP Server → Align Gateway API → Decision Graph

The MCP server runs locally alongside your assistant (stdio mode) or as a hosted service (HTTP mode). It authenticates to Align's Gateway API with your API key.

Available Tools

Tool	Description
align.search	Search decisions using natural language - "why did we choose Postgres?"
align.check_drift	Check if code or config has drifted from a documented decision
align.get_impact	See what decisions depend on this one before making changes
align.get_conflicts	List active conflicts between decisions across all platforms
align.capture	Record a new decision from your AI assistant conversation
align.analyze	Extract decisions and debates from pasted conversation text

Setup

Claude Desktop

Add to your claude_desktop_config.json (on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "align": {
      "command": "npx",
      "args": ["tsx", "src/server.ts"],
      "cwd": "/path/to/align-stack/connectors/mcp-align",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "GATEWAY_URL": "https://api.align.tech",
        "ALIGN_API_KEY": "your-api-key",
        "ALIGN_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

Claude Code (CLI)

Add to your .mcp.json in your project root:

{
  "mcpServers": {
    "align": {
      "command": "npx",
      "args": ["tsx", "src/server.ts"],
      "cwd": "/path/to/align-stack/connectors/mcp-align",
      "env": {
        "MCP_TRANSPORT": "stdio",
        "GATEWAY_URL": "https://api.align.tech",
        "ALIGN_API_KEY": "your-api-key",
        "ALIGN_TENANT_ID": "your-tenant-id"
      }
    }
  }
}

Cursor

In Cursor Settings → MCP Servers, add the hosted MCP endpoint:

{
  "align": {
    "url": "https://mcp.align.tech/tools",
    "transport": "streamable-http"
  }
}

For the hosted Align MCP service, your API key and tenant ID are configured on the server via environment variables or secrets - you do not need to send them as request headers from your MCP client.

tip

For self-hosted deployments, replace mcp.align.tech with your MCP server URL (e.g., https://mcp.your-domain.com/tools) and configure ALIGN_API_KEY and ALIGN_TENANT_ID via environment variables on your MCP server.

Environments

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

Configuration

Variable	Description	Default
GATEWAY_URL	Align Gateway API URL	http://gateway:8080
ALIGN_API_KEY	Your Align API key	-
ALIGN_TENANT_ID	Your tenant ID	-
MCP_TRANSPORT	stdio or http	http
PORT	HTTP server port (http mode only)	8089

Finding Your Credentials

1. Tenant ID - Go to Settings in Align, your tenant ID is shown under Organization
2. API Key - Go to Settings → API Keys, click Create API Key

tip

For self-hosted deployments, set GATEWAY_URL to your internal Gateway URL (e.g., http://gateway:8080 or https://api.your-domain.com).

Example Usage

Once connected, your AI assistant can use Align's tools naturally:

"What did we decide about caching?" → Assistant calls align.search with query "caching strategy" → Returns decisions from Slack, Jira, GitHub with context and rationale

"Does this PR drift from our API versioning decision?" → Assistant calls align.check_drift with the decision ID and PR diff → Returns severity, specific issues, and recommended action

"What depends on the Postgres decision before I change it?" → Assistant calls align.get_impact with the decision ID → Returns upstream and downstream decision graph

"We just decided to use Redis for session storage" → Assistant calls align.capture with the decision text → Records the decision, extracts goals/risks/actions, links to related decisions

Self-Hosted Setup

For self-hosted deployments, the MCP server is included in the Docker Compose stack:

docker compose up mcp-align

It connects to your Gateway at http://gateway:8080 automatically.

Troubleshooting

"Connection refused" in Cursor

• Ensure the MCP server is running: npx tsx src/server.ts
• Check the port isn't in use: lsof -i :8089
• Verify MCP_TRANSPORT=http is set

"Unauthorized" errors

• Check your API key is valid
• Verify your tenant ID matches your organization
• For self-hosted: ensure SERVICE_AUTH_TOKEN is set

Tools not appearing

• Restart your AI assistant after adding the MCP config
• Check the MCP server logs for connection errors
• Verify the config file path is correct