HR System MCP Server

An unofficial prototype MCP server providing HR system functionality with Okta token validation. For evaluation and testing purposes only.

📚 Documentation

Complete documentation available in the docs/ folder:

• docs/RAILWAY_README.md - Deploy to Railway.com (3 steps) 🚀
• docs/DOCKER_QUICK_START.md - Run locally with Docker 🐳
• docs/README_INTEGRATION.md - Use the deployed server 🔌
• docs/CLAUDE.md - Developer guide & architecture 💻
• docs/INDEX.md - Complete documentation index 📖

Overview

The HR System MCP Server provides:

• ✅ Employee information lookup
• ✅ Employee directory listing
• ✅ Payroll information access
• ✅ Time-off request management
• ✅ Okta OAuth 2.0 token validation for all tool calls
• ✅ HTTP/NDJSON streaming support (FastMCP)
• ✅ Ready for Railway deployment 🚀

Authentication

This server validates Okta access tokens for all tool calls (except initialize):

• Token Source: Okta authorization server
• Validation: JWT signature, expiration, audience claims
• Authorization Header: Authorization: Bearer <access_token>

Quick Start

# Setup
cp env.example .env
# Edit .env with your Okta credentials

# Install dependencies
pip install -r requirements.txt

# Run in HTTP mode (for Okta MCP Adapter)
python main.py --http 8001

Configuration

.env (Environment Variables)

OKTA_DOMAIN=ijtestcustom.oktapreview.com
OKTA_AUTHORIZATION_SERVER_ID=auss2fth0mcIXHzVO1d7
OKTA_AUDIENCE=
OKTA_REQUIRED_SCOPES=
# When true (default), tools/list without auth returns 401. When false, allows unauthenticated tools/list (e.g. for gateway registration).
# PROTECTED_DISCOVERY=true

Available Tools

Tool	Description	Parameters
get_employee	Get employee by ID	employee_id: str
list_employees	List all employees	None
get_employee_payroll	Get payroll info	employee_id: str
get_time_off_requests	Get time-off requests	employee_id: str (optional)

Usage Examples

Direct via VS Code/Copilot

# Endpoint
http://localhost:8001/mcp

# Authorization
Authorization: Bearer <okta_access_token>

Via Okta MCP Adapter Gateway

# Gateway will:
# 1. Receive request from client
# 2. Validate Okta token
# 3. Forward to HR System MCP
# 4. Attach authorization header

Implementation Details

• Framework: FastMCP 3.0.0b1
• Server: Uvicorn (async HTTP)
• Protocol: MCP (Model Context Protocol) with NDJSON streaming
• Token Validation: JWKS-based JWT validation with signature verification
• Caching: JWKS keys cached with TTL

Request Flow

Client Request
    ↓
Authorization Header (Okta token)
    ↓
Initialize (no token needed)
    ↓
tools/list (validate token)
    ↓
tools/call (validate token)
    ↓
Response

🚀 Deployment Options

Vercel (Serverless) ⚡

Deploy as serverless function - automatic scaling, pay-per-use

• ✅ Best for: Sporadic usage, automatic scale-to-zero
• ✅ Free tier: 100GB bandwidth/month
• ⚠️ Constraint: 10-second timeout (free), 5-min (Pro)
• 📖 Guide: docs/VERCEL_README.md

Railway.com (Traditional Server) 🚂

Deploy as long-running server - always-on, unlimited timeout

• ✅ Best for: Constant traffic, persistent connections
• ✅ Free tier: 500 hours/month ($5/month after)
• ✅ No timeout: Unlimited request duration
• 📖 Guide: docs/RAILWAY_README.md

Docker (Local Development) 🐳

Run locally with Docker - full control, testing

• 📖 Guide: docs/DOCKER_QUICK_START.md

docker-compose up -d

Recommendation:

• Use Vercel for sporadic/unpredictable usage (cheaper, auto-scales)
• Use Railway for constant traffic or if you need long timeouts

Troubleshooting

See docs/RAILWAY_DEPLOYMENT.md for complete troubleshooting guide.

Quick fixes:

• Token validation fails: Verify OKTA_DOMAIN and OKTA_AUTHORIZATION_SERVER_ID in .env
• Port already in use: Change port in startup command: python main.py --http 8002
• Missing environment variables: Copy .env example and fill in values
• JWKS fetch error: Verify Okta domain and authorization server ID are correct

Project Structure

hr-mcp-server/
├── main.py                    # FastMCP server with HTTP handler
├── requirements.txt           # Python dependencies
├── Dockerfile                 # Docker container definition
├── docker-compose.yml         # Docker Compose configuration
├── railway.json               # Railway deployment config
├── deploy-railway.sh          # Deployment helper script
├── test_server.sh            # Server test script
├── auth/                      # Authentication module
│   ├── __init__.py
│   └── okta_validator.py     # Okta token validation
└── docs/                      # Documentation
    ├── INDEX.md              # Documentation index
    ├── RAILWAY_README.md     # Railway quick start
    ├── RAILWAY_DEPLOYMENT.md # Complete deployment guide
    ├── DOCKER_QUICK_START.md # Docker reference
    ├── README_INTEGRATION.md # Usage guide
    ├── CLAUDE_CODE_SETUP.md  # Claude Code setup
    ├── CLAUDE.md             # Developer documentation
    └── ...more docs

See docs/INDEX.md for complete documentation guide.

Testing

# Using curl with Okta token
curl -X POST http://localhost:8001/mcp \
  -H "Authorization: Bearer <your_okta_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

📖 Documentation

For complete documentation, see the docs/ folder:

• Getting Started - Documentation index
• Deploy to Railway - Cloud deployment guide
• Run with Docker - Local development
• Integration Guide - How to use the server
• Developer Guide - Architecture & development

References

• MCP Specification
• FastMCP Documentation
• Okta Developer Docs
• Railway Documentation

Status

⚠️ Unofficial Prototype - For evaluation and testing only. Not for production use.

License: Apache 2.0