MCP Server Setup Guide

Prerequisites

• Node.js 20+ — node --version should show v20 or higher
• Albumi account — sign up for early access if you don't have one
• An MCP-compatible AI agent — Claude Code, Cursor, or any MCP client

Install & Authenticate

This opens your browser for authentication. After you log in, a token is saved to ~/.albumi/credentials.json. You don't need to log in again unless the token expires.

Configure: Claude Code

That's it. Claude Code now has access to Albumi tools. You can verify with:

You should see albumi in the list with 4 tools available.

Configure: Cursor

Add to your project's .cursor/mcp.json:

{
  "mcpServers": {
    "albumi": {
      "command": "npx",
      "args": ["@albumi/mcp"]
    }
  }
}

Restart Cursor. The Albumi tools appear in the agent sidebar.

Configure: Other MCP Agents

For any MCP-compatible agent, the server command is:

Transport: stdio. The server reads from stdin and writes to stdout using the MCP protocol. Refer to your agent's documentation for how to add stdio MCP servers.

For CI/CD or token-based auth (no browser login), set environment variables:

{
  "mcpServers": {
    "albumi": {
      "command": "npx",
      "args": ["@albumi/mcp"],
      "env": {
        "ALBUMI_API_URL": "https://my.albumi.app",
        "ALBUMI_API_TOKEN": "your-api-token"
      }
    }
  }
}

Pull a Workspace

Ask your agent to pull your workspace. The agent will list available workspaces, ask you to pick one, and download it as a JSON file.

The workspace JSON contains all your architecture data: organizations, business capabilities, data objects, IT components, applications (with interfaces), integrations, and initiatives. The agent reads the file and works with it directly — you don't need to touch the JSON yourself.

Generate Architecture from Documents

The MCP server includes a generate_workspace prompt with complete schema documentation. Your agent knows the full workspace format — all entity types, required fields, validation rules, and enum values.

Feed your agent any source material and ask it to create the architecture:

The agent generates the JSON with proper UUIDs, referential integrity, lifecycle metadata, and all required fields. It then validates and audits before pushing.

Validate

Validation checks three things: JSON schema compliance, referential integrity (every ID reference resolves), and circular reference detection (parentId chains).

If there are errors, the agent sees them and can fix them automatically:

The agent handles the fix-validate cycle on its own — broken references, missing fields, invalid values. You only see the final result.

Audit

The audit runs 70+ deterministic checks on your architecture data. No AI judgment — these are rules-based assessments.

Output includes a summary and detailed findings:

Summary: 12 findings (2 critical, 5 warning, 5 info)

CRITICAL: Legacy CRM (Application)
  Active integrations depend on EOL application.
  Affected: Storefront → Legacy CRM,
            Legacy CRM → Data Warehouse

WARNING: Customer Data (DataObject)
  Classification "confidential" but integration
  uses authentication "none"

INFO: Mobile App (Application)
  Missing business criticality level

You can ask the agent to focus on specific areas:

Push Changes

After editing, validating, and auditing, push changes back to Albumi:

The agent creates an Architecture Change Request (ACR). You review and approve it in Albumi's web UI. Nothing changes in your production workspace until you explicitly approve.

Push result:
  ACR created: "Initial Architecture Import"
  ACR ID: acr-019d-08ab-...
  Entities: 5 orgs, 12 capabilities, 8 data objects,
            45 applications, 67 integrations, 3 initiatives

→ Review in Albumi UI to apply changes

Full Audit Checks Reference

All 70+ automated checks grouped by category. Each check produces findings with severity: critical warning info

Environment Variables

Authentication priority: environment variables first, then CLI login credentials from ~/.albumi/credentials.json.

Troubleshooting