Skip to main content
Glama
jaskaran-ai

HR Solx MCP Server

by jaskaran-ai
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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.

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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jaskaran-ai/hr-solx-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server