AJEMS MCP Connector

Lets Claude and ChatGPT answer questions about an AJEMS workspace — and optionally create apps, forms and records — without anyone logging into AJEMS.

One deployment serves every tenant. Users sign in with their organisation name and AJEMS secret key.

Files

Related MCP server: BackCrew ServiceM8 MCP Server

Quick start

npm install
cp .env.example .env      # set PUBLIC_URL and AJEMS_HOST_TEMPLATE
npm start

Verify against a real workspace:

node diagnose.js https://mcp.ajems.com <organisation> <secret-key>

Or try it with no AJEMS at all:

npm run mock              # terminal 1
# set AJEMS_HOST_TEMPLATE=http://localhost:9090/{org}/json_builder
npm start                 # terminal 2
node diagnose.js http://localhost:8080 testco test-secret-key

See DEPLOY.md for nginx, TLS, pm2 and tuning.

Tools

Read-only by default. Set ALLOW_WRITES=true for the four write tools.

Read-only by default. Set ALLOW_WRITES=true for the six write tools.

Two rules the tools follow

Never make the model count. Every list carries an explicit total, placed first in the response. Models that summarise long lists return numbers that drift between identical questions; count_records exists so a "how many" question never depends on counting an array.

No write happens without confirm: true. The first call returns a preview and a warning instead of writing. For update_record the preview shows current values next to the new ones. This is enforced in the tool, not left to the model's judgement.

summarise_records computes on the server. Without it, "total by city" would pull thousands of rows into the model's context and add them by hand — slow, expensive, and wrong past a certain size.

search and fetch keep those exact names because outside Developer Mode, ChatGPT only calls tools named search and fetch and ignores everything else.

How a question gets answered

Claude asks "how many entries in July, by city?":

1. list_apps_and_forms → finds the form

2. show_form_fields → learns that date_1750943312417 is the date field and dropdown_1750943301432 holds cities

3. summarise_records with a date range and group_by → gets three numbers back

4. Writes the answer in plain English

Field keys are auto-generated (date_1750943312417), which is why step 2 is not optional. The tool descriptions tell the model this, and it chains the calls itself.

Tenant isolation

• Tenant comes from the session, resolved server-side from the bearer token

• No tool schema has a tenant, org or url parameter — nothing exists for a model to be talked into changing

• ajems.js is the only module issuing outbound requests, and only to that tenant's base URL

• Cache keys are namespaced by tenant and a hash of the secret key, so tenants can't read each other's cached entries and a rotated key self-expires

• Organisation names are stripped to subdomain-safe characters, so an entry like evil.com/x can't redirect the server elsewhere

• Every tool call is logged as JSON with tenant and user

When adding a tool, re-check the second point.

Testing

27 checks pass against the mock covering the tool layer: all 13 tools present with correct annotations, explicit totals, filtered counts, the confirmation gate blocking and then allowing every write, before/after previews, and search totals. An earlier suite covers authentication, tenant isolation, 20 concurrent users and rate limiting.