hr-mcp-agent-demo
osa-ora/hr-mcp-agent-demo
Demo building HR system using Custom HR MCP Server & Agent
Instalação
npx convez-ai osa-ora/hr-mcp-agent-demo1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
HR MCP Agent Demo
A demonstration project showing how to build an AI-powered HR assistant using a custom MCP (Model Context Protocol) server, an autonomous agent, and a PostgreSQL-backed HR system.
The goal of this project is to illustrate how enterprise business systems can be exposed as AI tools (via a custom MCP server) and consumed by an agent capable of performing HR workflows through natural language interactions.
This demostrates the concept that:
AI is the new UI for applications
Overview
This demo consists of five main components:
1. HR Database
A PostgreSQL database containing HR-related information such as:
- Employee profiles
- Managers and reporting structures
- Employee contacts
- Employment information
- Leave balances
- Leave requests
- Leave types
- Compensation information
- HR policies
You can see tables like employees:
employees = Table(
"employees",
metadata,
# Business identity (PRIMARY KEY NOW)
Column("employee_code", String(50), primary_key=True),
Column("full_name", String(200), nullable=False),
Column("sex", String(20)),
Column("birthdate", Date),
Column("marital_status", String(50)),
Column("nationality", String(100)),
# Business relationship (no FK constraint by design)
Column("manager_code", String(50), nullable=True),
Column("created_at", DateTime),
Column("updated_at", DateTime)
)
Here is a simplified view of the sample HR DB:
2. Database Service Layer
This layer exposes the database functionality in the file db_service.py. It exposes the needed CRUD operations for all tables transactions and enforce some rules as well:
def get_employee_profile(employee_code: str):
with engine.begin() as conn:
emp = _get_employee(conn, employee_code)
return dict(emp) if emp else None
The database is configured in the file db.py and it inherit the value from config file which get these values from .env file. You can update that file .env it to point to your database:
from config import DATABASE_URL
engine = create_engine(
DATABASE_URL or "postgresql+psycopg2://postgres:postgres@localhost:5432/hrdb",
echo=False
)
3. Custom HR MCP Server
A custom MCP server built using FastMCP that exposes HR operations as tools, FastMCP is a Python framework for building and exposing tools through the Model Context Protocol (MCP). It simplifies the creation of AI-accessible services by providing a lightweight way to define, register, and serve tools that can be discovered and invoked by MCP-compatible agents and clients.
Example capabilities include:
- Employee profile lookup
- Detailed employee information retrieval
- Manager lookup
- Leave balance inquiries
- Leave request creation
- Leave request approval and rejection
- Policy search
- Leave type discovery
You can see function like:
import db_service as db
# =========================================================
# EMPLOYEE PROFILE
# SKILL: employee_profile
# =========================================================
@mcp.tool(
annotations={"skill": "employee_profile"},
description="""
ROLE: ANY EMPLOYEE
Get basic employee basic profile information using employee_code
"""
)
def get_employee_basic_profile(employee_code: str):
return db.get_employee_profile(employee_code)
That's very simple and easy way to build pluggable integration layer for AI that exposes your internal system functionality. Without MCP, the LLM would need custom integration code for every business system. MCP standardizes tool access, allowing any MCP-compatible client or agent to discover and invoke enterprise functionality through a common protocol.
The good level of tool description is essential to let the LLM understand the use of that function very well and its input parameters and if there is any constraints like required role.
You can change the mcp_server configurations especially if you plan to run many and need different ports for execution, to do this change the .env file:
from config import MCP_HOST, MCP_PORT, MCP_TRANSPORT
if __name__ == "__main__":
print("REGISTERED TOOLS:", mcp.list_tools())
mcp.run(
transport=MCP_TRANSPORT,
host=MCP_HOST,
port=MCP_PORT
)
We used initially SSE protocol but then switched to HTTP, The SSE (Server-Sent Events) is a lightweight HTTP-based protocol that allows a server to continuously push real-time updates to a client over a single long-lived connection, it becomes a legacy now and most of the modern mcp are using http (or streamable_http).
The MCP server acts as a secure abstraction layer between the agent and the HR system.
4. HR Agent
HR Agent Examples
We have built four HR agent examples:
First: Custom Python Agent
A custom Python AI agent powered by a local LLM through Ollama, named hr_agent.py.
Second: Level-1 LangGraph Agent
A Level-1 LangGraph agent, also powered by a local LLM through Ollama, named lang-graph-hr-agent.py. This version sends all MCP server tools to the LLM for planning and execution.
LangGraph is a framework for building stateful, multi-step AI agents using graph-based workflows. It enables developers to model complex reasoning, planning, tool-calling, and decision-making processes as interconnected nodes, making agent execution more controllable, observable, and maintainable than traditional prompt chains.
Third: Level-2 LangGraph Agent
A Level-2 LangGraph agent named lang-graph-hr-agent-v2.py. This version is skill-based, filtering MCP server tools by skill (virtual grouping) and sending only the relevant tool groups required by the LLM to complete the requested task.
Skill-Based Tool Routing
The agent uses a lightweight skill-selection layer to identify the minimum set of MCP tool categories required for a user request. By filtering available tools before planning, the agent reduces prompt size, improves tool-selection accuracy, and keeps reasoning focused on the relevant domain capabilities.
Fourth: Level-3 LangGraph Agent
A Level-3 LangGraph agent named lang-graph-hr-agent-v3.py. This version builds on the skill-based architecture and externalizes prompts into dedicated template files.
Prompt Externalization with Jinja2
The agent uses Jinja2 templates to externalize all LLM prompts from the application code. This separates prompt engineering from business logic, making prompts easier to maintain, version, test, and update without modifying the agent implementation. Runtime context (such as user input, tool schemas, and execution history) is injected into templates to generate the final prompts sent to the model.
Jinja is a fast, expressive, extensible templating engine. Special placeholders in the template allow writing code similar to Python syntax. Then the template is passed data to render the final document, e.g. {{ variable }} place holders, while {% %} is control flow syntax. Read more: https://jinja.palletsprojects.com/en/stable/
For Example: response.jinja2
You are a helpful HR Assistant.
Answer the user's original request using the provided history of tool execution steps.
Be concise, professional, and do not mention the technical tool names.
User Request: {{ user_input }}
Execution History Data:
{{ history }}
And we seed these placeholders with the corresponding values for the agent.
The agent main functions:
- Understands user requests
- Discovers available MCP tools
- Selects the appropriate tool
- Executes multi-step workflows
- Maintains conversational context
- Produces user-friendly responses
You can still customize agent(s) configurations as following:
# For the custom Python agent:
agent = HRAgent(
AgentConfig(
debug=False,
max_steps=9,
mcp_endpoint="http://127.0.0.1:8000/mcp",
model_name="llama3.1"
)
)
# if you called in of them without any configurations, the defaults are resolved from environment variables via .env file through config.py.
from config import MODEL_NAME, DEBUG, MAX_STEPS, MCP_ENDPOINT
# for both LangGraph agent(s):
class Config:
model_name = "llama3.1"
mcp_url = "http://127.0.0.1:8000/mcp"
debug = False
max_steps= = 5
# And it also get these values from the .env file through config.py
Example requests:
- "leave balance for Osama Oransa?"
- "basic profile for Sara Ali"
- "Show my full profile for EMP001?"
- "policy for remote work?"
- "leave requests for Osama Oransa."
- "basic profile for EMP002"
Alternatively, you can use any ChatClient and configure the model and the mcp server to convert it to HR Agent (as we well see in the following section).
5. LLM Models
In this demo, we used local Ollama models such as llama3.1.
Technologies Used
- Python, FastMCP, MCP (Model Context Protocol), Ollama, Llama 3.1, PostgreSQL, SQLAlchemy, AsyncIO, Langgraph and others.
Learning Objectives
This project demostrates:
- Building custom MCP servers
- Tool-based AI agents
- LangGraph orchestration Agent
- Enterprise system integration
- Multi-step agent workflows
- Database-backed AI applications
- Agent-to-tool orchestration
- Natural language interfaces for business systems.
How to Run the Demo
After cloning the repository, follow these steps:
1. Setup environment
./setup_venv.sh
This will create a Python 3.12 virtual environment and install all required dependencies.
2. Activate environment
source .venv/bin/activate
Then edit the .env file for any changes you need to do.
3. Start PostgreSQL DB & Create 'hrdb' database
CREATE DATABASE hrdb;
4. Initialize database schema
python3 init_db.py
5. Seed test data
python3 seed_init_data.py
6. Run MCP server
python3 mcp_server.py
If successful, you will see:
Starting MCP server 'hr-system-v2' with transport 'http' on transport.py:304 http://0.0.0.0:8000/mcp
MCP Server Screenshot
Run the Local LLM
Install and start Ollama:
ollama pull llama3.1
ollama serve
You can also use other compatible models if needed.
Run the Python Agent
You can test the agent using the provided notebook:
test-agent.ipynb
Run all cells and interact with the HR Agent the way you want.
Or you can run it directly from the command line:
source .venv/bin/activate
python3 hr_agent.py
Or you can run the LangGraph Agent directly from the command line:
source .venv/bin/activate
python3 lang-graph-hr-agent.py
You can then use the better quality agent, that filter the mcp tools based on the needed skills to respond to customer specific request, using:
source .venv/bin/activate
python3 lang-graph-hr-agent-v2.py
Finally, the more dynamic agent, that filter the mcp tools and load the prompt from templates, using:
source .venv/bin/activate
python3 lang-graph-hr-agent-v3.py
You can see the LangGraph agent is much more mature and more accurate.
Note: The performance of all these agents can be more solid if they use a better and strong LLM.
Note: To check the optimal agent, with multiple dynamic MCP Server discovery, check the following repository: https://github.com/osa-ora/ocp-ai-mcp-client-demo
Using a Chat UI (Optional)
The other way is to integrate the system with a chat interface such as Open WebUI or any MCP-compatible client.
- Add the required model: e.g. Ollama
- Add MCP_SERVER and name it as HR MCP_SERVER
Here I am using for example: ChatBox: https://github.com/chatboxai/chatbox
This allows a more natural chat-based experience instead of running the Python agent directly.
How to Run the HR MCP Server on OpenShift Environment
Folliw the detailed instructions in the GitHub Repository: https://github.com/osa-ora/ocp-ai-custom-mcp-demo
License
This project is for educational and demonstration purposes only.