API & integraties

1. Vereisten

Toegang tot de MCP-API is inbegrepen in het Expert-pakket.

• Heb een actief CVforge-account met een lopend Expert-abonnement.
• Maak een Personal Access Token (PAT) aan via de pagina Instellingen → API & integraties.

2. Authenticatie

CVforge ondersteunt twee authenticatiemethoden. Voor de meeste persoonlijke integraties (n8n, scripts, Claude Desktop) gebruik je een PAT. Voor applicaties van derden gebruik je de OAuth 2.0 Authorization Code + PKCE-flow.

2.1 Personal Access Token (PAT)

Een PAT is een opaak token met het voorvoegsel mcp_pat_. Het wordt maar één keer getoond bij het aanmaken — bewaar het zorgvuldig.

Authorization: Bearer mcp_pat_XXXXXXXXXXXXXXXXXXXX

2.2 OAuth 2.0 (Authorization Code + PKCE)

Voor applicaties die met meerdere gebruikersaccounts werken, gebruik je de standaard OAuth 2.0-flow.

2.3 Scopes

3. Een MCP-aanroep doen

De MCP-API gebruikt het JSON-RPC 2.0-protocol over HTTP. Elk verzoek is een POST naar https://api.cvforge.co/mcp.

Formaat van een verzoek

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXXXXXXXXXXXXXXXXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "<nom_de_l_outil>",
    "arguments": { /* paramètres de l'outil */ }
  }
}

Formaat van een antwoord (succes)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{ ...données... }"
      }
    ]
  }
}

Formaat van een antwoord (fout)

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Token invalide ou révoqué",
    "data": { "error_code": "MCP_TOKEN_INVALID" }
  }
}

4. Beschikbare tools

De API stelt 10 tools beschikbaar. Leestools vereisen read:profile of read:cv. Uploads, het indienen van vacatures en optimalisaties vereisen write:cv.

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "get_profile", "arguments": {} }
}

{
  "id": "uuid",
  "email": "alice@example.com",
  "full_name": "Alice Martin",
  "subscription_plan": "Expert",
  "subscription_status": "active"
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "get_credits", "arguments": {} }
}

{
  "total": 7,
  "subscription_credits": 5,
  "paid_credits": 2,
  "free_credits": 0
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_cvs", "arguments": { "limit": 10, "offset": 0 } }
}

{
  "cvs": [
    {
      "id": "uuid",
      "original_filename": "CV_Alice_2026.pdf",
      "created_at": "2026-04-10T14:30:00Z",
      "generation_count": 3
    }
  ],
  "total": 1
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "get_cv", "arguments": { "cv_id": "uuid" } }
}

{
  "id": "uuid",
  "original_filename": "CV_Alice_2026.pdf",
  "extracted_text": "Alice Martin — Product Manager...",
  "created_at": "2026-04-10T14:30:00Z"
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "upload_cv", "arguments": {
  "filename": "mon_cv.pdf",
  "file_base64": "JVBERi0xLjQ...",
  "mime_type": "application/pdf"
} }
}

{
  "cv_profile_id": "uuid",
  "message": "CV uploaded and parsed successfully."
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "submit_offer", "arguments": {
  "offer_url": "https://www.linkedin.com/jobs/view/1234567890/"
} }
}

{
  "offer_id": "uuid",
  "offer_url": "https://www.linkedin.com/jobs/view/1234567890/",
  "job_title": "Product Manager Senior",
  "company_name": "Acme Corp"
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "optimize_cv", "arguments": {
  "cv_profile_id": "uuid-du-cv",
  "offer_id": "uuid-de-l-offre"
} }
}

{
  "generation_id": "uuid",
  "status": "processing",
  "message": "CV optimization started"
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_generations", "arguments": { "limit": 5 } }
}

{
  "generations": [
    {
      "id": "uuid",
      "cv_id": "uuid",
      "job_title": "Product Manager Senior",
      "ats_score": 87,
      "status": "completed",
      "created_at": "2026-04-11T09:00:00Z"
    }
  ],
  "total": 1
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "get_generation", "arguments": { "generation_id": "uuid" } }
}

{
  "id": "uuid",
  "job_title": "Product Manager Senior",
  "ats_score": 87,
  "optimized_text": "Alice Martin — Product Manager Senior...",
  "analysis": { "missing_keywords": ["OKR", "roadmap"], "strengths": [...] },
  "status": "completed",
  "created_at": "2026-04-11T09:00:00Z"
}

POST https://api.cvforge.co/mcp
Content-Type: application/json
Authorization: Bearer mcp_pat_XXXX

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "download_generation", "arguments": { "generation_id": "uuid" } }
}

{
  "filename": "CV_Alice_PM_Senior.pdf",
  "content_b64": "JVBERi0xLjQ...",
  "mime_type": "application/pdf",
  "size_bytes": 124580
}

5. Integratievoorbeelden

5.1 Volledige flow: upload → vacature → optimalisatie → download

