How it works

Every endpoint key owns a complete, isolated HRIS. There is no authentication because the key is the tenant, and there is nothing real behind it.

Per-endpoint documentation lives on the endpoint. This page describes the architecture. For the actual data dictionary of a specific company — every table, column, type and row count — open https://hr-safe-space.cheek.org/i/<key>/docs.

The addressing model

An endpoint is /i/<key>/mcp where the key is 4–64 characters of lowercase letters, digits and single hyphens. The first request to a key provisions it. Every request afterwards resolves the same company: the same name, the same roster size, the same people.

Because the key selects the dataset and nothing else does, an unshared key behaves like an unlisted URL. Keys are not secrets and the records behind them are synthetic, so nothing is protected by obscurity that would matter if it were not.

One template, many companies

Copying 50,000–425,000 employee rows per instance would mean millions of rows per tenant and billions across a few thousand tenants. No single Postgres survives that, so the roster is not copied.

A master template holds the worker records once. An instance is a deterministic projection over a prefix of that template, re-parameterised by its own row: a different company name and domain, a different roster size, a different department and location mix, a different pay multiplier, a different date offset, and rotated name pools so the same template row surfaces as a different person.

The reporting tree is pure arithmetic on a worker’s position in the roster, which is what makes a prefix safe to take: a manager’s position is always lower than their reports’, so truncating the roster never orphans anyone.

Provisioning is one INSERT. A 425,000-person company appears in milliseconds and occupies one row until something is written to it.

Writes are copy-on-write

16 of the 52 tools change data. Each writes a diff — a patch, a new row, or a tombstone — into that instance’s private overlay. Reads merge the overlay over the projection: tombstones removed, patches applied, created rows unioned in.

The shared template is immutable at runtime. A write through one key is structurally incapable of appearing under another, and every write lands in that instance’s audit log.

Every call is logged, not just the writes

The audit log answers “what is different now”. It cannot answer “what did my agent do”, because an agent that reads twenty tables and writes nothing leaves no trace in it. So every JSON-RPC message an endpoint receives is recorded separately: the method, the tool, the arguments it was called with, whether it wrote, whether it failed, and how long it took.

That log is at /i/<key>/activity, newest first. It is written by the server rather than by whatever is driving the agent, which makes it an independent account of a run: a figure in an agent’s output with no call behind it here did not come from the data. It keeps the most recent 1,000 calls per key; writes are also in the audit log, which is never pruned and is readable back through list_recent_changes.

What is in the schema

21 entities covering the HRIS surface: worker records and the org chart, compensation and its history, payroll and payslips, time off and balances, performance reviews and goals, benefits, learning and compliance training, recruiting requisitions and candidates, and employee-relations cases with their notes.

Entity	Origin	Writable	Description
employee	template projection	yes	The worker record.
compensation_event	template projection	yes	Historical pay changes: merit increases, promotions, market adjustments and retention awards.
time_off_request	template projection	yes	Absence requests across every leave type, from submitted through approved, denied or taken.
performance_review	template projection	yes	Completed review-cycle records with rating, potential, calibration state and written feedback.
goal	template projection	yes	Individual objectives with weighting, progress and status.
benefit_enrollment	template projection	yes	Which employees are enrolled in which benefit plans, with employee and employer cost.
training_record	template projection	yes	Assigned and completed learning, including mandatory compliance training and its renewal state.
hr_case	template projection	yes	Employee-relations matters: conduct concerns, grievances, accommodation requests, safety reports and ethics-hotline intake, with severity, SLA and assignment.
hr_case_note	template projection	yes	Chronological notes recorded against an employee-relations case.
job_requisition	template projection	yes	Open and historical hiring requisitions with hiring manager, recruiter, target and fill state.
candidate	template projection	yes	Applicants against requisitions, with source, pipeline stage, rating and expected compensation.
payslip	derived	no	Per-period earnings, taxes and deductions.
time_off_balance	derived	no	Accrued, taken and available leave per employee per leave type.
audit_log	overlay	no	Every write any MCP tool has performed against this instance, in order.
department	reference	no	Department catalogue.
location	reference	no	Work locations with timezone, currency and cost-of-living index.
job	reference	no	Job catalogue: every department and level combination with its title, FLSA status and pay band.
benefit_plan	reference	no	Benefit plan catalogue with carrier, tier, cost split, deductible and eligibility waiting period.
training_course	reference	no	Learning catalogue, including which courses are mandatory and how often they must be renewed.
policy_document	reference	no	HR policy library.
payroll_run	template projection	no	The payroll calendar: two years of semi-monthly periods with status and totals.

The tool surface

Directory & org

Tool	Kind	Purpose
search_employees	read	Search the worker directory by name, email, job title or id, with optional filters on department, location, status, employment type, manager, career level, hire date and performance rating.
get_employee	read	Full worker record for one employee: identity, contact details, job and level, department, location, reporting line, employment status and dates, demographics and compensation.
list_direct_reports	read	Everyone who reports directly to a given manager.
get_reporting_chain	read	The full management chain from an employee up to the CEO, one row per level.
get_org_snapshot	read	Shape of the whole organisation: roster size, active headcount, management layers with the population and span of control at each, and the largest departments and locations.
list_departments	read	Department catalogue with headcount, active headcount, average base pay and the most senior leader.
list_locations	read	Work locations with country, timezone, currency, cost-of-living index and headcount.
get_headcount_summary	read	Headcount grouped by any one of department, location, country, career level, employment type, work arrangement or status, with active counts and average base pay per group.

