contratando-mcp

MCP server for an AI agent (Hermes) to control Contratando — full read/write access to the platform: job vacancies, companies, candidates, applications, credits, subscriptions, commissions, users, and configuration.

How it works

This repo does not have access to the database. It's a thin client: every tool the agent calls is forwarded over HTTPS to POST {MCP_BRIDGE_URL}/api/mcp, a protected route inside the Contratando app itself (already deployed). The production database is intentionally kept private — this bridge is the way to control it without exposing it to the internet.

Hermes → contratando-mcp (stdio, local) → HTTPS + secreto → contratandord.com/api/mcp → Postgres (privada)

The real logic (what mutation each tool performs, validation, auditing) lives in the Contratando repo (src/lib/mcp/registro.ts). This repo only declares the 46 tools (name, description, input schema) so the agent knows what it can ask for.

If you're going to use scraper_mensajes_pendientes + vacantes_importar_lote (the scraper → draft → moderation flow), see PARSING.md for the exact structure each batch item expects.

Related MCP server: HeadHunter API MCP Server

Setup

npm install
cp .env.example .env

Fill in .env:

• MCP_BRIDGE_URL — https://contratandord.com (or http://localhost:3200 to test against local).

• MCP_API_SECRET — the same value as MCP_API_SECRET in Contratando's .env. If they don't match, the bridge rejects everything with 401.

npm start

Connecting it to an agent

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "contratando": {
      "command": "npx",
      "args": ["tsx", "C:\\ruta\\a\\contratando-mcp\\src\\server.ts"],
      "env": {
        "MCP_BRIDGE_URL": "https://contratandord.com",
        "MCP_API_SECRET": "..."
      }
    }
  }
}

Claude Code:

claude mcp add contratando -- npx tsx C:\ruta\a\contratando-mcp\src\server.ts

For Hermes or another MCP runtime: point it to npm start (or node --import tsx src/server.ts) in this directory, with MCP_BRIDGE_URL/MCP_API_SECRET in the environment.

What it does NOT do

• Does not upload files (logo, receipts, RNC documents).

• Does not edit a candidate's CV section by section (experience/education/languages one by one) — only the essentials of applications and company profile.

• talento_ficha never returns phone/email/ID number — the real talent search requires an audited unlock flow that this bridge does not replicate.

• Does not send email or notify Google when mutating — only in-app notification. The site picks up changes on its own (config cache up to 30s, normal sitemap/crawling for SEO).

Security

• The secret is compared on the server side with timingSafeEqual (no timing-based leakage).

• Rate limit of 30 calls / 5 min per IP on the bridge.

• Every mutation is recorded in Contratando's audit log with datos.via: "mcp", attributed to the super admin configured in SEED_ADMIN_EMAIL on the server side.

• If the secret leaks, rotate it on BOTH sides: MCP_API_SECRET in Contratando's .env (redeploy) and here.