MCP Integration for OpenConstructionERP
Why MCP
MCP (Model Context Protocol) is the 2026 standard for giving AI assistants tools. Wrapping OpenConstructionERP's REST API in an MCP server turns the assistant from a chat partner into an operator: it can load a cost base, search items, build a BOQ and read validation results itself.
What to expose (start with these)
| MCP tool |
Underlying API |
Notes |
list_cost_bases |
GET /api/v1/costs/base-catalog |
families, variants, positions, loaded badge |
load_cost_base |
POST /api/v1/costs/load-cwicr/{db_id} |
idempotent, returns imported/skipped |
search_cost_items |
GET /api/v1/costs/?region=...&q=... |
SQL path, works without Qdrant |
get_cost_item |
GET /api/v1/costs/{id} |
full components[] + classification |
category_tree |
GET /api/v1/costs/category-tree/?region=... |
browsing |
suggest_for_element |
POST /api/v1/costs/suggest-for-element |
BIM element → cost ranking |
create_boq / validate_boq |
POST /api/v1/boqs, /boqs/{id}/validate/ |
estimating |
import_catalog |
POST /api/v1/catalog/import/{region} |
resource catalog |
Reference implementation (TypeScript, fast)
// mcp-server: FastMCP wrapper around the ERP's FastAPI backend
import { FastMCP } from "fastmcp";
const ERP = process.env.OPENESTIMATE_URL ?? "http://localhost:8000";
const server = new FastMCP({ name: "openconstructionerp" });
server.addTool({
name: "load_cost_base",
description: "Load a CWICR cost base (e.g. TR_NATIONAL, ZH_CHINA) into the ERP.",
parameters: { db_id: { type: "string", required: true } },
execute: async ({ db_id }) => {
const r = await fetch(`${ERP}/api/v1/costs/load-cwicr/${db_id}`, {
method: "POST",
headers: { Authorization: `Bearer ${process.env.ERP_TOKEN}` },
});
return await r.json();
},
});
server.addTool({
name: "search_cost_items",
description: "Search cost items in a region by keyword.",
parameters: { region: { type: "string" }, q: { type: "string" } },
execute: async ({ region, q }) => {
const r = await fetch(`${ERP}/api/v1/costs/?region=${region}&q=${encodeURIComponent(q)}&limit=20`,
{ headers: { Authorization: `Bearer ${process.env.ERP_TOKEN}` } });
return await r.json();
},
});
server.start({ transportType: "stdio" });
Auth & safety
- Reuse the ERP's JWT (register a service account; bootstrap admin only for setup).
- MCP tools must be idempotent and read-mostly:
load_cost_base returns already_loaded on repeat.
- Never expose raw credentials in tool descriptions; use env vars (
ERP_TOKEN).
- Rate-limit write tools; the ERP already enforces
api_rate_limit (200/min default).
Best practices
- Start read-only (browse/search), add writes (BOQ create, link) after testing.
- Wrap long operations (BIM conversion) in a progress-tool pattern instead of blocking.
- Log every assistant action server-side (the platform's usage ledger pattern).
- Publish the MCP server to the assistant marketplace (Claude Code registry, Antigravity, OpenCode).
1---2name: oce-mcp-integration3description: Connect OpenConstructionERP to AI coding assistants via MCP (Model Context Protocol): expose costs, BOQ, BIM and catalog endpoints as MCP tools so Claude Code / Antigravity / OpenCode can drive the platform. Use when wiring an assistant to the ERP.4---5
6# MCP Integration for OpenConstructionERP
7
8## Why MCP
9
10MCP (Model Context Protocol) is the 2026 standard for giving AI assistants tools. Wrapping OpenConstructionERP's REST API in an MCP server turns the assistant from a chat partner into an operator: it can load a cost base, search items, build a BOQ and read validation results itself.
11
12## What to expose (start with these)
13
14| MCP tool | Underlying API | Notes |
15|---|---|---|
16| `list_cost_bases` | `GET /api/v1/costs/base-catalog` | families, variants, positions, loaded badge |
17| `load_cost_base` | `POST /api/v1/costs/load-cwicr/{db_id}` | idempotent, returns imported/skipped |
18| `search_cost_items` | `GET /api/v1/costs/?region=...&q=...` | SQL path, works without Qdrant |
19| `get_cost_item` | `GET /api/v1/costs/{id}` | full components[] + classification |
20| `category_tree` | `GET /api/v1/costs/category-tree/?region=...` | browsing |
21| `suggest_for_element` | `POST /api/v1/costs/suggest-for-element` | BIM element → cost ranking |
22| `create_boq` / `validate_boq` | `POST /api/v1/boqs`, `/boqs/{id}/validate/` | estimating |
23| `import_catalog` | `POST /api/v1/catalog/import/{region}` | resource catalog |
24
25## Reference implementation (TypeScript, fast)
26
27```typescript
28// mcp-server: FastMCP wrapper around the ERP's FastAPI backend
29import { FastMCP } from "fastmcp";
30
31const ERP = process.env.OPENESTIMATE_URL ?? "http://localhost:8000";
32const server = new FastMCP({ name: "openconstructionerp" });
33
34server.addTool({
35 name: "load_cost_base",
36 description: "Load a CWICR cost base (e.g. TR_NATIONAL, ZH_CHINA) into the ERP.",
37 parameters: { db_id: { type: "string", required: true } },
38 execute: async ({ db_id }) => {
39 const r = await fetch(`${ERP}/api/v1/costs/load-cwicr/${db_id}`, {
40 method: "POST",
41 headers: { Authorization: `Bearer ${process.env.ERP_TOKEN}` },
42 });
43 return await r.json();
44 },
45});
46
47server.addTool({
48 name: "search_cost_items",
49 description: "Search cost items in a region by keyword.",
50 parameters: { region: { type: "string" }, q: { type: "string" } },
51 execute: async ({ region, q }) => {
52 const r = await fetch(`${ERP}/api/v1/costs/?region=${region}&q=${encodeURIComponent(q)}&limit=20`,
53 { headers: { Authorization: `Bearer ${process.env.ERP_TOKEN}` } });
54 return await r.json();
55 },
56});
57
58server.start({ transportType: "stdio" });
59```
60
61## Auth & safety
62
63- Reuse the ERP's JWT (register a service account; bootstrap admin only for setup).
64- MCP tools must be idempotent and read-mostly: `load_cost_base` returns `already_loaded` on repeat.
65- Never expose raw credentials in tool descriptions; use env vars (`ERP_TOKEN`).
66- Rate-limit write tools; the ERP already enforces `api_rate_limit` (200/min default).
67
68## Best practices
69
701. Start read-only (browse/search), add writes (BOQ create, link) after testing.
712. Wrap long operations (BIM conversion) in a progress-tool pattern instead of blocking.
723. Log every assistant action server-side (the platform's usage ledger pattern).
734. Publish the MCP server to the assistant marketplace (Claude Code registry, Antigravity, OpenCode).
gabrielmoreira