EzzyBills code-generation MCP server

This TypeScript MCP server supplies ChatGPT with the EzzyBills developer contract needed to generate standalone applications. It is a read-only knowledge service: it does not call EzzyBills, access customer data, or perform approval actions at runtime.

Architecture

ChatGPT
   ↓
get_ezzybills_developer_spec
   ↓
EzzyBills API catalogue, authentication contract, schemas, ID rules,
and generation rules
   ↓
Generated application
   ↓
EzzyBills REST APIs

Generated applications run independently of MCP. When they require EzzyBills access, they authenticate through the Developer Portal credentials:

CLIENT_ID + CLIENT_SECRET
   ↓
POST /oauth/token
   ↓
Authorization: Bearer <token>
   ↓
EzzyBills REST APIs

The client secret belongs only in a generated application's backend environment. It must never be embedded in browser or React code.

Related MCP server: swagger-openapi-mcp

MCP capabilities

The server exposes one MCP tool:

get_ezzybills_developer_spec

It returns eleven structured sections:

• coreArchitecture — actors and default stack

• authContract — OAuth2 client-credentials, token lifecycle

• universalRules — rules for all generated applications

• contentSecurityRules — HTML sanitization, blob security, sandboxing

• actionRiskRules — READ_ONLY / WRITE / DESTRUCTIVE_OR_EXTERNAL classifications

• apiCatalogue — 9 verified endpoints including getPurchaseOrders3

• workflowRecipes — step-by-step recipes for common tasks

• applicationProfiles — optional UI blueprints (document-browser, approval-queue, etc.)

• idRules — parentDocumentId vs attachmentInvoiceId

• specificationGaps — items awaiting backend-developer verification

• generationRules — flat compatibility alias

The server also exposes one MCP resource:

ezzybills://docs/developer-spec

The resource serves docs/mcp_api_spec.md.

Requirements

• Node.js 20 or newer

• npm

The MCP server itself does not require EzzyBills account credentials.

Install and run

npm install
npm run dev

For a compiled production-style run:

npm run build
npm start

The default endpoint is:

http://127.0.0.1:3000/mcp

The health endpoint is:

http://127.0.0.1:3000/

Configuration

ALLOWED_HOSTS and ALLOWED_ORIGINS are comma-separated bare hostnames. Do not include a URL scheme or port.

Example production configuration:

HOST=0.0.0.0
PORT=3000
ALLOWED_HOSTS=mcp.ezzybills.com,<azure-container-app-hostname>

Configure ALLOWED_ORIGINS only when the connecting client sends an Origin header. Add the hostname actually used by that client.

Host and Origin validation protect request routing; they are not user authentication. If the developer specification is not intended to be public, protect /mcp with the authentication or private-ingress arrangement chosen for the deployment.

MCP Inspector

1. Start the server with npm run dev.

2. Select Streamable HTTP in MCP Inspector.

3. Connect to http://127.0.0.1:3000/mcp.

4. Confirm the single tool and resource listed above are available.

Docker

The multi-stage Dockerfile builds the TypeScript source, installs only production dependencies in the runtime image, and copies the Markdown specification required by the MCP resource.

docker build -t ezzybills-mcp .
docker run --rm -p 3000:3000 -e ALLOWED_HOSTS=localhost ezzybills-mcp

For Azure, set the production hostname in ALLOWED_HOSTS rather than using the local Docker value.

Scripts

Project layout

docs/mcp_api_spec.md
src/resources/ezzyBillsDeveloperResource.ts
src/tools/getEzzyBillsDeveloperSpec.ts
src/server.ts
src/httpConfig.ts
src/http.ts
test/developerSpec.test.ts
Dockerfile
.dockerignore

TestEzzyBillsMCP