Work Journal MCP Server

A hosted MCP server that lets any member of the team read their Simplified HR Work Journal through Claude — their own entries always, and colleagues' entries where their existing Work Journal permissions already allow.

Read-only. No tool here can create, change, or delete an entry.

Connecting, from any Claude client

One flow, whichever client you use: add the server by URL, then sign in in the browser window that opens.

Claude Desktop or claude.ai — Settings → Connectors → Add custom connector →

https://wj-mcp.dev.besimplified.net/mcp

Claude Code

claude mcp add work-journal --transport http https://wj-mcp.dev.besimplified.net/mcp

Either way a browser window opens. Sign in with your Simplified HR email and password. On dev you also enter your workspace, for example development-hr.dev.besimplified.net.

If this is a device the accounts service has not seen before, you are sent a verification code by email or SMS. Enter it once; you will not be asked again from the same client.

Your password never reaches Claude, and this server never stores it.

Signing in at the accounts service instead

WJ_LOGIN_MODE=redirect replaces the form above. /authorize sends the browser to the accounts sign-in page for the environment, the member signs in there, and the accounts service returns them to /identifier with a short-lived handoff token that this server exchanges for the session. Two things follow: no password is typed into a page this server renders, and the member is signed in to the BeSimplified web apps at the same time, because the session is the one the accounts service minted on its own origin.

It is off by default because it has prerequisites the form mode does not:

• An app_registrations record in the accounts service naming this server's host, as a verified fqdn or as a workspace, on every organisation whose members use it. The sign-in page takes the host out of the referrer it is given and looks it up; with no record it answers valid_workspace: false and returns the browser to the HR app rather than here. This is a record in the accounts service's own database — no code there changes.

• WJ_PUBLIC_BASE_URL as https with no port. The accounts service rebuilds the callback as https://<host>/identifier from the hostname alone, so a port or a plaintext scheme cannot receive it. The server refuses to start otherwise, rather than serving a login that can begin and never finish.

• Read access to the accounts session store, WJ_REDIS_HOST and WJ_ACC_CACHE_PREFIX. The handoff token names a key there; without it there is nothing to exchange the token for.

The callback host is checked against an allowlist in both modes. It matters more here: once the member authenticates at the accounts service, whoever named redirect_uri receives the authorization code, and PKCE does not help against an attacker who started the flow.

Related MCP server: mcp-infra-readonly

Tools

work_journal_get_entries

Entries with full task detail for a date or a range of up to 31 days.

Ask: "show my EOD entries for last week"

work_journal_get_day

One date in full: every task with notes and attachments, notified recipients, ETA, and submission time.

Ask: "what did I log on 4 August?"

work_journal_get_summary

Counts by type and status over any period, with no per-day detail. Use this for anything longer than 31 days.

Ask: "how many EOW reports did I miss this year?"

work_journal_find_member

Finds a colleague by part of their name or email and returns their member id, for use as member on the tools above.

Ask: "find Rahul's member id"

work_journal_get_team_report

One row per member with submitted, pending, and missed counts for a period.

Ask: "who missed their EOD last week?"

Type aliases

Matching ignores case and treats spaces, hyphens, and underscores as equivalent.

Who can see whose journal

This server enforces no permissions of its own. Every request carries your own Simplified HR session, and the Work Journal API applies exactly the permissions it applies in the web UI:

• Instance permission — you can read any member of your company

• Group permission — you can read members in your reporting subtree

• Neither — you can read only your own journal, and any attempt at another member's is refused

Two things to know when reading a colleague's entries: the request can be refused outright, and an admin view excludes drafts, scheduled, and private entries. An absent entry therefore does not prove nothing was logged.

Limits

• work_journal_get_entries rejects ranges longer than 31 days and points you at work_journal_get_summary

• At most 4 requests run concurrently per tool call, so a wide range stays gentle on the API

• Relative dates such as "last week" are resolved by Claude before the call; the tools accept YYYY-MM-DD only

Running it locally

npm install
cp .env.example .env      # then fill in the two secrets
WJ_ENV=dev \
WJ_PUBLIC_BASE_URL=http://localhost:8080 \
WJ_TOKEN_KEY=$(openssl rand -hex 32) \
WJ_FINGERPRINT_SECRET=$(openssl rand -hex 32) \
npm start

GET /healthz should answer {"status":"ok"}. Running node src/index.js with no environment must exit immediately, listing every missing variable.

Environment

WJ_FINGERPRINT_SECRET must be identical across every task, and must not be rotated casually. It derives each member's stable device fingerprint; changing it re-challenges the whole team with a verification code.

Deployment notes

• Cookie stickiness on /authorize is a WJ_LOGIN_MODE=form requirement only. In redirect mode nothing is held in process memory between the two legs — the authorization request rides back from the accounts service in an encrypted redirect_page token — so /authorize and /identifier are both stateless and need no stickiness.

• Cookie stickiness is required on /authorize only. An OTP submission must reach the task that began the login, because the in-progress login is held in that process's memory for five minutes. /mcp and /token are stateless and must not be sticky.

• Both secrets belong in SSM Parameter Store as SecureString, referenced from the task definition's secrets block — never as environment literals. Create them once per environment before the first deploy; nothing else in the platform uses the /hr/work-journal-mcp/ prefix, so they will not already exist:

  aws ssm put-parameter --type SecureString --name /hr/work-journal-mcp/<env>/token_key           --value "$(openssl rand -hex 32)"
  aws ssm put-parameter --type SecureString --name /hr/work-journal-mcp/<env>/fingerprint_secret  --value "$(openssl rand -hex 32)"

  ecsTaskExecutionRole needs ssm:GetParameters and kms:Decrypt on both, or the task fails at start with ResourceInitializationError, before any of this code runs.

• Production rejects the workspace login field that dev requires, so the login page hides it outside dev.

Security

• Passwords are never stored, never logged, and never returned to the browser in any form. They exist only in memory, for the seconds a login takes.

• Session state travels in an AES-256-GCM encrypted envelope that only this server can open. The Simplified HR JWT never reaches Claude or the model.

• Access, refresh, and authorization-code envelopes are cryptographically bound to their kind, so one cannot be spent as another.

• Login attempts are rate limited per email address.

• Every tool call is logged with the caller, the tool, and the member whose journal was read, so cross-member reads are auditable. Tokens and entry content are never logged.

Tests

npm test