Innergy MCP Gateway

A production-oriented, read-only remote Model Context Protocol (MCP) server that lets ChatGPT retrieve selected Innergy project, budget, work-order, finance, inventory, labor, scheduling, and added-expense data without exposing the Innergy API key.

Safety model

• The public MCP transport is served at POST/GET/DELETE /mcp.

• The MCP transport accepts either an Auth0 RS256 access token or the existing static Bearer token fallback.

• The safe operational health check is GET /health.

• Every MCP tool is annotated as read-only, non-destructive, and idempotent.

• No create, update, or delete Innergy route is registered.

• The Innergy key is read from the server environment only and is sent upstream in the documented Api-Key request header.

• Secrets and authorization headers are redacted from server logs.

• Browser and MCP responses never include the API key or base URL.

• Normal responses are projected into concise records. debug: true returns a redacted, size-limited upstream payload.

Related MCP server: Merlin Project MCP Extension

Architecture

ChatGPT ── Streamable HTTP MCP ──> /mcp
                                      │
                                      ├── tool validation and read-only policy
                                      ├── concise response projection
                                      └── modular Innergy API client
                                                │
                                                └── Api-Key header ──> Innergy

Browser ──> / ──> deployment/health dashboard
Browser ──> /health ──> safe configuration and capability status

The React app is a monitoring and connection-information surface. All credentials and Innergy requests remain in the Node.js API service.

Confirmed Innergy API contract

The following GET routes were confirmed from the supplied Innergy OpenAPI 3.0.1 document:

The gateway exposes 45 curated MCP tools, all mapped to GET operations confirmed in the supplied OpenAPI document. No undocumented Innergy route is called. Search, workflow summaries, schedules, exception analysis, joinery grouping, and expense project filtering are performed locally when the confirmed upstream endpoint does not provide that capability.

OpenAPI GET catalog

At build time the supplied v2 OpenAPI document is copied as an immutable dist-relative asset. Server startup fails if that asset is missing, invalid, or does not contain the expected 219 GET operations. The primary generic tools are search_endpoints, describe_endpoint, query_endpoint, and count_endpoint. They only resolve catalog GET templates; URLs, hosts, and mutation operations are never accepted. Generic grids validate documented path/query values and fields, use skip/take pages of at most 500, and scan all natural pages when local list filtering, text search, fetch-all, or exact counting is required. Results remain windowed (default 100) with total/count/paging metadata, while selected raw schema fields are preserved.

get_project_work_orders is v2-first. It uses the specification-defined GET /api/v2-unstable/project-management/work-orders grid operation with skip, take (maximum 500 per upstream request), requireTotalCount=true, encoded filter conditions, encoded sort objects, and a fixed select projection containing only fields needed for concise MCP work-order results. It supports project UUIDs through projectIds; project sequence identifiers through the schema-defined ProjectSequenceIdentifier grid field; Status values Open and Closed; the documented WorkOrderType values Sales, Drafting, Production, and Installation; the documented WorkflowPhaseType values Opportunity, Drafting, Production, and Installation; workFlowStepId; and exact WorkflowStepName filtering. countOnly uses a one-field WorkOrderId projection, while summaryBy=Status or summaryBy=WorkOrderType uses server-side total-count queries without downloading complete work-order rows.

Because API v2 is explicitly marked unstable, a failed v2 grid request automatically falls back to the existing read-only GET /api/projects/{id}/workOrders implementation. Responses disclose whether v2-unstable or v1-fallback supplied the data. The fallback endpoint remains unpaginated and is filtered locally where possible.

The v2 operation documents these required permissions: ProjectManagement → Project → WorkOrder → View, ProjectManagement → ProductionWorkOrders → View, ProjectManagement → InstallationWorkOrders → View, ProjectManagement → DraftingWorkOrders → View, and ShopFloor → WorkOrders → View.

get_project_work_orders also accepts exact type, query, and includeSummary compatibility inputs. type is a compatibility alias for the documented workOrderType query value; status and step use native grid predicates. query uses documented text matching on the Name and SequenceIdentifier LinkDto fields. Tags is a ListDto, whose OpenAPI contract does not document a grid-filter value shape, so a requested tag is exact-matched locally only after the v2 response and is disclosed in filters. get_work_order_summary returns exact named total/Open/Closed/type breakdowns and workflow-step counts rather than work-order rows. It uses narrow projections and server total-count queries; projectId is optional except for an exact coordinator display-name match. The upstream grid has no coordinator parameter, so coordinator matching is explicitly local and exact (for example, Aaron Clarke cannot match Aaron Ashworth) and requires a project ID to keep that scan bounded.

Additional v2 grids

