TalentNex MCP Server (Python)

Model Context Protocol server for TalentNex (Cauldron backend). Exposes candidate and challenge data via MCP tools and resources, forwarding the Nexa Flow auth token as Authorization: Bearer <token> to Cauldron.

Features

• Tools: getCandidateById, searchCandidates, getJobRoles (shaped like cauldron-mcp-server redactions, including parsedResume).
• Resources: talentnex://candidates/recent, talentnex://challenges/all.
• Transports: stdio (mcp-talentnex) and HTTP/SSE (mcp-talentnex-http).

Requirements

• Python >= 3.10
• Env: CAULDRON_API_BASE_URL (e.g., https://api.cauldron.example.com)
• Auth: Authorization: Bearer <token> provided by Nexa Flow (passed through by client or HTTP header). For stdio, set TALENTNEX_BEARER_TOKEN or provide per-call via HTTP wrapper.

Install

pip install mcp-talentnex
# or
uvx mcp-talentnex

Run (stdio)

export CAULDRON_API_BASE_URL="https://api.cauldron.example.com"
export TALENTNEX_BEARER_TOKEN="<nexa-flow-token>"
mcp-talentnex

Run (HTTP/SSE)

export CAULDRON_API_BASE_URL="https://api.cauldron.example.com"
uvx mcp-talentnex-http
# or
mcp-talentnex-http

HTTP endpoints (for Claude Desktop HTTP MCP):

• GET /mcp/tools
• POST /mcp/tools/call { name, arguments }
• GET /mcp/resources
• POST /mcp/resources/read { uri }
• GET /health

Pass Authorization: Bearer <token> on each HTTP call; the server forwards it to Cauldron.

Tools

• getCandidateById args: { userId, companyId, candidateId, token? }
• searchCandidates args: { userId, companyId, q?, skills?, status?, limit?, skip?, token? }
• getJobRoles args: { userId, companyId, status?, limit?, skip?, token? }

If token is omitted, the server uses TALENTNEX_BEARER_TOKEN (stdio) or the HTTP Authorization header.

Resources

• talentnex://candidates/recent (uses limit 20, skip 0)
• talentnex://challenges/all (limit 50, skip 0)

Development (from source)

cd talentnex-mcp-server
python -m venv .venv && source .venv/bin/activate
pip install -e .[dev]
pytest

Configuration

• CAULDRON_API_BASE_URL (required)
• TALENTNEX_DEFAULT_LIMIT (optional, default 20)
• TALENTNEX_DEFAULT_SKIP (optional, default 0)
• TALENTNEX_BEARER_TOKEN (fallback token for stdio)

Packaging / Release

• Bump version in pyproject.toml
• python -m build
• twine upload dist/*
• Smoke: uvx mcp-talentnex --help