HR System MCP Server

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

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)

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

Troubleshooting

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 to .env and fill in values

JWKS fetch error: Verify Okta domain and authorization server ID are correct

Gateway target registration needs tool list: Set PROTECTED_DISCOVERY=false so unauthenticated tools/list returns the tool list (e.g. for AgentCore gateway)

Project Structure

hr-system-mcp/
├── main.py              # FastMCP server with HTTP handler
├── requirements.txt     # Python dependencies
├── env.example         # Environment template
└── auth/
    ├── __init__.py
    └── okta_validator.py  # Okta token validation

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": {}
  }'

References

• MCP Specification
• FastMCP Documentation
• Okta Developer Docs

Status

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

License: Apache 2.0