The gateway also uses the v2 grid contract (encoded filters, fixed projections, take <= 500, and requireTotalCount) for projects, shop drawings and drawing publish logs, purchase orders and purchase-order line items, shipment items, project time tracking, library materials, and material associations. get_projects is v2-first and retains the v1 /api/projects fallback only for unavailable/malformed/not-found v2 responses—not 400, 401, or 403. get_my_projects uses only documented employeeId plus employeeType (SalesPerson, Estimator, or ProjectManager); it has no coordinator parameter or default-person lookup.

get_project_slippage calls the documented dashboard slippage grid. That operation does not have a projectId parameter, so the tool cannot claim a project-specific server-side query. get_project_labour projects activity, duration, employee, project, work-order, and labor-item fields only; no compensation or pay fields are selected. search_innergy intentionally searches only the efficiently server-filterable implemented project and material name grids.

Project coordination tools

Exception thresholds are returned with every response: approaching means within seven days, an unchanged workflow step is flagged at 14 days, and actual hours are considered materially over plan above 20%. These are transparent analysis thresholds, not invented Innergy workflow meanings.

Replit configuration

Set these in Replit Secrets/environment variables:

INNERGY_BASE_URL must use HTTP or HTTPS. HTTPS is strongly recommended outside local development.

Local usage

The managed Replit workflows provide ports and routing. Start:

pnpm --filter @workspace/api-server run dev
pnpm --filter @workspace/innergy-mcp run dev

Useful checks through Replit's shared preview routing:

curl -sS https://$REPLIT_DEV_DOMAIN/health
curl -i -X POST https://$REPLIT_DEV_DOMAIN/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"smoke-test","version":"1.0.0"}}}'

Use the returned mcp-session-id header for tools/list and tools/call.

Deployment and final MCP URL

Publish the Replit project after the health and MCP checks pass. The final connector URL is:

https://<your-published-replit-domain>/mcp

Do not use the temporary .replit.dev preview domain as the final ChatGPT connector URL.

Connect to ChatGPT Developer Mode

Current OpenAI guidance supports remote MCP servers over Streamable HTTP:

1. Publish this project and copy its published /mcp URL.

2. In ChatGPT on the web, open Settings → Security and login and enable Developer mode. Workspace-managed accounts may instead expose the setting under workspace permissions.

3. Open ChatGPT Plugins, select the plus button, and create a developer-mode app.

4. Enter the published MCP URL ending in /mcp.

5. Choose OAuth. ChatGPT discovers Auth0 through the MCP protected-resource metadata and requests the innergy.read scope.

6. Save the app and enable it from the Developer mode tool picker in a conversation.

7. Review and approve tool calls as appropriate for your ChatGPT account or workspace policy.

Example prompts:

• “Show me the work orders for Brunswick.”

• “What projects have incomplete work orders?”

• “Show me added expenses for project X.”

• “Find project number 12345.”

• “Show project 12345’s schedule of values and job-costing summary.”

• “List open purchase orders and invoice draws for project 12345.”

• “Which materials are requested for work order WO-100?”

• “Show labor Kanban items for project 12345.”

ChatGPT can combine search_projects with get_project_work_orders when a prompt identifies a project by name rather than by Innergy sequence ID.

Error behavior

Tools return concise JSON error objects with stable codes:

• not_configured

• invalid_request

• invalid_auth

• forbidden

• not_found

• rate_limited

• malformed_response

• response_too_large

• upstream_timeout

• upstream_unavailable

• upstream_error

Upstream response bodies are not copied into errors, preventing accidental disclosure of sensitive provider details.

If the bearer token is lost, replace MCP_AUTH_TOKEN in Replit Secrets and update the ChatGPT app configuration with the new token.

Auth0 OAuth resource-server configuration

This gateway is an OAuth protected resource, not an OAuth login application. ChatGPT is the OAuth client and Auth0 is the authorization server, so the gateway does not expose a local /callback or login route and does not need an Auth0 client secret.

Public protected-resource metadata is available at:

GET /.well-known/oauth-protected-resource
GET /.well-known/oauth-protected-resource/mcp

Auth0 access tokens must be signed with RS256 and match:

Issuer:   https://dev-scza6vay6a66c87e.au.auth0.com/
Audience: https://repulsive-nimble-editor.replit.app/mcp
Scope:    innergy.read

The existing MCP_AUTH_TOKEN remains accepted as a temporary fallback. Authorization headers and token values are never logged.

Verify the deployed metadata:

curl -i https://repulsive-nimble-editor.replit.app/.well-known/oauth-protected-resource/mcp

Verify the unauthenticated discovery challenge:

curl -i -X POST https://repulsive-nimble-editor.replit.app/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"oauth-check","version":"1.0.0"}}}'