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.

How disconnects are detected (and the honest limitation)

The Connector Store shows a Claude/ChatGPT card as Connected only while this server vouches for it. Three paths take a card down; know which one you are relying on:

1. Client-initiated revocation — instant, but NOT guaranteed. This server implements RFC 7009: it advertises revocation_endpoint in its OAuth metadata and serves POST /revoke. A client that calls it on disconnect gets the exact session invalidated and one status:"disconnected" report sent within seconds. However: nothing obliges claude.ai to call it. Anthropic's connector documentation specifies no signal of any kind on connector removal, the MCP authorization spec does not reference RFC 7009 at all (clients are neither required nor recommended to revoke on disconnect), and in production claude.ai has been observed removing a connector silently. Whether claude.ai caches the OAuth metadata per connector (so a later-added revocation endpoint is only picked up after remove + re-add) is also undocumented. Treat instant detection as best-effort, never as a guarantee.

2. Dashboard Disconnect — instant and always available. Clicking Disconnect on the Store card takes effect immediately and sticks: heartbeats and check-status never resurrect it; only a fresh sign-in (reconnect: true) does. This is the reliable way to take a card down now.

3. Dormancy fallback — guaranteed, within the activity window. lastSeen advances only on genuine authenticated MCP requests. A session with no traffic for CONNECTOR_ACTIVE_WINDOW_MS (default 1 hour) goes dormant: one status:"disconnected" report is sent and heartbeats stop, so a silent claude.ai removal shows as Disconnected within roughly the window plus one heartbeat (~65 minutes at defaults). A dormant session that speaks again reports back the moment it wakes. Shortening the window makes silent removals surface faster, but marks genuinely-connected-but-idle users Disconnected between uses — they reconnect automatically on their next request, at the cost of the card flapping. 1 hour is the compromise.

There is no fourth option: when the client sends nothing and the user clicks nothing, absence of traffic is the only signal, and it is indistinguishable from idleness until the window expires.

References: Anthropic remote-MCP connector docs · MCP authorization spec · RFC 7009

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.