Authentification et accès

Le serveur suit la spécification d'autorisation du protocole MCP : OAuth 2.1 avec le serveur d'autorisation d'Oxygenius (Auth0), découvert à partir de la ressource protégée. Chaque appel porte le jeton de l'utilisateur ; la société et les droits en sont déduits à chaque requête.

Déroulement

  1. Le client appelle https://mcp.oxygenius.be/mcp sans jeton : le serveur répond 401 avec l'adresse de ses métadonnées.
  2. Le client lit les métadonnées de ressource protégée (RFC 9728) : elles désignent le serveur d'autorisation d'Oxygenius.
  3. Le client lit les métadonnées du serveur d'autorisation et lance le flux code d'autorisation + PKCE, avec resource=https://mcp.oxygenius.be/mcp (RFC 8707).
  4. L'utilisateur se connecte avec son compte Oxygenius et autorise l'accès ; le client reçoit un jeton d'accès (et un jeton de rafraîchissement).
  5. Le client appelle le serveur avec Authorization: Bearer …. Le serveur valide le jeton, résout l'utilisateur et sa société, puis filtre les outils selon ses permissions.
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.oxygenius.be/.well-known/oauth-protected-resource/mcp"

Découverte

DocumentAdresse
Métadonnées de la ressource protégéehttps://mcp.oxygenius.be/.well-known/oauth-protected-resource/mcp
Serveur d'autorisationCelui indiqué par authorization_servers ; ses métadonnées sont publiées à l'emplacement standard (/.well-known/openid-configuration).