Compensation

Tool	Kind	Purpose
get_compensation_detail	read	Current pay for one employee: base salary, currency, bonus target, equity, compa-ratio and where they sit in the pay band for their job and level.
list_compensation_history	read	Pay changes over time: merit increases, promotions, market adjustments and retention awards.
submit_compensation_change	write	Change an employee's base salary.
get_pay_band_analysis	read	Compensation distribution by career level for a department or the whole company: population, minimum, average and maximum base pay, average compa-ratio, and how many people sit outside the 0.
list_payroll_runs	read	The payroll calendar: pay periods, pay dates, status and totals.
get_payslips	read	Payslips for one employee: gross, base and bonus earnings, tax and benefit deductions, and net pay for each pay period.

Time off

Tool	Kind	Purpose
get_time_off_balances	read	Accrued, taken, scheduled and available days for every leave type for one employee, derived from tenure, the accrual policy and approved absences.
list_time_off_requests	read	Absence requests filtered by employee, status, leave type or date range.
submit_time_off_request	write	Submit a time off request on behalf of an employee.
decide_time_off_request	write	Approve, deny or cancel a pending time off request.
get_absence_summary	read	Absence volume by leave type and status across the company or one department, with total days requested.

Performance

Tool	Kind	Purpose
list_performance_reviews	read	Completed reviews with rating, potential, calibration state and promotion readiness.
get_performance_review	read	One review in full, including written strengths, growth areas and narrative summary.
submit_performance_review	write	Record a performance review for an employee in the current cycle.
list_goals	read	Individual objectives with weighting, progress and status.
update_goal_progress	write	Update how far along a goal is, and optionally its status.

Recruiting

Tool	Kind	Purpose
list_job_requisitions	read	Hiring requisitions with status, priority, openings, hiring manager and age.
get_job_requisition	read	One requisition in full, with its candidate pipeline broken down by stage.
open_job_requisition	write	Open a new hiring requisition.
list_candidates	read	Applicants with source, pipeline stage, rating and days in pipeline.
advance_candidate	write	Move a candidate to a new pipeline stage, for example from screen to interview, or to offer.
get_recruiting_funnel	read	Candidate volume by pipeline stage and source, plus open requisition counts, so you can see where the funnel narrows and which channels are producing.

Lifecycle

Tool	Kind	Purpose
transfer_employee	write	Move an employee to a different department, location or manager.
promote_employee	write	Promote an employee to a higher level, with an optional pay increase.
record_termination	write	Record that an employee is leaving the organisation.
onboard_employee	write	Add a new hire to the roster, with their job, department, location, manager and start date.

Benefits & learning

Tool	Kind	Purpose
list_benefit_plans	read	Benefit plan catalogue with carrier, tier, employee and employer cost, deductible and enrollment counts.
get_benefit_enrollments	read	Which plans an employee is enrolled in, with cost split and effective dates.
enroll_in_benefit	write	Enroll an employee in a benefit plan.
list_training_courses	read	Learning catalogue with category, delivery mode, duration, mandatory flag and renewal cadence.
get_training_transcript	read	An employee's learning history with completion status, scores and certification expiry.
assign_training	write	Assign a course to an employee.

Employee relations

Tool	Kind	Purpose
list_hr_cases	read	Employee-relations matters with type, severity, status, assignment, SLA due date and whether the SLA has been breached.
get_hr_case	read	One case in full, with its chronological notes.
open_hr_case	write	Open an employee-relations case: a conduct concern, grievance, accommodation request, safety report or policy question.
add_case_note	write	Record a note against an employee-relations case.
resolve_hr_case	write	Move a case forward: investigating, pending review, resolved or closed.

Analytics

Tool	Kind	Purpose
get_attrition_report	read	Leavers broken down by reason and whether the departure was voluntary, with attrition rate against the current roster, optionally scoped to a department.
get_diversity_report	read	Representation by gender or ethnicity, optionally cut by career level, so you can see how representation changes as seniority increases.
get_compliance_training_status	read	Completion state for mandatory compliance training, by course, with the number overdue.
search_policies	read	Search the HR policy library and return full policy text, so a question about leave, pay, conduct or accommodations can be answered from source rather than paraphrased.
list_recent_changes	read	Everything any MCP tool has written to this instance, newest first.

Reference

Tool	Kind	Purpose
describe_hris_schema	read	The complete data dictionary for this endpoint: every entity, every column with its type and meaning, row counts for this instance, and which tools read or write each one.
get_instance_info	read	What this endpoint is: the company it represents, its roster size, when it was provisioned, how many writes it has taken, and where to browse or document it.

Connecting

claude mcp add --transport http acme https://hr-safe-space.cheek.org/i/acme-demo-4821/mcp

Or as JSON, for any client that speaks Streamable HTTP:

{
  "mcpServers": {
    "acme": {
      "type": "http",
      "url": "https://hr-safe-space.cheek.org/i/acme-demo-4821/mcp"
    }
  }
}

Limits worth knowing

Roster size is drawn once per key and never changes.
A single tool call returns at most 200 rows; page with offset.
Payslips and leave balances are computed on demand and are therefore read-only.
Payroll run totals are reported against the current active roster rather than recomputed per historical period, which would mean 48 full passes over the roster for a 48-row table.
Every record is fictional. Do not use any of it as if it described a real person.