OpenAssetIO MCP Server

An MCP server that exposes OpenAssetIO functionality as tools for LLM clients.

Install

pip install .

Run

openassetio-mcp

Note

The MCP server assumes OpenAssetIO is configured using the OPENASSETIO_DEFAULT_CONFIG environment variable. See OpenAssetIO docs for details.

The server starts on http://localhost:8000/mcp by default.

$ openassetio-mcp --help
usage: openassetio-mcp [-h] [--host HOST] [--port PORT]

OpenAssetIO MCP server

options:
  -h, --help   show this help message and exit
  --host HOST  Host to bind to (env: OPENASSETIO_MCP_HOST, default: localhost)
  --port PORT  Port to bind to (env: OPENASSETIO_MCP_PORT, default: 8000)

Supported OpenAssetIO Functions

The following OpenAssetIO operations are exposed as MCP tools:

Tool	Description
resolve	Resolve entity references to trait property data.
entity_exists	Query the manager to confirm entities exist.
entity_traits	Retrieve the trait set ("type") of entities.
is_entity_reference_string	Check if strings match the manager's reference format.
manager_identifier	Unique identifier of the configured manager plugin.
manager_display_name	Human-readable name of the manager.
manager_info	Auxiliary manager metadata (version, docs URL, etc.).
manager_settings	Current runtime settings of the manager.
ping	Health check - returns session and context IDs.

Traits Catalogue

The server exposes an MCP resource at openassetio://traits containing the full trait and specification catalogue as YAML. LLM clients read this resource to understand available trait IDs and their properties, helping the agent to answer domain-specific questions and construct valid tool requests.

The bundled openassetio-mediacreation definitions are included by default.

Extending the catalogue

Set the OPENASSETIO_MCP_TRAIT_DEFINITIONS environment variable to a list of additional trait definition YAML files (separated by the platform path separator - : on Linux/macOS, ; on Windows):

export OPENASSETIO_MCP_TRAIT_DEFINITIONS="/path/to/my-traits.yaml:/path/to/other-traits.yaml"

Each file must be a valid OpenAssetIO trait definition YAML document (for example, see the MediaCreation traits). Later files take precedence over earlier ones (with the bundled openassetio-mediacreation package being the earliest). Conflicting packages are replaced (not merged), allowing e.g. a custom openassetio-mediacreation YAML document to completely override the bundled document, if desired.

Development

Recommended to use uv for development.

To create a .venv environment with an editable (symlink-like) install of the project, and configure pre-commit (linter) hooks, run:

uv venv
uv sync --all-extras
uv run pre-commit install

Note that the pyright linter will expect a virtual environment path of .venv (default for uv venv).

Testing

uv run pytest

Linting

uv run pre-commit run --all-files

If linter checks fail, most issues can be auto-fixed by running the following formatters and fixers:

uv run ruff format src tests
uv run ruff check --fix src tests
uv run mdformat .github/ src/ tests/ *.md

Then re-run the linting checks and repeat until everything passes.

Contributing

Please feel free to contribute pull requests or issues. Note that contributions will require signing a CLA.

See the OpenAssetIO contribution docs for how to structure commit messages, the pull request process, and coding style guide.