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.

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 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