Exemple de métadonnées (le domaine du serveur d'autorisation est donné par le document réel) :

{
  "resource": "https://mcp.oxygenius.be/mcp",
  "authorization_servers": [
    "https://<tenant>.auth0.com/"
  ],
  "scopes_supported": [],
  "resource_name": "Oxygenius"
}

Clients OAuth

Jetons

POST /mcp HTTP/1.1
Host: mcp.oxygenius.be
Authorization: Bearer <access_token>
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

Utilisateur et société

L'identifiant de l'utilisateur contenu dans le jeton est rapproché, à chaque requête, de son compte Oxygenius, puis de sa société. Aucun outil n'accepte de société, de base de données ou d'identifiant d'utilisateur en paramètre. Le serveur refuse (403) :

Le refus intervient avant tout message MCP : un utilisateur refusé ne voit même pas la liste des outils.

Permissions par outil

Chaque outil exige la même permission que l'écran correspondant de l'application Oxygenius ; ce sont des permissions, jamais des rôles. Un outil dont la règle n'est pas satisfaite n'apparaît pas dans tools/list et son appel est refusé. Dans un détail, les documents liés (factures d'un devis, devis d'un événement…) n'apparaissent qu'avec leur propre permission.

Permission Oxygenius exigée par chaque outil. L'une des permissions d'un outil suffit ; une permission marquée « en plus » est exigée en plus de celle-ci.

PermissionOutils
all-mail.list.view
Messagerie › tous les mails
attach_documents_to_email, create_document_email, create_email_draft, get_document_download_link, get_email, get_my_emails, prepare_email_send, read_document, remove_email_attachments, search_emails, send_email, update_email_draft
calendar-hybrid.list.view
Calendrier hybride
create_calendar_event, get_agenda_lists, get_calendar_event, search_calendar_events, update_calendar_event
calendar.list.view
Calendrier
create_calendar_event, get_agenda_lists, get_calendar_event, search_calendar_events, update_calendar_event
credit-note.list.view
Notes de crédit › liste
add_credit_note_lines, create_credit_note (en plus), finalize_credit_note, get_credit_note, prepare_accountant_send, prepare_credit_note_finalization, remove_credit_note_lines, search_credit_notes, send_to_accountant, update_credit_note, update_credit_note_lines
dashboard.tasksWidget.view
Tableau de bord › widget Tâches
create_task, get_my_tasks, get_task, list_task_types, reply_task, search_tasks, search_users, set_task_pinned, transfer_task, update_my_task
dossier-detail.credit-note.create
Détail du dossier › nouvelle note de crédit
create_credit_note
dossier-detail.dossier.edit
Détail du dossier › modifier
get_reference_lists, search_users, update_dossier
dossier-detail.estimate.create
Détail du dossier › nouveau devis
create_estimate
dossier-detail.invoice.create
Détail du dossier › nouvelle facture
create_invoice
dossier-detail.tab.document
Détail du dossier › onglet Documents
get_document_download_link, list_dossier_documents, read_document
dossier-detail.tab.mailbox
Détail du dossier › onglet Mails
attach_documents_to_email, create_document_email, create_email_draft, get_document_download_link, get_email, get_my_emails, list_dossier_emails, prepare_email_send, read_document, remove_email_attachments, search_emails, send_email, update_email_draft
dossier-detail.tab.task
Détail du dossier › onglet Tâches
create_task, get_my_tasks, get_task, list_task_types, reply_task, search_tasks, search_users, set_task_pinned, transfer_task, update_my_task
dossier.details.view
Dossiers › détail
get_dossier, list_dossier_documents (en plus), list_dossier_emails (en plus), update_dossier (en plus)
dossier.list.view
Dossiers › liste
search_dossiers
dossier.new-dossier.create
Dossiers › nouveau dossier
create_dossier, get_reference_lists, search_users
estimate.list.view
Devis › liste
accept_estimate, add_estimate_lines, create_estimate (en plus), create_estimate_version, get_estimate, prepare_estimate_decision, print_estimate, refuse_estimate, remove_estimate_lines, search_estimates, update_estimate, update_estimate_lines
invoice.list.view
Factures › liste
add_invoice_lines, create_invoice (en plus), finalize_invoice, get_invoice, get_reference_lists, prepare_accountant_send, prepare_invoice_finalization, remove_invoice_lines, search_invoices, send_to_accountant, update_invoice, update_invoice_lines
item-job.list.view
Articles et ouvrages › liste
get_item, get_item_stock, search_items
mail-inbox.list.view
Messagerie › boîte de réception
attach_documents_to_email, create_document_email, create_email_draft, get_document_download_link, get_email, get_my_emails, prepare_email_send, read_document, remove_email_attachments, search_emails, send_email, update_email_draft
mail-outbox.list.view
Messagerie › éléments envoyés
attach_documents_to_email, create_document_email, create_email_draft, get_document_download_link, get_email, get_my_emails, prepare_email_send, read_document, remove_email_attachments, search_emails, send_email, update_email_draft
mail-sendbox.list.view
Messagerie › boîte d'envoi
attach_documents_to_email, create_document_email, create_email_draft, get_document_download_link, get_email, get_my_emails, prepare_email_send, read_document, remove_email_attachments, search_emails, send_email, update_email_draft
mail-trashbox.list.view
Messagerie › corbeille
attach_documents_to_email, create_document_email, create_email_draft, get_document_download_link, get_email, get_my_emails, prepare_email_send, read_document, remove_email_attachments, search_emails, send_email, update_email_draft
peppol.all.send
Peppol › envoyer
prepare_peppol_send, send_peppol
planning.list.view
Planning
create_planning_event, get_agenda_lists, get_planning_event, search_planning_events, update_planning_event
tiers.list.view
Tiers › liste
get_tiers, search_tiers
tiers.new-tiers.create
Tiers › nouveau tiers
check_vat, create_tiers, get_reference_lists
tiers.tiers.edit
Tiers › modifier
check_vat, get_reference_lists, update_tiers

Réponses HTTP de refus

CodeCauseQue faire
401Jeton absent, expiré, ou d'une autre audience.Le client renouvelle le jeton ou relance la connexion.
403Utilisateur ou société refusés (voir ci-dessus).Vérifier l'activation du connecteur et le compte. Voir Dépannage.
413Requête de plus de 64 Ko.Les messages MCP sont petits : réduire la requête.
429Plus de 60 requêtes par minute pour l'utilisateur.Patienter une minute.
Et les erreurs d'un outil ?

Un refus propre à un outil (permission, document non modifiable, paramètre invalide…) n'est pas une erreur HTTP : l'outil renvoie un résultat isError: true avec un message explicite. Voir Référence technique.