MCP Recruiting Server

Connect AI assistants like Claude, ChatGPT, and Cursor to RESTume using the Model Context Protocol (MCP). Search candidates, rank them for roles, compare profiles, and get fit explanations — all from inside the AI tools you already use. 15 tools and 2 resources, served over Streamable HTTP.

Quick Start (30 seconds)

Paste this into Claude Desktop, ChatGPT, or Cursor MCP config.

{
  "mcpServers": {
    "restume": {
      "url": "https://mcp.restume.com/mcp"
    }
  }
}

Overview Setup Response Contract Tools Resources Workflow MCP vs REST Troubleshooting

What MCP is used for in RESTume

The Model Context Protocol (MCP) lets AI assistants call RESTume as native tools. In RESTume, this is no longer just profile lookup. The MCP server now supports end-to-end recruiting workflows such as candidate search, ranking, shortlisting, multi-candidate comparison, skill-gap analysis, and deterministic profile verification across certifications and explicit availability.

Results are structured and deterministic so the LLM can reason on top of reliable data. Tool calls are auditable, profile exposures are tracked, and paginated endpoints keep large result sets stable for agent loops.

Discovery + Profiles

List candidates, run broad or skill-specific search, fetch full profiles, and compare candidates quickly.

Recruiting Intelligence

Search candidates by constraints, rank against job text, explain fit, build shortlists, compare many candidates, and identify skill gaps.

Setup

Point your MCP client to the server URL. No local server process is required.

ChatGPT, Claude Desktop / Cursor / Windsurf

Direct URL connection:

{
  "mcpServers": {
    "restume": {
      "url": "https://mcp.restume.com/mcp"
    }
  }
}

Stdio-only clients

Use mcp-remote bridge:

{
  "mcpServers": {
    "restume": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.restume.com/mcp"]
    }
  }
}

Security and discovery

The endpoint uses Streamable HTTP with stateless transport. Optional access controls include static bearer token or JWT bearer validation. Optional origin checks and per-minute rate limiting are configurable in MCP runtime settings.

OAuth metadata endpoints: /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-authorization-server/mcp.

Response Contract

All tools return a stable envelope with machine-readable metadata.

Success envelope

{
  "ok": true,
  "data": {},
  "error": null,
  "meta": {
    "tool": "tool_name",
    "version": "2026-02-18",
    "generated_at": "2026-02-18T12:34:56Z"
  }
}

Error envelope

{
  "ok": false,
  "data": null,
  "error": {
    "code": "invalid_input|not_found|internal_error",
    "message": "human readable message",
    "details": {}
  },
  "meta": {
    "tool": "tool_name",
    "version": "2026-02-18"
  }
}

Pagination metadata

Paginated tools accept limit and cursor, and return continuation metadata.

"meta": {
  "tool": "search_candidates",
  "total": 145,
  "limit": 25,
  "cursor": null,
  "next_cursor": "eyJvZmZzZXQiOjI1fQ=="
}

Tools

Core Discovery and Profile Tools

These tools expose platform entities and profile structure for downstream recruiting decisions.

list_developers(limit?, cursor?)

Enumerate professionals with summary fields and section counts.

search_developers(query, limit?, cursor?)

Broad text search across profile, skills, experience, education, projects, certifications, and explicit availability text.

get_user_profile(username)

Return full structured profile, including open-to-work state, skills, experience, education, projects, and certifications.

search_developers_by_skill(skill, limit?, cursor?)

Skill-specific candidate discovery with semantic + typo-tolerant matching and proficiency-aware results.

compare_developers(username1, username2)

Two-candidate side-by-side comparison for fast screening decisions.

Profile Intelligence Tools

These tools help agents verify profile freshness, extract deterministic facts, and answer profile questions with explicit evidence.

get_profile_index_status(username)

Report section-level embedding freshness, missing document IDs, and index coverage health.

get_profile_facts(username, facets?)

Return deterministic facts such as skills, titles, companies, current role, certifications, and explicit availability for reliable agent grounding.

search_profile_evidence(username, query, facets?, top_k?)

