mcp-erp-server

A reference Model Context Protocol server that lets an AI assistant (Claude, ChatGPT, Claude Code, any MCP client) work with a small business's ERP safely: customers, appointments, invoices and bills.

It runs against an in-memory mock ERP with synthetic data, so you can clone it and try it in a minute. The interesting part is not the mock, it is everything around it: how to expose real business data and write operations to a language model without handing it the keys.

This is a cleaned-up, generic version of patterns I use in production MCP servers for a dental clinic (appointments, receivables, payables). No real data, names or credentials are in this repository.

What it demonstrates

Related MCP server: tessera-mcp

Quick start

git clone https://github.com/mateusmeloc/mcp-erp-server.git
cd mcp-erp-server
npm install
cp .env.example .env     # demo values only; see "Configuration"
set -a; . ./.env; set +a
npm run dev              # http://localhost:3000

Check it is alive and that it asks for credentials:

curl -s localhost:3000/healthz
curl -si -X POST localhost:3000/mcp | head -n 3     # 401 + WWW-Authenticate

Then talk to it with the demo admin key from .env.example:

curl -s localhost:3000/mcp \
  -H "Authorization: Bearer change-me-demo-admin-token-0001" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Or point the MCP Inspector at http://localhost:3000/mcp.

npm test          # 40 tests, no network needed
npm run typecheck
npm run build && npm start

Tools

Roles

admin is the only open-ended role. The others are closed lists, so a family added tomorrow is invisible to them until someone grants it deliberately.

How a write works

 model ──► appointment_book(customer_id, staff, start)  ──► PREVIEW: "Book a <service> for Alex Rivera
                                                           (C-001) with <staff> on <start>, 30 minutes."
                                                           + confirmation_token   (nothing changed)
 human sees the preview and approves
 model ──► appointment_book(same args, confirm=true,
                            confirmation_token=…)      ──► executed (token consumed, audited)

The token is HMAC-signed and carries a hash of tool | person | canonical(args), an expiry and a unique id. So the model cannot skip the preview, cannot run something different from what the human saw (any changed argument invalidates it), cannot use someone else's token, and cannot replay an old approval. State is revalidated at execution time, because the calendar may have changed between preview and confirm.

The order inside runWrite is fixed, in one place, so the guardrails cannot drift apart between tools: kill switch, rate limit, revalidate, preview or consume token, run, audit.

Connecting a client

The server exposes one endpoint, POST /mcp, plus the OAuth endpoints. Deploy it behind HTTPS (OAuth redirects and bearer tokens must never travel in clear text) and set PUBLIC_URL to the public address.

• Claude / ChatGPT (custom connector): add https://your-host/mcp as a remote MCP server. The client discovers the OAuth metadata, registers itself, and sends the person to the consent page, which asks for their own access key (the token from ERP_USERS). The consent page names the client and the host it will redirect to.

• Claude Code: claude mcp add --transport http erp https://your-host/mcp --header "Authorization: Bearer <access key>"

• Scripts: send Authorization: Bearer <access key> directly.

Configuration

Everything comes from environment variables and is validated at boot; a bad configuration stops the process with a clear message instead of running half-configured. See .env.example.

With NODE_ENV=production the server refuses to start if any credential contains the demo marker change-me.

Revoking access: remove the person from ERP_USERS and restart. Roles are read from the current configuration on every request, not from the token, so the change takes effect immediately for OAuth tokens too. Rotating TOKEN_SECRET revokes every issued token at once.

Project layout

src/
  app.ts            Express app: /mcp (stateless), /healthz, error handling
  config.ts         Env parsing and validation (fails loudly at boot)
  auth/             roles, signed tokens, identity, OAuth 2.1 server + consent page
  erp/              the mock ERP (types, store with deterministic seed data, privacy masking)
  mcp/              server factory, write pipeline, confirmations, audit
    tools/          one file per family
test/               unit, tool-level (real MCP client) and HTTP/OAuth end-to-end tests

To use it with a real system, replace src/erp/store.ts with a client for your ERP and keep the tool layer, roles and write pipeline as they are.

Limits you should know about

This is a reference implementation, not a turnkey product. Honest list:

• Single instance. Rate limiters, OAuth authorization codes, registered clients and the single-use ledger of confirmation tokens live in memory. Behind several replicas, or across restarts, they are not shared (a restart invalidates pending previews and codes, which fails safe). Move them to Redis or a database before scaling out.

• Refresh tokens are not one-time. A new pair is issued on every refresh, but the server is stateless, so the previous refresh token stays valid until it expires. Strict rotation needs a store.

• Dynamic client registration is open, as DCR is by design, so it is treated as untrusted: redirect URIs must be https or loopback and are matched exactly, codes are single use and bound to client + redirect URI + PKCE, and nothing is granted without a valid access key. If you need stricter control, add an allow-list of clients.

• Access keys are shared secrets, not an identity provider. For a team, put this behind your SSO or replace auth/identity.ts.

• The data is fake. Money is USD, times are UTC, the business is a generic service shop.

License

MIT