hr_server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hr_serverMaya Rodriguez wants to work from Portugal for six weeks, 5 October to 15 November. Can she?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Helios HR Assistant
An agentic HR assistant for the fictional Helios Dynamics: policy retrieval, synthetic employee records, deterministic compliance checks, and reversible mock actions, all accessed through a real Model Context Protocol (MCP) server.
Application: https://helios-hr-assistant-wz3c.onrender.com
Readiness: https://helios-hr-assistant-wz3c.onrender.com/health
Design and evaluation: design-and-evaluation.md
Deployment: deployed.md
AI tooling disclosure: ai-tooling.md
/health.build_sha reports the commit currently deployed.
The free instance sleeps when idle, so the first visit can take about a minute while it wakes. See Cold starts and expected waits.
At a glance
16 policy documents in Markdown, HTML, PDF and TXT, indexed into 221 chunks.
12 MCP tools covering policy search, employee records, compliance rules and mock actions.
30 evaluation cases and two canonical demo workflows.
Live evaluation scores recorded in September are historical: the older citation metric measured retrieved-label presence rather than factual support. See the design report for the current scoring method and results.
Related MCP server: HR Assist MCP Server
Setup
Use Python 3.12+. From the repository directory:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
Copy-Item .env.example .envOn macOS/Linux, activate with source .venv/bin/activate and copy the template
using cp .env.example .env.
Set GROQ_API_KEY in .env or the host environment. A Groq tool-capable model
is required for multi-step workflows. Gemini's configured compatibility endpoint
is only available for non-tool calls; it is not a replacement for Groq here.
Never commit API keys, demo codes, or approval secrets.
Direct dependencies are pinned in pyproject.toml; transitive dependencies are
not locked.
Run
uvicorn app.main:app --reload --port 8000Open http://127.0.0.1:8000. The app starts and discovers the MCP subprocess. All dates are evaluated against the clearly labelled 2026-09-12 synthetic snapshot, not today's date. This prevents the example answers drifting.
Endpoint | Purpose |
| Chat with demo task buttons, cited source snippets, mock-action previews and an execution trace (answer basis, tool calls, arguments, outputs) |
| Process liveness; no LLM call |
| Configured dependencies, tool count, index, revision and local quota limits; no LLM call |
| Discovered MCP catalogue |
| Indexed corpus |
| Reproducible UI tasks |
| Message, optional user/assistant history, and optional |
| Execute the exact stored mock preview, once, in its originating browser session; zero LLM calls |
/health checks configuration, not whether a provider key is valid or has quota.
Only a live chat can establish that. The UI shows cached results explicitly;
their trace/timings belong to the original run.
API quota protection
Unit/integration tests use scripted models and prohibit real chat-completion calls. Indexing and retrieval evaluation use the local embedding model, not an LLM API.
Live evaluation and deployed-task scripts require explicit
--allow-live.The app admits one chat at a time and rejects duplicate/concurrent submissions. The default hourly chat allowance is 12 requests.
Provider requests are capped at 8 per turn, 60 per hour and 100 per day by default. The deployed service allows 16 per turn and 16 agent steps, because demo runs on a fallback model can need more steps. A request the provider refuses before doing any work (rate limit, oversized request, retired model) costs no tokens and is refunded; anything it may have processed counts.
A rate-limited model is passed over for the next model in the chain, which has its own per-minute budget. A call waits only when every model is rate-limited, for the soonest to recover (honouring
Retry-After, at most 60 s per call). Longer limits are reported, not waited out. Retired models are skipped.Read-only identical requests within the same session/context may reuse a labelled 10-minute cache. Mutating workflows and ticket listings are not cached. Run live (skip cache) bypasses the cache and uses quota.
Set
DEMO_ACCESS_CODEto protect a public deployment from casual quota consumption. Share it privately; users enter it in the Demo access code field, not the chat.Set
LLM_ENABLED=falseto disable all real model calls. Chat explicitly reports that calls are disabled; it does not fake an answer.
These are process-local application limits, not provider quota readings. They reset on restart and cannot protect against other applications using the same API key. Provider daily limits, and per-minute limits that outlast the wait, can still interrupt a task.
The two demo workflows
The canonical prompts live in agent/demo_tasks.py and are reused by the UI
and deployed verifier:
International remote work: Maya's 42-day Portugal request; read her rolling usage, check compliance, read POL-INTL-001 §2 The 30-Day Rule and POL-REMOTE-001 §6 Temporary Work Outside the Home Country, and explain, citing both, that 12 + 42 exceeds 30 by 24 days.
PTO and ticket preview: Jonas's three-day request; check 13 available hours against 24 requested and 6 days' notice against 10, read POL-PTO-001 §3.1 Notice Requirements and §3.3 Insufficient Balance, show a mock ticket preview, and explain the manager/skip-level exception routes. Select Create mock ticket on the preview to create the in-memory ticket and show its ID.
Every policy claim, including alternatives, needs evidence. A preview is not a completed write, and a tool call alone is not a correct answer.
Offline checks
pytest -q
ruff check .
python scripts/validate_mock_data.py
python scripts/check_rules.py
python scripts/healthcheck.py
python -m rag.ingest.build_index --check
python -m evaluation.run_retrieval_evalThe committed index avoids embedding downloads at application startup. When ingestion code or policies change, rebuild locally:
python -m rag.ingest.build_indexThe embedding weights must already be cached for fully offline execution.
Live evaluation (opt-in)
These commands make real LLM calls and consume quota:
python -m evaluation.run_eval --allow-live --case C01
python -m evaluation.run_eval --allow-live --resume
python scripts/verify_deployed_tasks.py --allow-live --task pto --confirm-mock-actionsThe last command performs a real agent turn and then explicitly authorizes the
mock ticket. It saves the complete response and confirmation result in evidence/
with each run's wall time, rate-limit waits, model calls and tokens. --task and
--case can be repeated, and the run stops at the first provider or HTTP error
rather than spending quota on requests that would fail the same way.
Current evaluation records contain scorer version, configuration/code fingerprint
and full traces. A checkpoint from another revision is rejected.
Architecture
Browser -> FastAPI -> agent orchestrator -> LLM provider
|
MCP client
| stdio JSON-RPC
MCP server
/ \
local RAG index synthetic HR records + rule engineThe folder is called mcp_server/, not mcp/, to avoid shadowing the SDK package.
All employee data is synthetic; tickets and email drafts disappear on restart.
Deployment
The live service runs on Render Free as one Docker service with one worker. The
web app, agent, local vector index, synthetic data and stdio MCP server share the
container; only the LLM is external. GitHub Actions checks the code, the real MCP
transport, app startup and the container, then deploys that exact commit.
render.yaml disables Render's own auto-deploy, so only revisions that pass CI are deployed.
To deploy your own copy:
Fork the repository and create a Render Blueprint from
render.yaml. Render builds theDockerfile, which bakes the embedding model into the image, and the app listens on Render's$PORT.In the Render dashboard, set
GROQ_API_KEY.GEMINI_API_KEYandDEMO_ACCESS_CODEare optional;render.yamlsupplies the other settings.In GitHub, add the secret
RENDER_API_KEYand the repository variablesRENDER_SERVICE_ID(thesrv-…ID) andAPP_URL(the service URL).Push to
main. CI runs lint, tests, the MCP smoke test and the container check, triggers the Render deploy for that commit, and waits until/healthreports it.
To run the production image locally with the settings from .env:
docker build -t helios-hr .
docker run --rm -p 8000:8000 --env-file .env helios-hrdeployed.md lists every environment variable and the demo steps.
Cold starts and expected waits
Render's free plan puts the service to sleep after about 15 minutes without
traffic, and the next request has to wake it. The measured cold start was
52.5 seconds, so allow about a minute. Before a demo, open /healthz and wait
for it to respond; neither health endpoint calls an LLM.
A multi-step agent task is slower than a single answer even when the service is
warm, because each model step waits for the provider's per-minute token budget.
On 3 October 2026, eight back-to-back requests to the deployed service took a
median of 15 seconds and at most 47 seconds. Sent about a minute apart, the two
demo tasks on build c88530a took 7 and 5 seconds;
design-and-evaluation.md
has the details.
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted MCP endpoint with realistic fake data for prototyping agents. 12 tools, no setup.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
# **RChilli MCP Hub** RChilli MCP Hub is a production-grade MCP server that exposes RChilli's full HR data intelligence platform as 17 AI-callable tools across 4 categories. Built on 15+ years of HR data intelligence, it is trusted by ATS vendors, HR technology platforms, staffing agencies, and enterprise recruiting teams worldwide. Every tool is read-only and returns a consistent, structured JSON response — no raw exceptions, no inconsistent formats. <br> --- <br> # **Tools — 17 Total** userkey and subuserid are injected automatically from your Bearer token — you never need to pass them manually. <br> --- <br> # **🔍 Resume & Job Description Parsing — 3 tools** <br> > ### **`extract_resume_data`** > > Extracts and converts resumes, CVs, and candidate documents into structured, searchable profiles with contact details, skills, experience, education, certifications, and taxonomy-enriched data for ATS, HCM, and AI recruiting workflows. When used on a careers page or application form, the same extraction call auto-fills every application field in under 10 seconds — documented to increase candidate conversion by up to 194%. Supports 40+ languages with English-normalized output for global intake, and runs in batch mode to process legacy databases or migration backlogs overnight at scale. Also supports resume reprocessing — re-running previously extracted resumes through the latest extraction logic and taxonomy version to bring older records up to current data quality, without requiring a new document from the candidate. Distinct from bulk import (first-time extraction of a new batch) and from talent data refresh (re-enrichment from a newer submitted resume). <br> > ### **`extract_resume_data_from_url`** > > Accepts a direct URL to a PDF, DOCX, or RTF file and returns the same normalized JSON profile as the Resume Data Extraction tool. Ideal for pipeline automation where resumes are stored in cloud storage, S3, or email attachments. Also supports the same auto-fill, multilingual, and batch-processing capabilities as the core extraction tool for URL-based intake sources. <br> > ### **`extract_job_data`** > > Extracts and converts job descriptions into structured hiring data including job title, required skills, preferred skills, responsibilities, experience, education, and taxonomy-normalized role requirements for recruitment automation and candidate matching. <br> --- <br> # **🧠 Skills & Job Taxonomy — 4 tools** <br> > ### **`lookup_skill`** > > Returns authoritative detail for a known skill including description, all aliases, related skills, proficiency levels, and O*NET/ESCO mappings. Use when you need the complete record rather than a ranked search. <br> > ### **`lookup_job_profile`** > > Returns authoritative detail for a known job profile including canonical title, SOC/O*NET code, job family, typical required and preferred skills, salary bands, and work context. <br> > ### **`autocomplete_skill`** > > Accepts a partial skill string (min 2 chars) and returns up to 10 ranked autocomplete suggestions with canonical names and categories. Prevents free-text entry errors and keeps skill data clean at point of entry. <br> > ### **`autocomplete_job_profile`** > > Accepts a partial job title string and returns ranked autocomplete suggestions with canonical titles and job families. Ensures job titles map to taxonomy profiles from the moment a recruiter starts typing. <br> --- <br> # **🛡️ Redaction, Documents & Utilities — 7 tools** <br> > ### **`redact_resume`** > > Redacts personally identifiable information from candidate profiles to support anonymized review, bias-aware screening, compliance workflows, and audit logs. Configurable redaction scope. Idempotent. <br> > ### **`reformat_resume_with_template`** > > RChilli's Resume Reformatting tool accepts any structured candidate profile and applies one of six branded templates (TM001–TM006) to produce a consistently formatted output document in PDF, DOCX, RTF, or HTML — ensuring every candidate is presented in a standardized, professional layout regardless of how their original resume was structured. Designed for staffing firms, recruitment agencies, and enterprise HR teams who need to control candidate presentation at scale, it eliminates manual reformatting effort and enforces brand consistency across all submissions. <br> > ### **`convert_document_format`** > > Accepts a document as base64 or URL and converts between PDF, DOCX, RTF, HTML, and plain text. Preserves formatting fidelity. Useful as a pre-processing step before data extraction on non-standard file types. <br> > ### **`tag_entities`** > > RChilli's Named Entity Recognition tool takes already-extracted HR text and annotates it by wrapping each recognized entity in a structured XML-style label inline — returning output such as `<job_title>Senior Data Engineer</job_title>`, `<skill>Python</skill>`, `<city>Austin</city>`, `<degree>Bachelor of Science</degree>`, and `<organization>Google</organization>` — covering 10+ HR-specific entity types including person name, state, country, date, and year. Unlike data extraction tools that produce separate field lists, tag_entities preserves the full original text structure with entities labeled in place, making the output immediately consumable by ATS field-mapping pipelines, candidate profile builders, and content annotation workflows without any offset calculation or post-processing. <br> > ### **`extract_contacts`** > > Identifies and structures names, emails, phone numbers, LinkedIn URLs, and addresses with field-level confidence scores from candidate records, emails, or documents. Safe for GDPR/CCPA workflows. <br> > ### **`geolocate`** > > Converts partial or informal location text into structured city, state, country, ISO codes, latitude, and longitude. Enables radius-based candidate and job search and supports workforce planning analytics. <br> > ### **`classify_job_zone`** > > RChilli's Job Zone Classification tool reads the job profile from a resume or job description and returns its O/*NET Job Zone — one of five standardized levels ranging from Zone 1 (little or no preparation required) through Zone 2 (some preparation), Zone 3 (medium preparation), Zone 4 (considerable preparation), to Zone 5 (extensive preparation required) — based on the education, experience, and training criteria defined by O/*NET. The returned Job Zone level enables downstream workflows such as candidate-to-role fit filtering, compensation benchmarking, over/under-qualification flagging, and job architecture standardization without any manual O/*NET lookup. <br> --- <br> # **🎯 Search & Matching — 3 tools** <br> > ### **`score_resume_against_jd`** > > Accepts one resume and one Job Description (no index required) and returns an overall match score, dimension scores, skill gap list, and natural-language explanation. Bias-controlled and audit-ready. <br> > ### **`find_matches_in_index`** > > Accepts a resume or Job Description as input and returns the top-N most similar documents from the indexed corpus ranked by semantic similarity. No index setup required for the input document. <br> > ### **`search_indexed_documents`** > > Accepts a query string and returns ranked document references from the tenant's pre-populated index. Supports Boolean and semantic search modes. Requires documents to be indexed before use.
CareerProof MCP gives AI agents direct access to a professional-grade career and workforce intelligence platform. Two namespaces: atlas_* for HR/TA teams (candidate evaluation, batch shortlisting, competency scoring, interview generation, JD analysis, custom eval frameworks, research reports) and ceevee_* for professionals (CV optimization, career positioning, salary intelligence, market reports). Backed by RAG knowledge from 50+ premium research sources (McKinsey, BCG, HBR, Gartner, WEF)
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP server exposing employee info retrieval and web search tools, designed to be consumed by a LangChain agent for decoupled tool execution.-
- FlicenseCqualityCmaintenanceAgentic HR assistant providing employee, leave, meeting, ticket, and email tools over the Model Context Protocol, designed to automate onboarding workflows via an MCP client such as Claude Desktop.14-
- FlicenseNot gradedqualityCmaintenanceExposes travel planning data and constraint checking as MCP tools over stdio, enabling AI agents to query reference information and evaluate plan validity.-
- FlicenseNot gradedqualityCmaintenanceAn MCP server exposing internal business operations as tools — task management (create, list, update status) and RAG-style semantic search over an internal knowledge base (leave, expense, and onboarding policies) that any MCP-compatible AI agent can call directly for grounded, non-hallucinated answers.-