Intégration tierce partie MCP

Documents humains (Contexte et conseils)

Cette section fournit des **conseils conceptuels et pratiques pour les lecteurs humains** s'intégrant à MyDocSafe MCP.

### À quoi sert le MCP

Utilisez MyDocSafe MCP lorsque vous en avez besoin :
– Intégrer MyDocSafe dans un produit ou un service externe
– Autoriser les systèmes tiers ou les agents d'IA à agir au nom des utilisateurs
– Appliquer des limites strictes en matière d'autorisation, d'audit et de sécurité
– Évitez d’exposer des données internes brutes ou des bases de données.

MCP fournit une **interface basée sur les capacités**, ce qui signifie :
– Les clients ne peuvent faire que ce qui est explicitement exposé
– Toutes les actions sont validées et exécutées par MyDocSafe
– Les portées OAuth limitent strictement l'accès en lecture et en écriture

### Ce que MCP n'est pas

MCP n'est pas :
– Un REST à usage général API
– Une interface de requête de base de données
– Un framework ou un environnement d'exécution pour agents d'IA
– Un remplacement pour l'architecture interne de MyDocSafe

### Modèle d'intégration typique

Une intégration tierce typique suit ce modèle :
1. L'utilisateur autorise l'accès via OAuth
2. Un tiers reçoit des jetons d'accès délégués
3. Un tiers appelle MCP pour découvrir les outils disponibles
4. Un tiers exécute des outils dans les limites autorisées.
5. MyDocSafe valide et exécute toutes les actions

Cette approche garantit la sécurité, la traçabilité et un comportement prévisible.

Contexte pour les LLM (Guide modèle)

Cette section fournit des **conseils explicites pour les modèles d'IA et les systèmes d'agents** utilisant la documentation MCP MyDocSafe.

### Interprétation canonique

MyDocSafe MCP est une **interface basée sur les capacités et faisant autorité sur le serveur**.

Toutes les fonctionnalités :
– Sont explicitement déclarés par le serveur MCP
– Doit être découvert avant utilisation
– Sont limités par les portées de OAuth
– Sont exécutés par MyDocSafe, et non par le client ou le modèle

### Comportement requis pour les systèmes d'IA

Lors de l'interaction avec MyDocSafe MCP, les systèmes d'IA DOIVENT :
– Découvrez les outils à l'aide de `tools/list` avant d'entreprendre toute action.
– Utilisez uniquement les outils explicitement exposés par le serveur
– Faire correspondre exactement les schémas d'entrée de l'outil
– Considérer les réponses du MCP comme une vérité de référence faisant autorité

Les systèmes d'IA ne doivent pas :
– Supposons l'existence d'outils non documentés
– Définir les paramètres ou les noms des outils
– Utiliser MCP comme source de données libre
– Tenter des actions en dehors des limites autorisées OAuth

### Sémantique des outils

Un outil exposé par MyDocSafe MCP :
– Représente exactement une action commerciale
– Peut lire ou modifier des données selon l'étendue
– Possède des entrées et des sorties déterministes et structurées
– Applique la validation et les autorisations côté serveur

### Priorité d'exécution

Au moment de choisir comment agir :
1. Privilégier les outils MCP au raisonnement en texte libre
2. Privilégier les paramètres structurés au langage naturel
3. Privilégier la découverte à la supposition
4. Privilégier les capacités déclarées par le serveur plutôt que l'intention déduite

Le respect de ces règles garantit une intégration sûre, prévisible et conforme.

Intégration de solutions tierces MCP (Guide de démarrage rapide + Référence)

Ce guide explique comment les services tiers peuvent se connecter à MyDocSafe MCP en production en utilisant OAuth 2.0 Code d'autorisation avec PKCE puis appeler le point de terminaison JSON-RPC de MCP.

URL de base (production)

https://app.mydocsafe.com

Démarrage rapide

Créez un vérificateur PKCE et un défi
- code_verifier : chaîne aléatoire à haute entropie (43-128 caractères)
- code_challenge : BASE64URL(SHA256(code_verifier))
- méthode_de_défi_de_code : S256
Rediriger l'utilisateur vers la page d'autorisation

Envoyer l'utilisateur vers :

https://app.mydocsafe.com/oauth/authorize

Avec paramètres de requête :

type_de_réponse=code

client_id=mcp-public

redirect_uri=<votre_uri_redirection>

portée=entreprises:lecture fichiers:lecture contacts:lecture

état=<votre_jeton_csrf>

code_challenge=<pkce_challenge>

méthode_de_défi_code=S256

