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

Copy .env.example to get started:

cp .env.example .env

Available Tools

Health Checks

Geographic Data

Reference Data

User Management

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