Python-voorbeeld dat het volledige traject in 4 stappen illustreert.

import requests, base64, time, json, os

PAT     = os.environ["CVFORGE_PAT"]
MCP     = "https://api.cvforge.co/mcp"
HEADERS = {"Content-Type": "application/json", "Authorization": f"Bearer {PAT}"}

def mcp(tool: str, args: dict = {}):
    r = requests.post(MCP, json={
        "jsonrpc": "2.0", "id": 1, "method": "tools/call",
        "params": {"name": tool, "arguments": args}
    }, headers=HEADERS, timeout=60)
    r.raise_for_status()
    data = r.json()
    if "error" in data:
        raise RuntimeError(data["error"]["message"])
    return json.loads(data["result"]["content"][0]["text"])

# Étape 1 — Upload du CV
with open("mon_cv.pdf", "rb") as f:
    b64 = base64.b64encode(f.read()).decode()

cv = mcp("upload_cv", {
    "filename": "mon_cv.pdf",
    "file_base64": b64,
    "mime_type": "application/pdf",
})
cv_id = cv["cv_profile_id"]
print(f"CV uploadé : {cv_id}")

# Étape 2 — Soumission de l'offre
offer = mcp("submit_offer", {
    "offer_url": "https://www.linkedin.com/jobs/view/1234567890/"
})
offer_id = offer["offer_id"]
print(f"Offre : {offer['job_title']} @ {offer['company_name']} ({offer_id})")

# Étape 3 — Lancement de l'optimisation (1 crédit consommé)
gen = mcp("optimize_cv", {"cv_profile_id": cv_id, "offer_id": offer_id})
gen_id = gen["generation_id"]
print(f"Génération démarrée : {gen_id}")

# Étape 4 — Attente + téléchargement
for _ in range(20):
    time.sleep(5)
    details = mcp("get_generation", {"generation_id": gen_id})
    print(f"  statut : {details['status']}")
    if details["status"] == "completed":
        dl = mcp("download_generation", {"generation_id": gen_id})
        print(f"Téléchargement : {dl['download_url']} (valide 15 min)")
        break
    if details["status"] == "failed":
        raise RuntimeError("Optimisation échouée")

5.2 curl

# Remplacez YOUR_PAT par votre Personal Access Token
export PAT="mcp_pat_XXXXXXXXXXXXXXXXXXXX"

# Récupérer le profil
curl -X POST https://api.cvforge.co/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PAT" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_profile","arguments":{}}}'

# Vérifier le solde de crédits
curl -X POST https://api.cvforge.co/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $PAT" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_credits","arguments":{}}}'

5.3 Claude Desktop / Claude.ai

Voeg het volgende blok toe aan je Claude Desktop-configuratiebestand (~/Library/Application Support/Claude/claude_desktop_config.json op macOS).

{
  "mcpServers": {
    "cvforge": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.cvforge.co/mcp",
        "--header",
        "Authorization: Bearer mcp_pat_XXXXXXXXXXXXXXXXXXXX"
      ]
    }
  }
}

Na een herstart heeft Claude rechtstreeks in het gesprek toegang tot de CVforge-tools. Zeg bijvoorbeeld: "Toon mijn cv's op CVforge" of "Upload het bestand MijnCV.pdf naar CVforge".

5.4 n8n — HTTP Request-node

Maak in n8n een HTTP Request-node aan met de volgende parameters:

Het JSON-resultaat is beschikbaar in de volgende node via {{ $json.result.content[0].text }}. Parse het met een Set- of Function-node om de velden te extraheren.

5.5 Cursor / Windsurf

In .cursor/mcp.json (of het equivalent voor Windsurf):

{
  "mcpServers": {
    "cvforge": {
      "url": "https://api.cvforge.co/mcp",
      "headers": {
        "Authorization": "Bearer mcp_pat_XXXXXXXXXXXXXXXXXXXX"
      }
    }
  }
}

6. Foutcodes

7. Limieten & best practices

Rate limiting

Bij overschrijding geeft de API een HTTP 429 terug met de header Retry-After. Implementeer exponentiële backoff in je automatiseringen.

Best practices

• Maak één token per integratie aan (één voor n8n, één voor Claude Desktop…) — zo kun je er één intrekken zonder de andere te beïnvloeden.
• Ken elk token alleen de noodzakelijke scopes toe.
• Bewaar tokens in omgevingsvariabelen of een secrets manager, nooit hardcoded in je code.
• Trek een gecompromitteerd token onmiddellijk in via de pagina Instellingen.
• Het MCP-endpoint ondersteunt open CORS — vergeet niet de origin server-side te valideren in je eigen integraties.

Vindbaarheid

CVforge publiceert een MCP-manifest dat leesbaar is voor LLM's en zoekmachines:

• /.well-known/mcp.json — MCP-manifest
• /.well-known/oauth-authorization-server — OAuth2-discovery (RFC 8414)
• /llms.txt — MCP-context voor LLM's