AgentFEM MCP lets AI agents create, validate, run, and inspect finite-element projects through seven typed tools while keeping scientific evidence and trust states intact.
describe_system: Inspect the installed AgentFEM runtime, approved project roots, and capability map.
create_project: Create a new project from an official version-matched AgentFEM template inside an approved root.
validate_project: Run fail-closed structural and compatibility checks without solving the project.
inspect_project: Read project validation and recent immutable run identities without modifying anything.
submit_run: Launch an isolated serial or MPI finite-element run in a separate process and get a durable job ID.
get_run_status: Poll a background job's status and available execution evidence.
get_result_summary: Read a structured scientific result summary (or full evidence) with its trust state for a completed job or latest run.
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 |
| Inspect the installed runtime and a compact capability map |
| Start from a version-matched AgentFEM template |
| Report process success and scientific acceptance separately |
| Read project and recent-run identity |
| Launch an isolated serial or MPI process |
| Observe a durable background job |
| Read a compact result and trust state; request full evidence only when needed |
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-mcpOr install the lightweight adapter in the active environment:
python -m pip install agentfem-mcpThe 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 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.
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-mcpClaude 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 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.
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.
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.
Related MCP server: pyNastran MCP Server
AI agent
│ seven typed MCP tools
▼
AgentFEM MCP ── process + path boundary
│ versioned JSON contracts
▼
AgentFEM CLI → Study → Model → Step → SimulationResult
▼
FEniCSx / PETSc / MPINo 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.
Variable | Meaning |
| Approved project roots separated by the platform path separator |
| Absolute path to a specific |
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.
python -m pip install -e '.[test]'
ruff check .
pytest
python -m buildSee 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.
Create a new project from one version-matched official AgentFEM template inside an approved root.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| path | Yes | ||
| template | No | static-solid |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this is not read-only, not idempotent, and not destructive. The description adds the 'approved root' and 'version-matched' constraints, which are more about prerequisites than behavior. It does not disclose side effects (e.g., overwriting existing projects), permission requirements, or what 'approved' means. Given annotations cover safety, the description adds minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and key constraints without fluff. Every word contributes to the meaning, making it efficient and easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with three parameters and no parameter documentation in the schema, the description should clarify what 'approved root' means, how to specify a valid template, and whether the tool creates directories or files. The output schema exists but the description lacks crucial invocation details, leaving an agent to guess.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It hints that 'path' must be inside an approved root and that 'template' must be a version-matched official template, but it does not explain the 'name' parameter, the format of 'path', or the available template values. This is insufficient for a tool with three parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Create a new project') and adds precise constraints: 'version-matched official AgentFEM template' and 'inside an approved root'. This clearly distinguishes it from sibling tools like validate_project or inspect_project, which are about analysis rather than creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives contextual constraints (version-matched template, approved root) that imply when to use it, but does not explicitly compare against alternatives or state when not to use it. An agent could infer the purpose, but there is no routing guidance to other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the installed AgentFEM runtime and approved roots. Use summary first; request full only when selecting an advanced capability.
| Name | Required | Description | Default |
|---|---|---|---|
| detail | No | summary |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, and the 'Inspect' language aligns with those. The description adds value by scoping behavior to the installed runtime and approved roots and by flagging that 'full' should be reserved for advanced-capability selection, which is useful beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words: the first gives the scope, the second gives an actionable usage rule. It is front-loaded and does not repeat annotations or schema information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a simple single-parameter schema, an output schema present, and comprehensive annotations, the description is complete enough for an agent to invoke the tool correctly. The optional 'full' usage is covered, and return-value details are presumably handled by the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the 'detail' parameter, so the description carries the full burden of explaining it. It directly references the enum values 'summary' and 'full' and provides a decision rule for choosing between them. It does not define what each detail level returns, but it adds meaningful guidance beyond the raw enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Inspect') and a concrete resource ('installed AgentFEM runtime and approved roots'), which clearly distinguishes it from sibling tools like inspect_project. It is not a tautology and gives an agent enough specificity to know what the tool operates on.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit invocation guidance: 'Use summary first; request full only when selecting an advanced capability.' This provides clear context for how to use the tool, including the default behavior emphasis, though it does not explicitly contrast this tool with sibling alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read the structured scientific result for a completed job or the project's latest run, including its trust state.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| detail | No | summary | |
| job_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior, so the description's job is lighter. It adds meaningful context by specifying what is read: the structured scientific result and the trust state. There is no contradiction with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler. It front-loads the key action, then clarifies the scope and adds the trust-state detail. Every part contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description plus annotations and output schema cover the overall read operation well, but the zero parameter description coverage leaves ambiguity around path and detail. There is also no explicit routing guidance versus get_run_status, so the context is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description needs to compensate for what the schema omits. It does not explain path, detail, or job_id, and only loosely maps 'completed job or latest run' to the job-related parameters. The detail enum is left entirely unannotated in prose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and object: 'Read the structured scientific result' for a completed job or the project's latest run. It also includes the useful extra of the trust state. It does not explicitly contrast itself with get_run_status, but the object is distinct enough to avoid obvious confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for a completed job or the project's latest run' gives clear contextual guidance about when the tool is appropriate. It does not name alternatives or state explicit exclusions, but the context is strong enough for an agent to understand the basic trigger condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read one submitted run's status and any AgentFEM execution evidence currently available.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| job_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it returns 'any AgentFEM execution evidence currently available,' which hints at partial/streaming results, but doesn't elaborate on what 'currently available' means or how status values behave.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is concise and front-loaded with the core action. It earns its place by adding the 'AgentFEM execution evidence' detail, though it could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and annotations covering safety, the description is adequate for a simple read operation. However, with 0% parameter coverage and no guidance on how to identify a run, an agent may still be uncertain about what values to pass for 'path' and 'job_id'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'one submitted run' but does not explain that 'path' and 'job_id' are required to identify the run, nor does it clarify their roles or format. The description adds minimal meaning beyond the schema's bare property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Read') and resource ('one submitted run's status'), and adds the AgentFEM execution evidence detail. It is clear enough to distinguish from siblings like submit_run or get_result_summary, though it doesn't explicitly name a sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for reading status of a single run, which is a clear context. However, it doesn't explicitly state when to use this versus get_result_summary or inspect_project, nor does it mention any exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read project validation and recent immutable run identities without modifying the project.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint, idempotentHint, and destructiveHint=false, so the description's 'without modifying' is redundant with structured data. It adds some useful scoping by naming validation results and 'recent immutable run identities,' but it does not describe return behavior or edge cases beyond that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one tight sentence, starts with the action verb, and contains no filler or repetition beyond the annotation-aligned safety note. Every word contributes to understanding what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only tool with strong annotations and an output schema, the description conveys the essential purpose and scoping. The main gaps are the unexplained path parameter and the lack of explicit sibling differentiation, but the tool's low complexity keeps these gaps modest.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage for the sole parameter, and the description never explains what 'path' should point to or what format is expected. The word 'project' is the only hint, which is too weak to help an agent correctly populate the path parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete verb and resources: 'Read project validation and recent immutable run identities.' This clearly distinguishes it from mutating siblings like create_project or submit_run and identifies what the agent will get back. 'Without modifying the project' further pins down its read-only role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies a read-only inspection use case, but it never explicitly says when to choose this tool over siblings such as describe_system or get_run_status. It gives no exclusions or alternative routing, so usage context is only inferred from wording rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
After preflight, start a finite-element run in a separate process and return a durable job identity immediately.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | agent | |
| path | Yes | ||
| mpi_ranks | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal that the tool is not read-only and not idempotent, and the description adds useful behavioral context: the run happens in a separate process, returns immediately, and yields a durable job identity. This effectively communicates the async, stateful nature of the operation, though lifecycle or resource implications are not covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, tight sentence that front-loads the action and includes the two most important behavioral facts: separate-process execution and immediate durable job identity. There is no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with three parameters and several siblings, the description leaves important gaps: parameter meanings are absent, alternative tools are not routed, and the purpose of the returned job identity (e.g., for use with get_run_status) is unstated. The output schema may cover the return shape, but the calling context remains under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no parameter semantics. An agent cannot determine what `path` should point to, what `name` controls, or how `mpi_ranks` affects the run from the text alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a concrete verb ('start') and resource ('finite-element run'), and adds valuable detail about asynchronous execution and the immediate return of a durable job identity. It distinguishes this submit action from sibling status/result tools, though it does not name alternatives explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'After preflight' provides an ordering precondition that implies the tool should be used after validation. However, it does not mention sibling alternatives or state when not to use this tool, leaving the usage guidance implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run fail-closed structural and compatibility checks without solving the project.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already establish read-only, idempotent and non-destructive behavior, so the description need not repeat those. It adds value by disclosing that the checks are 'fail-closed and that the tool does not solve the project, revealing expected scope and outcome behavior beyond the structured metadata.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with no filler: it front-loads the main purpose, states the check type, and adds the key limitation in the same clause. Every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with read-only annotations and an output schema, the description covers the tool's scope well enough to call correctly. It does not spell out return values, but the output schema covers that. It could be stronger by naming inspect_project as the alternative, but nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema gives only a title ('Path' plus type for the required path parameter, at 0% coverage, so the description must compensate and does not mention path or explain what it should point to. The single parameter is intuitive from the name, but the description adds no semantic meaning beyond the bare schema title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('run') and a resource ('project'), and says the checks are 'structural and compatibility' plus 'fail-closed', which makes its role fairly clear. It does not explicitly name a sibling it differs from, but 'without solving the project' separates it from submit_run and suggests a pre-solve validation role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Without solving the project' implies that the tool is intended for validation before computation, but there is no explicit statement of when to use validate_project over inspect_project or submit_run. It offers slight contextual guidance, no exclusions, but no alternative-selection rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0create_projectdescribe_systemget_result_summaryget_run_statusinspect_projectsubmit_runvalidate_projectScored across 7 tools
Each tool addresses a distinct phase: system description, project creation, validation, inspection, run submission, status retrieval, and result summary. No overlap in purposes, making tool selection unambiguous.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., describe_system, create_project, submit_run). The naming convention is uniform and predictable.
Seven tools is well-scoped for a finite-element analysis server, covering the essential lifecycle without redundancy or bloat. Each tool earns its place.
The core workflow is covered: system inspection, project creation, validation, run submission, status checking, and result retrieval. Minor gaps like project updates or deletion exist but are not critical to the main simulation flow.
One MCP tool for verified AI-agent outcomes with success-only charging.
Stateless agentic tools over MCP: concept extraction, long-context, knowledge graph, planning.
Free public MCP for AI agents — 193 tools, 44 workflows. No API key.
Open scientific and engineering knowledge for AI agents: search, evidence, document publishing.
