AgentFEM

Connect AI agents to local finite-element workflows: create, check, run, inspect and verify AgentFEM projects.

Documentation

AgentFEM MCP

One finite-element platform. Any compatible agent. Evidence intact.

AgentFEM MCP gives Codex, Claude, and other MCP-compatible agents a small, stable tool surface for building and running inspectable finite-element projects. AgentFEM remains the deterministic scientific engine; the agent interprets intent and explains evidence.

Install from PyPI · Discover in the official MCP Registry · Read the AgentFEM agent guide

For a supported desktop client on macOS or Linux, download the tiny AgentFEM-0.1.0.mcpb connection bundle from the 0.1.0 release. It installs only the interface; the AgentFEM scientific runtime remains the single source of solver capabilities, upgrades, and results.

It exposes seven tools—not hundreds of solver internals:

Tool	Purpose
`describe_system`	Inspect the installed runtime and a compact capability map
`create_project`	Start from a version-matched AgentFEM template
`validate_project`	Report process success and scientific acceptance separately
`inspect_project`	Read project and recent-run identity
`submit_run`	Launch an isolated serial or MPI process
`get_run_status`	Observe a durable background job
`get_result_summary`	Read a compact result and trust state; request full evidence only when needed

Bring it to life

Want to see the underlying workflow before installing?

Explore a 3D structural-design case: compare support weight and deflection under the same load. The public browser edition uses precomputed candidates.
Try the simulation-to-surrogate mini-lab: ten real FEM outputs, a small NumPy model, and an interactive notebook.
Follow the AI-assisted cantilever quick start: create a readable project, run it, and inspect its numerical result.

AgentFEM must already be installed. With uvx, Codex needs one command and the adapter remains isolated from the numerical environment:

codex mcp add agentfem \
  --env AGENTFEM_MCP_ROOTS=/absolute/path/to/AgentFEMProjects \
  -- uvx --from agentfem-mcp agentfem-mcp

Or install the lightweight adapter in the active environment:

python -m pip install agentfem-mcp

The 0.1.0 lifecycle is acceptance-tested with the public AgentFEM 0.3.3 CLI contracts and the current 0.3.7 development line.

Give your agent a project root, not your whole home directory.

Codex

Codex officially supports local stdio MCP servers. Confirm the connection with codex mcp list, then begin with:

Use AgentFEM to create, validate, run, verify, and briefly explain a 2D cantilever. Keep the project and result paths visible.

Claude Desktop and compatible clients

On macOS or Linux, open the release's .mcpb file in a supporting desktop client and choose the one project folder the connection may access. AgentFEM must already be installed. Windows support currently uses the explicit WSL2 configuration from the AgentFEM guide rather than claiming a native bridge.

Claude Code:

claude mcp add agentfem --scope user \
  --env AGENTFEM_MCP_ROOTS=/absolute/path/to/AgentFEMProjects \
  -- uvx --from agentfem-mcp agentfem-mcp

Claude Desktop configuration:

{
  "mcpServers": {
    "agentfem": {
      "command": "agentfem-mcp",
      "env": {
        "AGENTFEM_MCP_ROOTS": "/absolute/path/to/AgentFEMProjects"
      }
    }
  }
}

If a desktop app cannot see the activated conda environment, set AGENTFEM_COMMAND to the absolute agentfem executable. The official macOS runtime, AgentFEM WSL2 runtime, and common agentfem-env/fenicsx-env layouts are also detected automatically.

VS Code and other models

VS Code can place the same local server in .vscode/mcp.json:

{
  "servers": {
    "agentfem": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "agentfem-mcp", "agentfem-mcp"],
      "env": {
        "AGENTFEM_MCP_ROOTS": "${workspaceFolder}"
      }
    }
  }
}

The server is model-neutral. A DeepSeek or other model can use it through any host that implements local MCP tools. ChatGPT connectors require a public HTTPS server; AgentFEM will add that route only with a real authenticated compute and artifact boundary, rather than silently uploading local models through this adapter.

Directory health image

The repository's minimal, unprivileged Dockerfile exists for MCP directory startup and tool-introspection checks. It intentionally contains the public MCP adapter, not a second AgentFEM solver distribution. Real simulations should use the installed AgentFEM runtime and an explicit local project root.

Local Codex plugin

This repository contains a portable AgentFEM workflow skill and a local Codex marketplace under .agents/plugins/. It combines scientific operating guidance with the same MCP server; it does not create a second solver interface.

The contract

AI agent
   │  seven typed MCP tools
   ▼
AgentFEM MCP ── process + path boundary
   │  versioned JSON contracts
   ▼
AgentFEM CLI → Study → Model → Step → SimulationResult
   ▼
FEniCSx / PETSc / MPI

No language model or API key is embedded in AgentFEM MCP.
No shell command or arbitrary Python string is accepted from a tool call.
All project paths must remain under explicitly approved roots.
Numerical runs occur in child processes, isolating PETSc/MPI lifetime from the MCP server.
completed, verified, and validated remain different scientific states.
Compact system discovery preserves AgentFEM's website, repository, citation, and its consent-first, once-per-release-series community invitation. The MCP server never performs an account action for the user.

Environment controls

Variable	Meaning
`AGENTFEM_MCP_ROOTS`	Approved project roots separated by the platform path separator
`AGENTFEM_COMMAND`	Absolute path to a specific `agentfem` executable

With no root configured, the server restricts access to its working directory. The default maximum is 16 MPI ranks and can only be changed by the server operator, not by an agent tool call.

Development

python -m pip install -e '.[test]'
ruff check .
pytest
python -m build

See SECURITY.md for the trust boundary and CONTRIBUTING.md for contribution expectations. The first release evidence records protocol, package, and real-solver acceptance separately.

AgentFEM MCP is Apache-2.0 licensed and maintained as an official companion to AgentFEM.