Skip to main content
Glama
jaskaran-ai

HR Solx MCP Server

by jaskaran-ai

HR Solx MCP Server

A Model Context Protocol (MCP) server that exposes HR API endpoints as AI-accessible tools. Built with Express.js and the official MCP SDK.

What It Does

This server acts as a bridge between AI models (Claude, GPT, etc.) and the HR Solx REST API. AI clients can discover and invoke tools through the MCP protocol, enabling natural language interactions with HR data like users, countries, skills, roles, and more.

Related MCP server: MCP Employee API Server

Features

  • 12 MCP Tools — Health checks, geographic data, reference data, and user management

  • Streamable HTTP Transport — Stateless JSON-RPC 2.0 communication

  • TypeScript — Full type safety with Zod validation

  • Modular Architecture — Organized codebase with separated concerns

  • Authentication — API key protection for MCP endpoint

  • Rate Limiting — IP-based request throttling

  • Error Handling — Typed errors with contextual messages

System Architecture

graph LR
    AI["AI Client\n(Claude, GPT)"] -->|"POST /mcp\nJSON-RPC 2.0"| Express["Express Server\n(MCP Protocol)"]
    Express -->|"fetch"| API["HR API\napi.hr-solx-mobile.com"]
    API -->|"JSON Response"| Express
    Express -->|"SSE Stream"| AI

    subgraph Middleware
        Express
    end

    classDef ai fill:#e1f5fe,stroke:#01579b
    classDef server fill:#fff3e0,stroke:#e65100
    classDef api fill:#e8f5e9,stroke:#2e7d32
    class AI ai
    class Express server
    class API api

Quick Start

npm install
npm run dev

Server runs at http://localhost:4000/mcp

Environment Variables

Variable

Default

Description

MCP_SERVER_PORT

4000

Server listening port

MCP_API_URL

https://api.hr-solx-mobile.com

Upstream HR API URL

MCP_API_KEY

API key to protect MCP endpoint

API_TOKEN

Bearer token for upstream API auth

RATE_LIMIT_WINDOW_MS

900000

Rate limit window (15 min)

RATE_LIMIT_MAX_REQUESTS

100

Max requests per window

Copy .env.example to get started:

cp .env.example .env

Available Tools

Health Checks

Tool

Description

basic-health-check

Check if API is reachable

detailed-health-check

Comprehensive system health

Geographic Data

Tool

Description

get-countries

List all countries

get-states

List all states

get-cities

List all cities

Reference Data

Tool

Description

get-skills

List available skills

get-languages

List available languages

get-working-statuses

List working statuses

get-roles

List available roles

User Management

Tool

Description

Params

get-users

List all users

create-user

Create a new user

name, email, mobile

Usage Examples

List Available Tools

curl -X POST http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

Call a Tool

curl -X POST http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "get-users",
      "arguments": {}
    },
    "id": 1
  }'

Create a User

curl -X POST http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "create-user",
      "arguments": {
        "name": "John Doe",
        "email": "john@example.com",
        "mobile": "+1234567890"
      }
    },
    "id": 1
  }'

With Authentication

curl -X POST http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-API-Key: your-api-key" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'

Project Structure

├── docs/                          # Detailed documentation
│   ├── ARCHITECTURE.md            # System architecture & design
│   ├── MCP-PROTOCOL.md            # MCP protocol guide
│   ├── TOOLS-REFERENCE.md         # Complete tool catalog
│   ├── DEVELOPER-GUIDE.md         # How to extend & test
│   ├── SECURITY.md                # Security considerations
│   ├── TROUBLESHOOTING.md         # Common issues & fixes
│   └── REQUEST-FLOW.md            # Request lifecycle
├── src/
│   ├── index.ts                   # Server entry point
│   ├── types/
│   │   ├── api.ts                 # API response interfaces
│   │   └── errors.ts              # Custom error types
│   ├── client/
│   │   └── api-client.ts          # Upstream API client
│   ├── tools/
│   │   ├── echo.ts                # Echo tool/resource/prompt
│   │   ├── health.ts              # Health check tools
│   │   ├── reference.ts           # Reference data tools
│   │   └── users.ts               # User management tools
│   └── middleware/
│       ├── auth.ts                # API key authentication
│       └── rate-limit.ts          # Rate limiting
├── .env.example                   # Environment template
├── package.json
└── tsconfig.json

Module Dependencies

graph TD
    Index["src/index.ts\n(Server Entry)"] --> Types["src/types/\n(api.ts, errors.ts)"]
    Index --> Client["src/client/\n(api-client.ts)"]
    Index --> Tools["src/tools/\n(echo, health, reference, users)"]
    Index --> Middleware["src/middleware/\n(auth, rate-limit)"]
    Tools --> Client
    Tools --> Types
    Client --> Types

    classDef entry fill:#fff3e0,stroke:#e65100
    classDef module fill:#e3f2fd,stroke:#1565c0
    class Index entry
    class Types,Client,Tools,Middleware module

See docs/ARCHITECTURE.md for full details.

Adding New Tools

  1. Define the TypeScript interface in src/types/api.ts

  2. Register the tool in the appropriate module under src/tools/

  3. Import and register in src/index.ts

See docs/DEVELOPER-GUIDE.md for step-by-step instructions.

Security

The server supports two layers of authentication:

  • MCP endpoint — Protected via X-API-Key header (MCP_API_KEY)

  • Upstream API — Authenticated via Bearer token (API_TOKEN)

See docs/SECURITY.md for full security guide and production checklist.

Troubleshooting

Common issues and solutions are documented in docs/TROUBLESHOOTING.md.

Quick checks:

# Verify server is running
curl http://localhost:4000/mcp

# Test upstream API
curl https://api.hr-solx-mobile.com/health

# Check environment variables
echo $MCP_API_URL
echo $MCP_SERVER_PORT

License

MIT

Related MCP Connectors

  • AI-callable tools for API mocking, testing, monitoring, security, and automation.

  • Query professional profiles, search candidates, and get AI-powered summaries and job fit analysis.

  • # **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.

  • Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.

Related MCP Servers

  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to interact with BambooHR's API through natural language queries. Provides access to employee data, time off management, company files, and HR operations with comprehensive tools for workforce management.
    108 npm
    1
    MIT
  • F
    license
    Not graded
    quality
    D
    maintenance
    Provides 50+ tools for interacting with Rippling's HR platform, including employee management, payroll, time tracking, benefits, recruiting, learning, devices, groups, and custom objects, all through natural language.
    -
  • F
    license
    B
    quality
    D
    maintenance
    Enables AI assistants to interact with the HRD-PIS API for HR profile management, including authentication and various HR operations.
    16
    -