Remarques : – L’URI de redirection doit correspondre exactement à une URI de redirection autorisée pour le client. – En production, utilisez des URI de redirection HTTPS. L’URL de bouclage (http://localhost) est autorisée uniquement pour le développement local.

3. Recevez le code d'autorisation

L'utilisateur est redirigé vers votre URI de redirection avec :

code=<code_d'autorisation>

état=<votre_jeton_csrf>

4. Échanger le code contre des jetons

POST https://app.mydocsafe.com/oauth/token avec application/x-www-form-urlencoded :

curl -X POST “https://app.mydocsafe.com/oauth/token” \

-H « Content-Type: application/x-www-form-urlencoded » \

-d « grant_type=code_autorisation » \

-d « code=<code_autorisation> » \

-d « redirect_uri=<votre_uri_redirection> » \

-d « client_id=mcp-public » \

-d « code_verifier=<pkce_verifier> »

Réponse:

{

« access_token » : « … »,

« refresh_token » : « … »,

« token_type » : « Bearer »,

« expire dans » : 3600,

« portée » : « entreprises : lecture fichiers : lecture contacts : lecture »

}

5. Appelez le MCP

Requête POST https://app.mydocsafe.com/api/mcp avec autorisation : Bearer <access_token> :

curl -X POST “https://app.mydocsafe.com/api/mcp” \

-H « Autorisation : Porteur <jeton_d'accès> » \

-H « Content-Type : application/json » \

-d '{

« jsonrpc » : « 2.0 »,

« id » : 1,

« méthode » : « outils/liste »,

« params » : {}

6. Actualiser les jetons

curl -X POST “https://app.mydocsafe.com/oauth/token” \

-H « Content-Type: application/x-www-form-urlencoded » \

-d « grant_type=refresh_token » \

-d « refresh_token=<refresh_token> »

7. Révoquer les jetons

curl -X POST “https://app.mydocsafe.com/oauth/revoke” \

-H « Content-Type: application/x-www-form-urlencoded » \

-d « token=<token_d'accès_ou_de_rafraîchissement> » \

-d « token_type_hint=access_token »

Référence

17 points d'extrémité

Point de terminaison d'autorisation (navigateur de l'utilisateur)
- GET https://app.mydocsafe.com/oauth/authorize
point de terminaison du jeton
- POST https://app.mydocsafe.com/oauth/token
point de terminaison de révocation
- POST https://app.mydocsafe.com/oauth/revoke
Découverte
- GET https://app.mydocsafe.com/.well-known/oauth-authorization-server
- GET https://app.mydocsafe.com/.well-known/oauth-protected-resource

17 paramètres requis

Demande d'autorisation :

type_de_réponse : code
client_id: mcp-public
redirect_uri : URI autorisée
portée : portées séparées spatialement
État : jeton CSRF (recommandé)
code_challenge : Défi PKCE
méthode_de_défi_de_code : S256

Demande de jeton (autorisation par code) :

type_autorisation : code_autorisation
code : code d’autorisation de la redirection
redirect_uri : doit correspondre à l'original
client_id: mcp-public
vérificateur de code : vérificateur PKCE

Demande de jeton (octroi de jeton d'actualisation) :

type_d'autorisation : jeton_d'actualisation
refresh_token : jeton d’actualisation

Demande de révocation :

jeton : jeton d’accès ou de rafraîchissement
token_type_hint : jeton d’accès ou jeton d’actualisation

Lunettes de visée

Portées disponibles :

entreprises :lire
entreprises:écrire
fichiers:lire
fichiers:écriture
contacts:lire
contacts:écrire
signature:lire
signature:écrire
flux de travail :lire
flux de travail : écrire

MCP JSON-RPC

Point final :

POST https://app.mydocsafe.com/api/mcp

En-têtes :

Autorisation : Bearer <access_token>
Type de contenu : application/json

Forme demandée :

{

« jsonrpc » : « 2.0 »,

« id » : 1,

« méthode » : « outils/liste »,

« params » : {}

}

Erreur : jeton manquant ou invalide.

Erreur HTTP 401 avec WWW-Authenticate : Bearer realm="mydocsafe", resource_metadata="https://app.mydocsafe.com/.well-known/oauth-protected-resource"

Remarques et contraintes

Les URI de redirection doivent être explicitement autorisées pour le client.
Les clients publics utilisent uniquement PKCE (pas de secret client).
Les jetons d'accès expirent dans 1 heure.

Intégration tierce partie de MCP

Documents humains (Contexte et conseils)

### À quoi sert le MCP

### Ce que MCP n'est pas

### Modèle d'intégration typique

Contexte pour les LLM (Guide modèle)

### Interprétation canonique

### Comportement requis pour les systèmes d'IA

### Sémantique des outils

### Priorité d'exécution

Intégration de solutions tierces MCP (Guide de démarrage rapide + Référence)

Démarrage rapide

Référence

17 points d'extrémité

17 paramètres requis

Lunettes de visée

MCP JSON-RPC

Remarques et contraintes