urssaf-vigilance-mcp

Serveur MCP pour vérifier les attestations de vigilance Urssaf que vous recevez de vos fournisseurs et sous-traitants, et tenir votre tableau de suivi.

En France, tout donneur d'ordre qui conclut un contrat d'au moins 5 000 € HT doit obtenir de son cocontractant une attestation de vigilance Urssaf à la signature, puis tous les six mois, et en vérifier l'authenticité (art. L.8222-1 et D.8222-5 du Code du travail, L.243-15 du Code de la sécurité sociale). À défaut, il peut être tenu solidairement des cotisations et pénalités du sous-traitant en cas de travail dissimulé.

La vérification se fait normalement à la main sur urssaf.fr, code par code, derrière un captcha. Ce connecteur s'appuie sur l'API officielle de l'Urssaf « Attestations Vérification Code Sécurité », qui rend le même service sans captcha et permet de vérifier jusqu'à 100 attestations en un appel. Il ajoute la lecture du PDF reçu, le rapprochement champ à champ, le calcul de la fin de validité et la mise à jour d'un classeur Excel.

Ce projet n'est pas affilié à l'Urssaf. L'API et ses conditions d'utilisation sont décrites sur le Portail API Urssaf.

Sommaire

1. Ce que fait le connecteur

2. Obtenir ses identifiants API Urssaf

3. Installation

4. Configuration

5. Tableau de suivi Excel

6. Règles métier

7. Sécurité et engagements

8. Développement

Related MCP server: eu-verify

Ce que fait le connecteur

Natures d'attestation reconnues : vigilance (AVG_UR, AVG_RSI), mais aussi CSG/CRDS, formation professionnelle, employeur de personnel de maison, frontalier suisse, chiffre d'affaires micro-entrepreneur, artistes-auteurs — l'API couvre toutes les attestations à code de sécurité émises par l'Urssaf.

Obtenir ses identifiants API Urssaf

L'API est gratuite et ouverte à toute personne physique ou morale, sous réserve de validation par l'Urssaf (« accès public et libre, tout demandeur est éligible »). Comptez 1 à 2 jours ouvrés.

1. Créer un compte sur le Portail API Urssaf : https://portailapi.urssaf.fr/fr/inscription (adresse e-mail professionnelle, SIRET de votre organisation).

