API & Integrationen

1. Voraussetzungen

Der Zugriff auf die MCP-API ist im Expert-Paket enthalten.

• Ein aktives CVforge-Konto mit laufendem Expert-Abonnement besitzen.
• Einen Personal Access Token (PAT) über die Seite Einstellungen → API & Integrationen erstellen.

2. Authentifizierung

CVforge unterstützt zwei Authentifizierungsmethoden. Für die meisten persönlichen Integrationen (n8n, Skripte, Claude Desktop) verwenden Sie einen PAT. Für Drittanbieter-Anwendungen nutzen Sie den OAuth 2.0 Authorization Code + PKCE-Flow.

2.1 Personal Access Token (PAT)

Ein PAT ist ein opaker Token mit dem Präfix mcp_pat_. Er wird nur ein einziges Mal bei der Erstellung angezeigt — bewahren Sie ihn sicher auf.

Authorization: Bearer mcp_pat_XXXXXXXXXXXXXXXXXXXX

2.2 OAuth 2.0 (Authorization Code + PKCE)

Für Anwendungen, die mehrere Benutzerkonten bedienen, verwenden Sie den Standard-OAuth-2.0-Flow.

2.3 Scopes

3. Einen MCP-Aufruf durchführen

Die MCP-API verwendet das Protokoll JSON-RPC 2.0 über HTTP. Jede Anfrage ist ein POST an https://api.cvforge.co/mcp.

Format einer Anfrage

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 */ }
  }
}

Format einer Antwort (Erfolg)

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

Format einer Antwort (Fehler)

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

4. Verfügbare Tools

Die API stellt 10 Tools bereit. Lese-Tools erfordern read:profile oder read:cv. Uploads, das Einreichen von Stellenanzeigen und Optimierungen erfordern 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. Integrationsbeispiele

5.1 Vollständiger Flow: Upload → Stellenanzeige → Optimierung → Download

Python-Beispiel, das den kompletten Ablauf in 4 Schritten veranschaulicht.

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

Fügen Sie den folgenden Block in Ihre Claude-Desktop-Konfigurationsdatei ein (~/Library/Application Support/Claude/claude_desktop_config.json unter macOS).

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

Nach dem Neustart hat Claude direkt in der Konversation Zugriff auf die CVforge-Tools. Sagen Sie zum Beispiel: "Liste meine Lebensläufe auf CVforge auf" oder "Lade die Datei MeinLebenslauf.pdf auf CVforge hoch".

5.4 n8n — HTTP-Request-Node

Erstellen Sie in n8n einen HTTP Request-Node mit den folgenden Parametern:

Das JSON-Ergebnis ist im nächsten Node über {{ $json.result.content[0].text }} verfügbar. Parsen Sie es mit einem Set- oder Function-Node, um die Felder zu extrahieren.

5.5 Cursor / Windsurf

In .cursor/mcp.json (oder dem Äquivalent für Windsurf):

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

6. Fehlercodes

7. Limits & Best Practices

Rate Limiting

Bei Überschreitung gibt die API einen HTTP 429 mit dem Header Retry-After zurück. Implementieren Sie in Ihren Automatisierungen einen exponentiellen Backoff.

Best Practices

• Erstellen Sie einen Token pro Integration (einen für n8n, einen für Claude Desktop…) — so können Sie einen einzelnen Token widerrufen, ohne die anderen zu beeinträchtigen.
• Gewähren Sie jedem Token nur die notwendigen Scopes.
• Speichern Sie Tokens in Umgebungsvariablen oder einem Secrets-Manager, niemals fest im Code.
• Widerrufen Sie jeden kompromittierten Token sofort über die Seite Einstellungen.
• Der MCP-Endpoint unterstützt offenes CORS — denken Sie daran, in Ihren eigenen Integrationen die Origin serverseitig zu validieren.

Auffindbarkeit

CVforge veröffentlicht ein MCP-Manifest, das von LLMs und Suchmaschinen gelesen werden kann:

• /.well-known/mcp.json — MCP-Manifest
• /.well-known/oauth-authorization-server — OAuth2-Discovery (RFC 8414)
• /llms.txt — MCP-Kontext für LLMs