Authentication & access

The server follows the MCP authorization specification: OAuth 2.1 with Oxygenius's authorization server (Auth0), discovered from the protected resource. Every call carries the user's token; the company and rights are derived from it on every request.

Flow

  1. The client calls https://mcp.oxygenius.be/mcp without a token: the server answers 401 with the address of its metadata.
  2. The client reads the Protected Resource Metadata (RFC 9728): it names the Oxygenius authorization server.
  3. The client reads the authorization server metadata and starts the authorization code + PKCE flow, with resource=https://mcp.oxygenius.be/mcp (RFC 8707).
  4. The user signs in with their Oxygenius account and allows access; the client gets an access token (and a refresh token).
  5. The client calls the server with Authorization: Bearer …. The server validates the token, resolves the user and their company, then filters the tools by their permissions.
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://mcp.oxygenius.be/.well-known/oauth-protected-resource/mcp"

Discovery

DocumentAddress
Protected Resource Metadatahttps://mcp.oxygenius.be/.well-known/oauth-protected-resource/mcp
Authorization serverThe one given by authorization_servers; its metadata is published at the standard location (/.well-known/openid-configuration).

Example metadata (the authorization server domain is given by the live document):

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

OAuth clients

Tokens

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"}

User and company

The user identifier in the token is matched, on every request, to their Oxygenius account and then to their company. No tool accepts a company, database or user identifier as a parameter. The server refuses (403):

The refusal happens before any MCP message: a refused user does not even see the tool list.

Permissions per tool

Each tool requires the same permission as the matching screen of the Oxygenius application; these are permissions, never roles. A tool whose rule is not met is not listed by tools/list and calling it is refused. In a detail, linked documents (invoices of an estimate, estimates of an event…) only appear with their own permission.

Oxygenius permission required by each tool. Any one of a tool's permissions is enough; a permission marked "in addition" is required on top of it.

PermissionTools
all-mail.list.view
Mailbox › all mail
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
Hybrid calendar
create_calendar_event, get_agenda_lists, get_calendar_event, search_calendar_events, update_calendar_event
calendar.list.view
Calendar
create_calendar_event, get_agenda_lists, get_calendar_event, search_calendar_events, update_calendar_event
credit-note.list.view
Credit notes › list
add_credit_note_lines, create_credit_note (in addition), 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
Dashboard › Tasks widget
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
Project detail › new credit note
create_credit_note
dossier-detail.dossier.edit
Project detail › edit
get_reference_lists, search_users, update_dossier
dossier-detail.estimate.create
Project detail › new estimate
create_estimate
dossier-detail.invoice.create
Project detail › new invoice
create_invoice
dossier-detail.tab.document
Project detail › Documents tab
get_document_download_link, list_dossier_documents, read_document
dossier-detail.tab.mailbox
Project detail › Mails tab
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
Project detail › Tasks tab
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
Projects › detail
get_dossier, list_dossier_documents (in addition), list_dossier_emails (in addition), update_dossier (in addition)
dossier.list.view
Projects › list
search_dossiers
dossier.new-dossier.create
Projects › new project
create_dossier, get_reference_lists, search_users
estimate.list.view
Estimates › list
accept_estimate, add_estimate_lines, create_estimate (in addition), 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
Invoices › list
add_invoice_lines, create_invoice (in addition), 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
Items and assemblies › list
get_item, get_item_stock, search_items
mail-inbox.list.view
Mailbox › inbox
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
Mailbox › sent items
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
Mailbox › outbox
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
Mailbox › deleted items
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 › send
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
Third parties › list
get_tiers, search_tiers
tiers.new-tiers.create
Third parties › new third party
check_vat, create_tiers, get_reference_lists
tiers.tiers.edit
Third parties › edit
check_vat, get_reference_lists, update_tiers

HTTP refusals

CodeCauseWhat to do
401Token missing, expired, or for another audience.The client renews the token or signs in again.
403User or company refused (see above).Check that the connector is enabled and the account. See Troubleshooting.
413Request larger than 64 KB.MCP messages are small: reduce the request.
429More than 60 requests per minute for the user.Wait a minute.
What about tool errors?

A refusal specific to a tool (permission, document that can no longer change, invalid parameter…) is not an HTTP error: the tool returns an isError: true result with an explicit message. See Technical reference.