Album MCP

AI agent integration via Model Context Protocol

album-mcp is an MCP server that exposes Album’s catalog and solution management as tools any MCP-compatible AI agent can call (e.g. Claude, Copilot, or any client supporting the Model Context Protocol).

Why MCP for Album?

Album solutions are tool-grounded executable building blocks: each one has a machine-readable manifest, typed arguments, and lifecycle hooks. That makes them a good fit for LLM-driven orchestration. Concretely, exposing Album over MCP gives an agent three capabilities:

• Discover the solutions actually available in the user’s catalogs (no free-form internet search, no invented tool names).

• Install and execute those solutions through typed tool calls (album_install_solution, album_run_solution) instead of arbitrary shell commands.

• Chain solutions to fulfil a multi-step user request — each step is a versioned, testable artifact rather than a one-off snippet.

This is a practical grounding mechanism: the agent picks from an explicit inventory, which mitigates a class of free-form hallucinations (nonexistent tools or flags). It does not eliminate error — incorrect parameterization, unsuitable solution choice, or silent scientific failures are still possible. For drafting new solutions with an LLM, see Drafting solutions with LLMs.

Installation

1. Install Album.

2. Activate the Album environment:

   micromamba activate album
   

3. Install the MCP server following the instructions in the album-mcp README.

Environment setup

The server requires micromamba to create and manage solution environments. Set the environment variable pointing to your micromamba binary before starting the server:

# Local — point to your micromamba installation
export ENVIRONMENT_DEBUGGING_MICROMAMBA_PATH=$(which micromamba)

Registering the server

Register the server with your MCP client:

uvx mcp install --with album src/album/mcp/main.py

Refer to your MCP client’s documentation for how to connect to a registered server.

Available tools

Tool	Read-only	Description
album_list_catalogs	✅	List all registered catalogs
album_add_catalog	❌	Add a catalog from a URL or local path
album_remove_catalog	❌	Remove a catalog by name
album_update_catalog	❌	Pull the latest solution index from a catalog
album_list_solutions	✅	List all solutions (optionally filtered by catalog)
album_search_solutions	✅	Search catalogs by keyword
album_get_solution_info	✅	Inspect a solution’s arguments, metadata, and citations
album_install_solution	❌	Install a solution and provision its environment
album_uninstall_solution	❌	Remove a solution and its environment
album_run_solution	❌	Execute an installed solution with arguments

Typical agent workflow

1. Discover — album_list_catalogs → album_list_solutions or album_search_solutions

2. Inspect — album_get_solution_info to read argument names and types

3. Install & run — album_install_solution → album_run_solution

4. Keep up to date — album_update_catalog to pull the latest index

Example: a user request that fans out into tool calls

A user prompt like “Take the images in ~/data/raw/ and produce denoised segmentations” should drive the agent through roughly this sequence:

1. album_search_solutions("denoise") and album_search_solutions("segment") to find candidate building blocks.

2. album_get_solution_info(...) on each candidate to read the typed arguments and decide if they fit (e.g. expected input modality, output schema).

3. album_install_solution(...) for each chosen solution — Album provisions each one in its own micromamba environment, so dependency conflicts between the denoiser and the segmenter do not matter.

4. album_run_solution(...) for each step, threading outputs through the solution-scoped data paths.

The agent never invents a CLI flag — it only calls into tool operations whose inputs Album validates against the solution’s manifest.

Safety and trust

Per-solution micromamba environments are an isolation boundary, not a security sandbox. A solution still runs as your user with full access to your filesystem and network. When letting an LLM drive Album, treat the agent like a junior collaborator with shell access:

• Prefer curated catalogs you trust (your group’s, a community catalog you vet); be cautious about adding arbitrary catalogs an agent suggests.

• Keep destructive operations (album_uninstall_solution, album_remove_catalog, file-mutating run calls) behind an explicit confirmation in your MCP client, where supported.

• Consider running agent-driven workflows inside a container or VM if the consequences of a wrong tool call are non-trivial.

Agent system prompt

The album-mcp README contains a ready-to-use system prompt you can paste into your agent’s configuration. It covers key Album concepts, the recommended tool calling order, and error handling guidance.