Facet-aware lexical evidence search with matched terms and scored snippets across sections including certifications and availability.

answer_profile_question(username, question, include_full_profile?)

Structured profile data retrieval with intent classification: returns matched entities (skills, experience, education, certifications) and cross-references relevant to the question.

Recruiting Workflow Tools

These tools support sourcing, ranking, explanation, and shortlist generation from job context.

search_candidates(skills?, location?, companies?, keywords?, min_years_experience?, sort_by?, limit?, cursor?)

Constraint-based candidate search designed for recruiter filtering workflows.

rank_candidates_for_job(job_description, required_skills?, preferred_skills?, limit?, cursor?)

Deterministic ranking with score components so results are explainable and repeatable.

explain_candidate_fit(username, job_description, required_skills?, preferred_skills?)

Candidate fit assessment with score breakdown, matched/missing skills, recommendation, and risk flags.

shortlist_candidates(job_description, required_skills?, preferred_skills?, min_score?, limit?, cursor?)

Generate shortlist-ready outputs by thresholding candidate scores.

compare_candidates(usernames, criteria?)

Compare multiple candidates at once with overlap and differentiation signals. The optional criteria input controls which metric groups are included.

find_skill_gaps(username, target_role_or_job, target_skills?, max_suggestions?)

Identify missing skills for a role using agent-provided target skills or auto-detected heuristics.

Resources

restume://users/{username}/profile

Plain-text profile summary for lightweight agent context injection.

restume://users/{username}/resume

Full resume in Markdown for rich context loading without extra tool orchestration, including certifications and availability when present.

Example Recruiting Workflow

A practical sequence an AI recruiting assistant can run:

1. Source candidates

Run search_candidates(...) with skill/location/company constraints.

2. Rank for role

Call rank_candidates_for_job(job_description, ...) for deterministic scoring.

3. Build shortlist

Use shortlist_candidates(..., min_score) to get interview-ready candidates.

4. Explain top profiles

Call explain_candidate_fit(username, ...) to brief hiring managers.

5. Final comparison + growth plan

Use compare_candidates(usernames) and find_skill_gaps(username, target_role_or_job).

Recruiter Prompt Examples

Prompt

Find backend engineers with 5+ years in Python and FastAPI in New York.

Expected MCP flow

`search_candidates` -> `rank_candidates_for_job` -> `shortlist_candidates`

Prompt

Compare `alex` and `sam` for this Staff Platform Engineer role and explain tradeoffs.

Expected MCP flow

`compare_developers` -> `explain_candidate_fit` for each candidate

Prompt

Shortlist candidates scoring above 0.75 and identify the top 3 missing skills for each.

Expected MCP flow

`shortlist_candidates` -> `find_skill_gaps` per shortlisted candidate

Prompt

Before I reach out, tell me whether this candidate is explicitly open to work and whether they have any documented certifications.

Expected MCP flow

`get_profile_facts` -> `answer_profile_question` -> `search_profile_evidence` when the agent wants citations

MCP vs REST API

Feature	REST API	MCP Recruiting Server
Transport	HTTP/JSON	Streamable HTTP
Auth model	JWT/API key endpoints	Optional bearer/JWT auth at MCP edge
Primary use	App integrations and CRUD	AI-native recruiting orchestration
Tool surface	Endpoint-by-endpoint	15 tools + 2 resources
Result consistency	Standard JSON responses	Unified envelope + pagination metadata
Auditability	API analytics	Tool invocation logging + MCP profile view tracking

Troubleshooting

HTTP 404 from MCP client

Confirm client URL is exactly https://mcp.restume.com/mcp and verify protected-resource metadata is reachable.

HTTP 401

Only expected when MCP bearer auth is enabled by deployment settings. Check token format and JWT claims if JWT auth is configured.

HTTP 429

Request rate exceeded the configured MCP per-minute limit. Add retry with backoff and lower reconnect churn.

Tools missing in client

Restart the MCP client after config changes and validate JSON syntax. Some clients cache tool schemas per session.

See also: Developer Portal · REST API docs · OpenAPI