MCP Server

matgpr includes an optional local Model Context Protocol server for AI coding agents. The server exposes public matgpr package knowledge as structured, read-only tools so agents can choose featurizers, inspect physics-equation templates, validate safe custom equations, and design validation or Bayesian-optimization workflows without guessing API names.

This server is a companion to the open-source matgpr library. It does not expose downstream project-specific workflows.

Current Status

The MCP server is currently available on the development branch and is planned for a future v0.2.x release. Until that release is published, install from a local checkout when testing the MCP server.

The first MCP version is intentionally conservative:

• local STDIO transport,
• read-only tools,
• read-only prompt templates,
• read-only static guide resources,
• JSON-safe outputs,
• no model fitting,
• no Bayesian-optimization execution,
• no shell execution,
• no arbitrary Python execution,
• no file writes,
• no automatic package installation,
• no imports from downstream project packages.

Install

For a released version that includes MCP support:

python -m pip install "matgpr[mcp]"

For the current development branch:

git clone https://github.com/harikrishna-chem/matgpr.git
cd matgpr
python -m pip install -e ".[mcp]"

Supported MCP SDK versions

The mcp extra requires mcp>=1.14. Both major SDK lines work:

MCP SDK	Server class	Notes
2.x	mcp.server.MCPServer	Current line. FastMCP was renamed to MCPServer.
1.14 to 1.x	mcp.server.fastmcp.FastMCP	Supported; server metadata is omitted because FastMCP does not accept it.

matgpr picks the right class automatically. Versions 1.10 to 1.13 are not supported: they cannot register tools from modules that use from __future__ import annotations, which matgpr does throughout.

Check that the command is available:

matgpr-mcp

The command starts a local STDIO MCP server. Most users will not run it directly; their MCP host will start it when needed.

Verify that a real MCP client can initialize the server and list the expected tools, prompts, and resources:

matgpr-mcp-smoke

For a machine-readable result:

matgpr-mcp-smoke --json

Configure Codex

Codex can run local STDIO MCP servers from its config.toml file. Add this to your Codex MCP configuration:

[mcp_servers.matgpr]
command = "matgpr-mcp"
args = []
enabled = true

For project-scoped setup, place the configuration in .codex/config.toml for a trusted project. For user-wide setup, use the default Codex configuration file.

You can also add the server from the Codex CLI:

codex mcp add matgpr -- matgpr-mcp
codex mcp list

Configure Claude Code

Claude Code can also launch local STDIO MCP servers. Add matgpr with:

claude mcp add --transport stdio matgpr -- matgpr-mcp

The double dash separates Claude Code's MCP options from the command used to start the server.

Tool Overview

The initial server exposes read-only helper tools.

Tool	Purpose
get_matgpr_info	Returns version, install, documentation, DOI, and capability metadata.
list_capabilities	Lists public matgpr workflows and the main APIs for each.
recommend_featurizers	Suggests composition, molecule SMILES, polymer SMILES, structure, numeric, and target-column handling from schema evidence.
list_physics_equations	Lists built-in physics-equation templates, optionally filtered by query, application, tag, or required features.
get_physics_equation	Returns detailed metadata for one physics-equation template.
validate_safe_equation	Validates a safe custom equation spec and returns schema-level diagnostics.
preview_safe_equation	Evaluates a valid safe custom equation on a few supplied rows and summarizes physics-mean outputs.
suggest_validation_workflow	Recommends learning-curve, train/test, cross-validation, and uncertainty-diagnostic protocols.
suggest_bo_workflow	Recommends a finite-pool Bayesian-optimization setup without executing BO.

Prompt Overview

The server also exposes prompt templates that help AI agents follow documented matgpr workflows instead of inventing package usage from memory.

Prompt	Purpose
plan_featurization_workflow	Plans column-role detection and featurizer selection from schema/sample-row evidence.
plan_physics_informed_gpr_workflow	Plans PI-GPR setup with physics-template lookup, safe-equation checks, feature maps, and model comparison.
plan_validation_workflow	Plans learning curves, train/test splits, metrics, and uncertainty diagnostics.
plan_bayesian_optimization_workflow	Plans finite-pool BO or active-learning recommendations with uncertainty, constraints, and duplicate avoidance.

Resource Overview

Static guide resources provide compact Markdown notes for common agent tasks.

Resource URI	Purpose
matgpr://guide/capabilities	Public MCP capability map and safety boundary.
matgpr://guide/featurization	Materials column types and matching featurizers.
matgpr://guide/physics-informed-gpr	PI-GPR mean-function setup and reporting expectations.
matgpr://guide/validation	Validation outputs, repeated splits, and uncertainty checks.
matgpr://guide/bayesian-optimization	Finite-pool BO planning flow and recommendation reporting.

Example Agent Prompts

After connecting the server, useful prompts include:

