MCP Server

The Model Context Protocol (MCP) server exposes Metaxy's feature graph and metadata store operations to AI assistants, enabling them to explore your feature definitions and query metadata.

Installation

Install Metaxy with the mcp extra:

uvpip

uv add metaxy[mcp]

pip install metaxy[mcp]

Running the Server

Run the MCP server from your Metaxy project directory:

metaxy mcp # (1)!

1. Use uv run metaxy mcp to run the server within the project's Python environment.

The server uses the standard Metaxy configuration discovery, loading metaxy.toml from the current directory or parent directories.

Configuration

Claude Code

Add the MCP server to your project's .claude/settings.json:

{
  "mcpServers": {
    "metaxy": {
      "command": "metaxy",
      "args": ["mcp"]
    }
  }
}

Available Tools

The MCP server provides the following tools:

get_config

Get the current Metaxy configuration as JSON.

Returns:

The full Metaxy configuration serialized as JSON, including all settings like project, store, entrypoints, stores, migrations_dir, etc.

get_feature

Get the complete specification for a feature.

Parameters:

Name	Type	Required	Default	Description
feature_key	str	Yes	—	Feature key in slash notation (e.g., "video/processing")

Returns:

Complete feature specification as a dictionary including fields, dependencies, id_columns, and other metadata

get_metadata

Query metadata for a feature from a store.

Parameters:

Name	Type	Required	Default	Description
feature_key	str	Yes	—	Feature key in slash notation (e.g., "video/processing")
store_name	str	Yes	—	Name of the metadata store to read from
columns	list[str] | None	No	None	List of columns to select (None for all)
filters	list[str] | None	No	None	List of SQL-like filter expressions (e.g., "column > 5", "name == 'foo'")
current_only	bool	No	True	Only return current (non-superseded) rows
latest_only	bool	No	True	Only return latest version of each row
include_soft_deleted	bool	No	False	Include soft-deleted rows
allow_fallback	bool	No	True	If True, check fallback stores when feature is not found in the primary store
sort_by	list[str] | None	No	None	List of column names to sort by
descending	bool | list[bool]	No	False	Sort descending (bool for all columns, or list per column)
limit	int	No	50	Maximum number of rows to return

Returns:

Dictionary containing:

• columns: List of column names
• rows: List of row dictionaries
• total_rows: Number of rows returned

get_store

Get display information for a metadata store.

Parameters:

Name	Type	Required	Default	Description
store_name	str	Yes	—	Name of the store to get info for

Returns:

Human-readable display string for the store (e.g., "DuckDBMetadataStore(database=/tmp/db.duckdb)")

list_features

List all registered features with their metadata.

Matches the output format of mx list features --format json.

Parameters:

Name	Type	Required	Default	Description
project	str | None	No	None	Filter by project name (optional)
verbose	bool	No	False	Include detailed field information and dependencies

Returns:

Dictionary containing:

• feature_count: Total number of features
• features: List of feature dictionaries with key, version, is_root, project, import_path, field_count, fields, and optionally deps

list_stores

List all configured metadata stores.

Returns:

List of dictionaries with 'name' and 'type' for each store