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 backend origin only (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? }

Optional runtime routing override:

• baseUrl can be passed in tool arguments when the caller needs to choose backend at runtime.
• baseUrl must be host-only origin (for example https://talentnex-backend-qa-...run.app) and cannot include path/query/fragment.
• If baseUrl is omitted, server falls back to CAULDRON_API_BASE_URL.

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]
python -m pytest

Test Troubleshooting

• If collection fails with ModuleNotFoundError: mcp or ModuleNotFoundError: requests_mock, your active interpreter is missing runtime/dev dependencies.
• Reinstall into the same interpreter used for tests:
  • python -m pip install -e .[dev]
  • python -m pytest
• Verify imports directly in that environment:
  • python -c "import mcp, requests_mock; print('ok')"

Configuration

• CAULDRON_API_BASE_URL (required, host-only origin; no path/query/fragment)
• TALENTNEX_DEFAULT_LIMIT (optional, default 20)
• TALENTNEX_DEFAULT_SKIP (optional, default 0)
• TALENTNEX_BEARER_TOKEN (fallback token for stdio)
• TALENTNEX_ALLOWED_BASE_URL_HOSTS (optional, comma-separated host allowlist for both CAULDRON_API_BASE_URL and runtime baseUrl)

Common misconfiguration to avoid:

• Wrong: https://.../candidates/:candidateId/resume
• Correct: https://...

Packaging / Release

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