Ask matgpr which featurizer I should use for these columns:
formula, polymer_smiles, solvent_smiles, temperature_C, diffusivity

Ask matgpr to list physics equations related to diffusion.

Ask matgpr to validate this safe custom equation before I use it as a
physics-informed GPR mean function.

Ask matgpr to preview this safe equation on these three temperature rows and
summarize the physics mean values.

Ask matgpr to suggest a low-data validation workflow for a 75-row regression
dataset.

Use the matgpr PI-GPR planning prompt for a diffusivity model with temperature,
polymer fingerprint, and solvent fingerprint features.

Featurizer Recommendation Inputs

recommend_featurizers is designed for small schema previews, not full datasets. Pass:

• column names,
• optional dtype summaries,
• one to five sample rows,
• optional target-column name,
• optional task type.

The tool uses conservative heuristics. It can recognize common evidence for:

• inorganic composition/formula columns,
• molecule SMILES columns,
• polymer repeat-unit SMILES columns with [*] dummy atoms,
• crystal-structure columns or file names,
• numeric process-condition columns,
• likely target columns.

Always review the recommendation before training. Ambiguous columns should be confirmed by the user.

Safe Equation Validation

validate_safe_equation wraps the public safe-equation schema and validator. The input is the same JSON-like spec used by matgpr.safe_equations.

Minimal example:

{
  "name": "linear_temperature_mean",
  "expression": "offset + slope * temperature_k",
  "variables": [
    {"name": "temperature_k", "units": "K"}
  ],
  "parameters": [
    {"name": "offset", "initial_value": 0.0},
    {"name": "slope", "initial_value": 1.0}
  ]
}

The tool returns:

• whether the spec is valid,
• validation errors and warnings,
• normalized spec when valid,
• the safe-equation schema snapshot,
• implementation hints.

The validator does not use eval. It accepts only declared symbols, allowlisted operators, and allowlisted mathematical functions.

Safe Equation Preview

preview_safe_equation validates the same safe-equation spec and then evaluates the equation on a small set of explicitly supplied rows. It is useful before training a PI-GPR model because it can catch:

• missing variable columns,
• non-numeric variable values,
• non-finite equation outputs,
• target-minus-physics residual scale,
• unit mistakes that are visible in the preview values.

Example using row records:

{
  "spec": {
    "name": "linear_temperature_mean",
    "expression": "offset + slope * temperature_k",
    "variables": [
      {"name": "temperature_k", "units": "K"}
    ],
    "parameters": [
      {"name": "offset", "initial_value": 1.0},
      {"name": "slope", "initial_value": 2.0}
    ]
  },
  "sample_rows": [
    {"temperature_k": 300.0, "target": 601.0},
    {"temperature_k": 310.0, "target": 620.0}
  ],
  "target_column": "target"
}

Example using direct variable arrays:

{
  "spec": {
    "name": "sqrt_preview",
    "expression": "sqrt(x)",
    "variables": [
      {"name": "x"}
    ]
  },
  "variable_values": {
    "x": [4.0, 9.0, 16.0]
  }
}

The preview returns:

• equation validation diagnostics,
• normalized equation spec,
• row-count and input-mode metadata,
• physics mean summary statistics,
• optional residual summary when target values are supplied,
• clipped preview values,
• warnings and implementation hints.

The MCP preview is capped to a few rows. It does not fit a model and does not read datasets from disk.

What The Server Does Not Do Yet

The first public MCP server is advisory. It does not yet:

• fit GPR models,
• run Bayesian optimization,
• read arbitrary files,
• write artifacts,
• execute notebooks,
• install dependencies,
• upload data,
• call external services.

Those capabilities can be considered later only after the read-only server is stable and the safety model is reviewed.

Troubleshooting

If matgpr-mcp is not found:

python -m pip install -e ".[mcp]"

or, after a release that includes MCP support:

python -m pip install "matgpr[mcp]"

If the command reports that MCP is missing, install the MCP extra:

python -m pip install "matgpr[mcp]"

If your MCP host cannot find matgpr-mcp, use the full path from:

which matgpr-mcp

and place that absolute command path in the host configuration.

You can also smoke-test the absolute path directly:

matgpr-mcp-smoke --command /absolute/path/to/matgpr-mcp

If an MCP host starts but does not show tools, restart the host after changing its MCP configuration.

Development Checks

Before releasing MCP support, run:

python -m ruff check matgpr tests scripts
python -m ruff format --check matgpr tests scripts
python -m pytest
python -m mkdocs build --strict
python -m build
python -m pip install -e ".[mcp]"
matgpr-mcp-smoke

For package-upload readiness, also run twine check on the generated distribution files.

References

• Model Context Protocol tools specification
• OpenAI Codex MCP documentation
• Claude Code MCP documentation
• MCP Python SDK