API & Integrations

1. Prerequisites

Access to the MCP API is included in the Expert pack.

• Have an active CVforge account with a current Expert subscription.
• Create a Personal Access Token (PAT) from the Settings → API & Integrations page.

2. Authentication

CVforge supports two authentication methods. For most personal integrations (n8n, scripts, Claude Desktop), use a PAT. For third-party applications, use the OAuth 2.0 Authorization Code + PKCE flow.

2.1 Personal Access Token (PAT)

A PAT is an opaque token prefixed with mcp_pat_. It is shown only once when created — store it safely.

Authorization: Bearer mcp_pat_XXXXXXXXXXXXXXXXXXXX

2.2 OAuth 2.0 (Authorization Code + PKCE)

For applications serving multiple user accounts, use the standard OAuth 2.0 flow.

2.3 Scopes

3. Making an MCP call

The MCP API uses the JSON-RPC 2.0 protocol over HTTP. Each request is a POST to https://api.cvforge.co/mcp.

Request format

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

Response format (success)

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

Response format (error)

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

4. Available tools

The API exposes 10 tools. Read tools require read:profile or read:cv. Uploads, offer submissions and optimizations require 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. Integration examples

5.1 Full flow: upload → offer → optimization → download

Python example illustrating the complete journey in 4 steps.

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

Add the following block to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS).

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

Once restarted, Claude will have access to the CVforge tools directly in the conversation. Say for example: "List my resumes on CVforge" or "Upload the file MyResume.pdf to CVforge".

5.4 n8n — HTTP Request node

In n8n, create an HTTP Request node with the following parameters:

The JSON result is available in the next node via {{ $json.result.content[0].text }}. Parse it with a Set or Function node to extract the fields.

5.5 Cursor / Windsurf

In .cursor/mcp.json (or the equivalent for Windsurf):

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

6. Error codes

7. Limits & best practices

Rate limiting

If exceeded, the API returns an HTTP 429 with the Retry-After header. Implement exponential backoff in your automations.

Best practices

• Create one token per integration (one for n8n, one for Claude Desktop…) — this makes it easy to revoke a single one without impacting the others.
• Grant only the scopes each token actually needs.
• Store tokens in environment variables or a secrets manager, never hardcoded in your code.
• Immediately revoke any compromised token from the Settings page.
• The MCP endpoint supports open CORS — remember to validate the origin server-side in your own integrations.

Discoverability

CVforge publishes an MCP manifest readable by LLMs and search engines:

• /.well-known/mcp.json — MCP manifest
• /.well-known/oauth-authorization-server — OAuth2 discovery (RFC 8414)
• /llms.txt — MCP context for LLMs