MCP Server Setup

The Albumi MCP server lets AI agents work directly with your architecture data — pull, generate, validate, audit, and push changes. It ships as part of @albumi/cli — a single binary (albumi) that works as both a command-line tool and an MCP stdio server.

Prerequisites

• Node.js 24+ recommended (20 minimum). Node 24 ships with npm ≥ 11 which avoids known edge cases around provenance and Trusted Publisher publishes. node --version to check.
• Albumi account — sign up if you don’t have one
• An MCP-compatible AI agent — Claude Code, Cursor, Claude Desktop, or any MCP client

Three layers

Albumi integration has three independent components. Most users need all three; advanced users can pick:

Layer	What	Audience	Always required?
CLI binary	albumi executable on your PATH	Everyone — humans, CI, and the MCP server process	✅ Yes
MCP server registration	Tells your agent to spawn albumi as an MCP server	Anyone connecting an AI agent	✅ For agent use
Skill (albumi-workspace)	Markdown routing rules that teach the agent when to use CLI vs MCP tool calls	Claude Code only (other clients don’t support skills)	❌ Nice-to-have

Step 1: Install the CLI

npm install -g @albumi/cli
albumi login

albumi login opens your browser, authenticates your Albumi account, and saves a token to ~/.albumi/credentials.json. The token is reused for both CLI commands and the MCP server — no need to log in again unless it expires.

Verify: albumi --help should print the command reference.

Step 2: Register the MCP server with your agent

Claude Code

Option A — Plugin (recommended). Installs the MCP server registration and the albumi-workspace skill in one step:

/plugin marketplace add albumi-eam/albumi-cli
/plugin install albumi@albumi-cli
/reload-plugins

The /reload-plugins command activates the MCP server and skill in the current session — otherwise you’d need to restart Claude Code.

Option B — Manual (MCP server only, no skill):

claude mcp add albumi -- albumi

Verify either way:

claude mcp list

You should see albumi with 4 tools available.

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (all projects):

{
  "mcpServers": {
    "albumi": {
      "command": "albumi"
    }
  }
}

Restart Cursor. Albumi tools appear in the agent sidebar.

Claude Desktop

Edit the config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "albumi": {
      "command": "albumi"
    }
  }
}

Restart Claude Desktop.

Other MCP agents

Server command: albumi. Transport: stdio. No arguments.

Refer to your agent’s documentation for how to register a stdio MCP server.

CI / token-based auth

For non-interactive environments (CI pipelines, Docker containers), set ALBUMI_API_TOKEN as a secret and reference it:

ALBUMI_API_TOKEN=<token> albumi validate ./workspace.json

Or in an MCP config that runs in CI:

{
  "mcpServers": {
    "albumi": {
      "command": "albumi",
      "env": {
        "ALBUMI_API_TOKEN": "${ALBUMI_API_TOKEN}"
      }
    }
  }
}

Slash commands

Skill command

If you installed via the Claude Code plugin (/plugin install albumi@albumi-cli), the albumi-workspace skill is also available as a slash command:

Command	What it does
/albumi-workspace	Loads the Albumi workspace skill — routes the agent between CLI and MCP tool calls based on what you’re trying to do.

When to use it: Skills auto-activate heuristically — Claude Code loads them when your message matches the skill’s description. If your request is narrow or doesn’t mention “Albumi” explicitly, auto-activation can miss. Invoke /albumi-workspace at the start of an Albumi-related session to guarantee the routing rules are in context.

This is not required for MCP tools themselves — pull_workspace, validate, audit, push_workspace are always available to the agent once the plugin is installed, regardless of skill state. The skill just tells the agent when to prefer CLI vs MCP; without it, the agent will still use MCP tools, just with less nuanced routing.

MCP prompt commands

Installing the MCP server 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.

CLI mode

Everything the agent can do, you can do from your shell:

albumi pull --workspace <id>     # download workspace JSON
albumi validate ./ws.json        # schema + referential integrity
albumi audit ./ws.json           # ~70 EAM checks
albumi push ./ws.json            # upload as an ACR
albumi --help                    # full reference

All commands exit 0 on success, 1 on failure — safe for CI, pre-commit hooks, and make targets.

Environment Variables

Variable	Required	Description
ALBUMI_API_TOKEN	If not using CLI login	Bearer token for API auth (typical for CI)
ALBUMI_CONFIG_DIR	No	Config directory (default: ~/.albumi)

Auth priority: environment variable → credential file (~/.albumi/credentials.json from albumi login).

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

“Not authenticated” — Run albumi login again.

“No workspaces found” — Token may be expired. Run albumi login to refresh.

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

“Command not found: albumi” — The global install didn’t put the binary on your PATH. Run npm config get prefix to see where npm installs globals; make sure that path’s bin/ directory is in your $PATH.

“Tool not found” — Verify the MCP server is registered. Claude Code: claude mcp list or /plugin 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.