MCP Server Setup

The Albumi MCP server lets AI agents work directly with your architecture data — pull, generate, validate, audit, and push changes.

Prerequisites

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

Install & Authenticate

npx @albumi/mcp login

This opens your browser for authentication. A token is saved to ~/.albumi/credentials.json. You don’t need to log in again unless the token expires.

Configure: Claude Code

claude mcp add albumi -- npx @albumi/mcp

Verify with:

claude mcp list

You should see albumi 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

The server command is:

npx @albumi/mcp

Transport: stdio. Refer to your agent’s documentation for how to add stdio MCP servers.

For CI/CD or token-based auth:

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

Slash commands

Installing the MCP server also registers five MCP prompts. In Claude Code these surface as slash commands — start typing / in the chat and you’ll see them in the picker:

Command	What it does
/mcp__albumi__pull_workspace	Download a workspace from the server as JSON — the starting point of any edit workflow
/mcp__albumi__validate	Check a local workspace JSON file for schema and referential-integrity errors
/mcp__albumi__audit	Run the full architecture audit — structural integrity, data quality, lifecycle, compliance, portfolio health
/mcp__albumi__generate_workspace	Prime the agent with the workspace schema to generate a new workspace from a landscape description
/mcp__albumi__push_workspace	Upload a local workspace JSON as a reviewable Architecture Change Request

Each slash command injects a prepared prompt with context and the right tool sequence. You can invoke the slash command directly, or just describe the goal in plain English — the agent picks the same tools either way.

Other MCP clients (Cursor, etc.) expose the same prompts through their own UI. The prompt names (pull_workspace, validate, audit, generate_workspace, push_workspace) are identical across clients; only the invocation syntax differs.

Environment Variables

Variable	Required	Description
ALBUMI_API_URL	If not using CLI login	Base URL (e.g., https://my.albumi.app)
ALBUMI_API_TOKEN	If not using CLI login	Bearer token for API auth
ALBUMI_CONFIG_DIR	No	Config directory (default: ~/.albumi)

Auth priority: environment variables first, then CLI login credentials.

Verify it works

Once the server is registered, ask your agent to pull your workspace (or run /mcp__albumi__pull_workspace in Claude Code):

“Pull my Albumi workspace.”

The agent lists available workspaces (by name and ID), you pick one, and it downloads the full architecture — applications, integrations, data objects, capabilities, IT components, organizations, initiatives, and their relationships — as JSON into the agent’s context.

From there, read-only follow-ups are free:

“How many applications are marked Mission Critical?”

“Which integrations depend on Salesforce?”

“List every application end-of-life in the next 12 months.”

Nothing is written back to Albumi by these commands. Writes go through the Change Request flow — the agent proposes, you approve in the UI.

Troubleshooting

“No workspaces found” — Token may be expired. Run npx @albumi/mcp login again.

“Authentication failed” — Delete ~/.albumi/credentials.json and log in again.

“Tool not found” — Verify the MCP server is registered. Claude Code: claude mcp list. Cursor: check .cursor/mcp.json and restart.

Node.js version error — Requires Node.js 20+. Check with node --version.

Next steps

• Generate Architecture — create a complete workspace from existing documents, spreadsheets, or free-form descriptions of your landscape.
• Validate & Audit — run schema validation, referential-integrity checks, and 70+ quality/compliance audit rules.
• Use Cases — prompt patterns that combine pull, validate, audit, and push for real work (initial landscape import, incremental updates, impact briefings, drift detection).
• Change Requests (ACR) — how agent-proposed changes become approved workspace edits.