Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Job Matching Server calculate my match score for alpic-fullstack with skills TypeScript, React, Node.js"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A lightweight Model Context Protocol (MCP) server built with TypeScript and Node.js that helps AI agents evaluate candidate-job fit by calculating weighted match scores.
Built using the official @modelcontextprotocol/sdk.
The Model Context Protocol is an open standard that allows AI assistants (like Claude, Gemini, etc.) to interact with external tools and data sources through a unified interface. MCP servers expose tools that AI agents can discover and invoke autonomously.
This server demonstrates how to build a production-style MCP server that could power recruitment workflows in the agentic web.
Related MCP server: Recruitment AI MCP
Tool | Description |
| Returns a list of job postings with required and preferred skills (simulates a database query) |
| Compares a candidate's skills against a job's requirements and returns a weighted score with detailed breakdown |
The scoring engine uses a weighted formula:
Overall Score = (Required Skills Match × 0.70) + (Preferred Skills Match × 0.30)The response includes:
Overall match percentage
Required vs preferred skills breakdown
Matched and missed skills lists
Hiring recommendation (STRONG FIT, GOOD FIT, or STRETCH / LOW FIT)
Runtime: Node.js (ES2022)
Language: TypeScript (strict mode)
Protocol: MCP over Stdio transport (JSON-RPC 2.0)
SDK: @modelcontextprotocol/sdk
Node.js v18+ installed
npm
git clone https://github.com/nourelhoudaas/mcp-job-matching-server.git
cd mcp-job-matching-server
npm installnpm run buildA test script is included that spawns the server, sends a tools/call request via JSON-RPC, and prints the match score result:
node test-client.jsExpected output:
Starting MCP server for testing...
Server stderr log: Job Match MCP Server running on Stdio transport
Sending tools/call request to server stdin...
Received from server stdout: { ... overallMatchScore: "53%" ... }
Success: MCP Server successfully executed calculate_match_score!Add this to your claude_desktop_config.json:
{
"mcpServers": {
"job-matcher": {
"command": "node",
"args": ["/absolute/path/to/mcp-job-matching-server/build/index.js"]
}
}
}Then ask Claude: "Use the job-matcher tool to calculate my match score for the alpic-fullstack job with skills: TypeScript, React, Node.js"
mcp-job-matching-server/
├── src/
│ └── index.ts # MCP server implementation
├── build/ # Compiled JS (generated by tsc)
├── test-client.js # Automated verification script
├── package.json
├── tsconfig.json
└── README.mdRequest (JSON-RPC 2.0 via stdin):
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "calculate_match_score",
"arguments": {
"candidateSkills": ["TypeScript", "React", "Node.js", "SQL", "REST APIs"],
"jobId": "alpic-fullstack"
}
}
}Response (via stdout):
{
"jobId": "alpic-fullstack",
"company": "Alpic",
"title": "Full-Stack Software Engineer",
"overallMatchScore": "53%",
"breakdown": {
"requiredSkillsMatch": "3/4",
"preferredSkillsMatch": "0/4"
},
"matchedRequired": ["TypeScript", "React", "Node.js"],
"missedRequired": ["English communication"],
"matchedPreferred": [],
"missedPreferred": ["AWS CDK", "NestJS", "MCP", "Developer tools"],
"recommendation": "STRETCH / LOW FIT - Tailor carefully"
}Calculate a detailed match score between a candidate's skills and a job description.
| Name | Required | Description | Default |
|---|---|---|---|
| candidateSkills | Yes | List of candidate's skills (e.g. ['TypeScript', 'React', 'Node.js']) | |
| jobId | Yes | The ID of the job to match against (e.g. 'alpic-fullstack') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Only states 'calculate a detailed match score' without disclosing return format, side effects, or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with clear action and front-loaded purpose. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple but description omits return format and error handling. Adequate for basic use but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover both parameters fully (100% coverage). Description adds minimal value beyond schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'calculate' and resource 'match score', specifying inputs (candidate skills, job description). Distinct from sibling get_mock_jobs which retrieves jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use or exclude. Implied use case but lacks alternatives or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve list of mock job postings including requirements and metadata.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It only states 'retrieve' implying read-only, but fails to mention return format, pagination, rate limits, or any prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words, effectively communicating the tool's action and included information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and no annotations, the description is adequate but minimal. It could provide more context on the nature of the list (e.g., static vs. dynamic, approximate size) to improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so schema coverage is 100%. Baseline for this case is 4, and the description does not need to add parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the verb 'retrieve' and the resource 'list of mock job postings', specifying what is included (requirements and metadata). It effectively distinguishes from sibling 'calculate_match_score' which has a different purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. With a sibling tool present, explicit context for choosing this tool would be helpful but is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0calculate_match_scoreget_mock_jobsScored across 2 tools
The two tools have clearly distinct purposes: one calculates a match score, the other retrieves mock job postings. No overlap or ambiguity.
Both tools follow a consistent verb_noun pattern with underscores, making the naming predictable and clear.
With only 2 tools, the server feels minimal. While it may cover a narrow scope, typical job matching servers would require more tools, so the count is borderline.
The tool set is severely incomplete for a job matching domain. It lacks essential operations like searching jobs, managing candidate profiles, or submitting applications, leaving agents with limited functionality.
MCP server for building and testing AI agents with multi-model experimentation and insights.
WorkorAI talent marketplace MCP: candidate job search and employer hiring with explainable matching
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
MCP server for VC pitch-deck scoring, thesis-fit matching, and deal-flow management.
