HR System MCP Server

A Model Context Protocol (MCP) server that exposes a mock HR system to LLM clients (Claude Desktop, Claude Code, custom agents). Ships with in-memory seed data so you can start experimenting without wiring up a real HRIS.

Capabilities

Group	Module	What it does
Leave & Attendance	capabilities/leave.py	Balances, applications, attendance records, holiday calendar
Benefits & Compensation	capabilities/benefits.py	Compensation summary, benefits catalog, payslips, tax declarations
Employee Lifecycle	capabilities/lifecycle.py	Profiles, onboarding, offboarding, internal transfers
Learning & Development	capabilities/learning.py	Course catalog, enrollment, learning history, recommendations
Performance Management	capabilities/performance.py	Review cycles, goals, self-assessments
Travel & Expense	capabilities/travel.py	Travel policy, expense submission and status
HR Policy Search	capabilities/policy.py	Full-text search over policy corpus + summarization
HR FAQ	capabilities/faq.py	FAQ catalog + search

All eight groups share a single FastMCP instance and are served together.

Requirements

• Python 3.10+
• pip / uv

Install

pip install -e .

Run

python run.py

You should see:

INFO: Uvicorn running on http://127.0.0.1:8765

The MCP endpoint is http://127.0.0.1:8765/mcp (streamable HTTP transport).

Configure via env vars (see .env.example):

• HR_MCP_HOST (default 0.0.0.0)
• HR_MCP_PORT (default 8765; PORT is honored first for PaaS hosts)
• HR_MCP_LOG_LEVEL (default INFO)
• HR_MCP_AUTH_TOKEN — when set, every request to /mcp must include Authorization: Bearer <token>. /healthz is always open.
• HR_MCP_ALLOWED_HOSTS — comma-separated Host headers FastMCP will accept (DNS-rebinding protection). Required on any public deployment (e.g. hr-mcp.onrender.com). Symptom if missing: Error POSTing to endpoint: Invalid Host header / HTTP 421.

Try it with the MCP Inspector

npx @modelcontextprotocol/inspector

Choose transport Streamable HTTP and URL http://127.0.0.1:8765/mcp. You should see ~30 tools grouped by capability.

Register with Claude Desktop / Claude Code

Local, no auth:

{
  "mcpServers": {
    "hr-system": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Remote (Render), with bearer token:

{
  "mcpServers": {
    "hr-system": {
      "url": "https://hr-mcp.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN_FROM_RENDER"
      }
    }
  }
}

Then ask things like:

• "What's the leave balance for employee E001?"
• "Search HR policies for maternity leave and summarize the top match."
• "Show me the payslip for E002 for March 2026."

Deploy to Render (free tier)

The repo ships with render.yaml — a Render Blueprint that provisions everything.

1. Push to a new GitHub repo

git init
git add .
git commit -m "Initial commit: HR MCP server"

# Create the empty repo on GitHub first (via the website or `gh repo create`),
# then push
git remote add origin https://github.com/<your-user>/hr-mcp.git
git branch -M main
git push -u origin main

2. Provision on Render

1. Sign in at https://dashboard.render.com.
2. New → Blueprint → connect your GitHub account → pick the hr-mcp repo.
3. Render reads render.yaml, previews the service, and asks you to confirm. Click Apply.
4. First deploy takes ~2–3 minutes. When the service goes green, note its URL: https://hr-mcp-<hash>.onrender.com.
5. Open the service → Environment tab → copy the auto-generated HR_MCP_AUTH_TOKEN value. That's your bearer token.

3. Try it

# Health check (no auth needed)
curl https://hr-mcp-<hash>.onrender.com/healthz
# → ok

# MCP endpoint (401 without token, works with)
curl -H "Authorization: Bearer $HR_MCP_AUTH_TOKEN" \
     https://hr-mcp-<hash>.onrender.com/mcp

Point the MCP Inspector at https://hr-mcp-<hash>.onrender.com/mcp and set a custom header Authorization: Bearer <token> in the Inspector's connection settings.

4. Notes on the free plan

• Instances spin down after 15 minutes of idle. First request after a nap has a ~30 s cold start. For a personal demo this is fine; upgrade to the Starter tier ($7/mo) if you need always-on.
• 750 free instance-hours per month across all your Render services.
• /healthz is exempt from auth so Render's health prober keeps working.

Seed data

The server seeds ~10 employees (E001–E010), a set of policies, courses, benefits, holidays, and FAQs at startup. All data lives in memory — restarting resets state. Swap src/hr_mcp/data/store.py for a real backend when you're ready.

Structure

src/hr_mcp/
├── __main__.py            # CLI entrypoint
├── server.py              # FastMCP wiring
├── config.py              # env-var settings
├── data/
│   ├── models.py          # Pydantic models
│   ├── store.py           # in-memory store
│   └── seed.py            # sample data
└── capabilities/          # one module per capability group