@elevate/constellation-mcp

MCP server for institutional governance — "AI that checks before it acts."

Constellation surfaces constraints, traces decisions, and records institutional memory. It never blocks actions; it informs them.

Tools

check — "Can I do X?"

Evaluates an intended action against institutional constraints.

{
  "action": "spend $15,000 on new servers",
  "domain": "finance",
  "context": { "amount": 15000 }
}

Returns: whether the action is allowed, what constraints apply, what approvals are needed, and human-readable advice.

boundary — "What are my limits?"

Returns all active constraints, grouped by type.

{
  "domain": "communications",
  "includeRationale": true
}

Returns: constraint list with optional rationale and authorship (Symmetry Principle — you can see the rules that govern you and why they exist).

record — "This happened"

Records an action that was taken, creating an institutional trace.

{
  "action": "published quarterly results blog post",
  "domain": "communications",
  "outcome": "published successfully after board approval"
}

Supports overrides with required justification (Override Principle):

{
  "action": "emergency press release about data breach",
  "domain": "communications",
  "outcome": "published within 30 minutes of discovery",
  "overrideConstraintId": "timing-comms-001",
  "overrideJustification": "Legal obligation to disclose within 72 hours. Board chair verbally approved at 2:15am."
}

Constitutional Principles

• Institutional Memory: Every tool call creates a trace
• Symmetry: Constraints include authorship and rationale — actors see the rules that govern them
• Override Principle: Any constraint can be overridden, but overrides must be explicit, attributable, and evidentiary
• Human Judgment: Tools never block — they surface constraints and advise
• Non-Surveillance: Traces exist for memory, not for ranking individuals

Setup

Claude Desktop

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

{
  "mcpServers": {
    "constellation": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/packages/constellation-mcp/src/index.ts"]
    }
  }
}

Then restart Claude Desktop. The five tools (check, boundary, record, escalate, preview) will appear in the tools menu.

Claude Code

Add to .claude/settings.json in your project root:

{
  "mcpServers": {
    "constellation": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/packages/constellation-mcp/src/index.ts"]
    }
  }
}

Claude Code will pick up the MCP server automatically. You can verify with /mcp in the CLI.

Database Persistence (Optional)

To persist traces to the Constellation database, set these environment variables in your MCP server config:

{
  "mcpServers": {
    "constellation": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/packages/constellation-mcp/src/index.ts"],
      "env": {
        "CONSTELLATION_API_URL": "http://localhost:3000",
        "CONSTELLATION_API_KEY": "csk_your_api_key_here",
        "CONSTELLATION_INSTITUTION_ID": "your_institution_id",
        "CONSTELLATION_ACTOR_ID": "your_clerk_user_id"
      }
    }
  }
}

Without these, traces are stored in-memory only (lost on restart). With them, every check/record/escalate is persisted and visible in the Governance > Traces page.

Development

# Install dependencies (from monorepo root)
pnpm install

# Type check
pnpm --filter @elevate/constellation-mcp type-check

# Run server (stdio — will wait for input)
pnpm --filter @elevate/constellation-mcp start

Architecture

src/
├── index.ts              # MCP server entry point (stdio transport)
├── types.ts              # Shared types (tool inputs/outputs)
├── tools/
│   ├── check.ts          # "Can I do X?"
│   ├── boundary.ts       # "What are my limits?"
│   ├── record.ts         # "This happened"
│   ├── escalate.ts       # "This needs approval"
│   └── preview.ts        # "What would this have blocked?"
├── constraints/
│   ├── types.ts          # Constraint type definitions
│   ├── engine.ts         # Constraint evaluation logic
│   └── hardcoded.ts      # Test constraints (replaced by DB in Week 2+)
└── traces/
    ├── types.ts          # Trace type definitions
    └── logger.ts         # In-memory + optional database persistence

What's Built

• 5 MCP tools: check, boundary, record, escalate, preview
• 8 hardcoded constraints (AUTHORITY, THRESHOLD, PROHIBITION, TIMING)
• In-memory trace store + optional database persistence via API
• Keyword-based constraint matching
• Database-backed constraints (GovernanceConstraint model in idealoom-database)
• Admin UI for constraints, thresholds, authority, and exceptions
• Escalation tool with urgency levels
• Proof export (JSON/CSV for auditors)
• Constraint Preview (simulate impact against trace history)
• API key authentication
• Governance page (Symmetry Principle — all members see constraints)
• Traces viewer (actors see their own governance activity)