2. Souscrire à l'API « Attestations Vérification Code Sécurité » : https://portailapi.urssaf.fr/fr/catalogue-api/prd/avcs/souscription-formulaire. Le formulaire demande l'usage prévu (vérification des attestations de vigilance de vos fournisseurs en tant que donneur d'ordre) et l'acceptation des CGU de l'API.

3. Recevoir les identifiants. L'équipe « Secteur API » de l'Urssaf Caisse nationale envoie un e-mail avec une archive protégée par mot de passe (le mot de passe arrive dans un second e-mail). Elle contient :

   • client-id et client-secret (UUID) ;

   • le scope : attn.codes_securite ;

   • l'URL d'obtention du jeton : https://api.urssaf.fr/api/oauth/v1/token ;

   • l'hôte des ressources : https://api.urssaf.fr. Un accès dit « sandbox » (api-edi.urssaf.fr) peut être fourni avant la production.

4. Renseigner URSSAF_CLIENT_ID et URSSAF_CLIENT_SECRET dans la configuration du serveur (ci-dessous), avec URSSAF_ENV=production.

Support : questions techniques via le centre de services ACOSS (JIRA), autres questions via le formulaire du portail. Documentation technique de l'API (PDF ACOSS v1.2) et changelog : onglets « Documentation » et « Changelog » de la page de l'API.

Installation

Python 3.11 ou plus récent.

git clone https://github.com/aghulas/urssaf-vigilance-mcp.git
cd urssaf-vigilance-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

Le paquet installe la commande urssaf-vigilance-mcp (serveur MCP sur stdio).

Sans identifiants, vous pouvez tester le connecteur en mode simulé : URSSAF_MOCK=1. Les codes MOCKVALIDE00001, MOCKPERIMEE0001, MOCKMANQUANT001 renvoient respectivement une attestation valide, périmée et incomplète ; tout autre code est inconnu.

Configuration

Toute la configuration passe par des variables d'environnement — aucun secret dans un fichier versionné.

Le jeton OAuth2 (client_credentials, validité 1 h) est mis en cache et renouvelé automatiquement deux minutes avant expiration, conformément aux recommandations du portail.

Claude Desktop

Dans claude_desktop_config.json (macOS : ~/Library/Application Support/Claude/, Windows : %APPDATA%\Claude\), ajoutez :

"urssaf-vigilance": {
  "command": "/chemin/vers/urssaf-vigilance-mcp/.venv/bin/urssaf-vigilance-mcp",
  "env": {
    "URSSAF_ENV": "production",
    "URSSAF_CLIENT_ID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "URSSAF_CLIENT_SECRET": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "URSSAF_FICHIER_SUIVI": "/chemin/vers/Suivi des attestations.xlsx",
    "URSSAF_ECRITURE": "1"
  }
}

Sous Windows, remplacez command par C:\\chemin\\vers\\.venv\\Scripts\\urssaf-vigilance-mcp.exe. Redémarrez Claude Desktop après modification.

Autres clients MCP

Tout client compatible MCP (Claude Code, Cursor, etc.) peut lancer urssaf-vigilance-mcp sur stdio avec les mêmes variables d'environnement. Exemple en ligne de commande :

URSSAF_MOCK=1 .venv/bin/urssaf-vigilance-mcp

Tableau de suivi Excel

Le connecteur lit et met à jour un classeur Excel ordinaire — le vôtre, ou celui que crée suivi_creer_modele. Il ne dépend pas des lettres de colonnes mais des en-têtes (recherche insensible à la casse et aux retours à la ligne), ce qui permet d'ajouter vos propres colonnes (assurances, PPSPS, contacts…). Colonnes reconnues :

Un code est considéré « à vérifier » tant que sa cellule Vérification ne mentionne pas un contrôle effectué.

L'écriture dans le classeur n'a lieu que si l'appel demande ecrire=True et que URSSAF_ECRITURE=1 ; faites une sauvegarde avant, et fermez le fichier dans Excel (en particulier sur un lecteur synchronisé).

Règles métier

• Validité : une attestation de vigilance est valable six mois à compter de la fin de la période analysée (la date « à jour au » du document), pas de sa date d'édition. Le connecteur arrondit à la fin du mois : à jour au 31/08 → échéance 28/02 (29 en année bissextile). L'Urssaf applique la même règle dans ses réponses « attestation périmée depuis le … ». Une alerte est émise à 30 jours de l'échéance.

• Un code valide ne suffit pas. Il prouve que le document existe chez l'Urssaf, pas que l'entreprise est votre cocontractant ni que l'établissement qui travaille pour vous est couvert. controler_attestation vérifie donc aussi : nature = attestation de vigilance ; SIREN et SIRET du PDF égaux à ceux renvoyés par l'Urssaf ; présence du siret_attendu (celui du devis ou du contrat) dans la liste des établissements.

• Verdicts : code inconnu, attestation périmée, SIREN différent ou SIRET attendu absent → REFUS ; écarts d'effectif, de masse salariale ou de date de certification, échéance proche → ALERTE ; sinon OK.

• Une attestation sur l'honneur, un quitus d'une plateforme privée ou une capture d'écran ne remplacent pas l'attestation Urssaf. En cas de code inconnu, demandez à l'entreprise le PDF original téléchargé depuis son espace urssaf.fr.

Sécurité et engagements

En souscrivant à l'API, vous acceptez les CGU de l'Urssaf, qui imposent notamment : n'utiliser l'API que pour vérifier des attestations (jamais pour obtenir des informations sur des comptes cotisants) ; ne divulguer ni les identifiants ni les données retournées ; signaler toute faille de sécurité à contact.api@urssaf.fr sous 48 heures ; respecter les quotas (HTTP 429 en cas de dépassement). Repli en cas d'indisponibilité : l'outil web https://www.urssaf.fr/accueil/outils-documentation/outils/verification-attestation.html.

Le connecteur ne stocke rien : pas de base de données, pas de journal des codes vérifiés ; les identifiants ne sont lus que dans l'environnement du processus.

Développement

.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest -q        # tests sans réseau (respx)
python tests/fixtures/generer_fixture.py   # régénère le PDF d'exemple (données fictives)

Le dossier skills/ contient une skill Claude générique décrivant la procédure de vérification d'une attestation reçue et la revue périodique du tableau ; adaptez-la à votre organisation (dossiers d'archivage, interlocuteurs).

Les contributions sont bienvenues : ouvrez une issue ou une pull request.

Licence

MIT — voir LICENSE.