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
- The client calls
https://mcp.oxygenius.be/mcpwithout a token: the server answers 401 with the address of its metadata. - The client reads the Protected Resource Metadata (RFC 9728): it names the Oxygenius authorization server.
- The client reads the authorization server metadata and starts the authorization code + PKCE flow, with
resource=https://mcp.oxygenius.be/mcp(RFC 8707). - The user signs in with their Oxygenius account and allows access; the client gets an access token (and a refresh token).
- 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
| Document | Address |
|---|---|
| Protected Resource Metadata | https://mcp.oxygenius.be/.well-known/oauth-protected-resource/mcp |
| Authorization server | The 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
- Pre-registered clients: the server does not use dynamic client registration (DCR). Claude uses the Oxygenius client registered for the connector; any other client asks support for its client ID.
- Claude redirect URLs:
https://claude.ai/api/mcp/auth_callbackandhttps://claude.com/api/mcp/auth_callback. - Flow: authorization code with PKCE and refresh token (the user stays connected without signing in at every session).
- Scopes: no specific scope is required; access is governed by the user's Oxygenius permissions.
Tokens
- JWTs signed (RS256) by the Oxygenius authorization server; issuer, signature and expiry are checked on every request.
- Dedicated audience: the token audience must be exactly the MCP server URL. A token of the Oxygenius web application is refused by the MCP server, and a token issued to an assistant does not open the application's API.
- Short lifetime; the client renews it with its refresh token.
- The server never logs a token. To write, it calls the Oxygenius API on the user's behalf with a separate short-lived API token, obtained from the Oxygenius authorization server by token exchange, or signed by the MCP server itself; that token is never returned to the MCP client and only opens the API operations designed for the MCP server.
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):
- a user unknown or deactivated in Oxygenius;
- a user attached to several companies, or an identifier shared by several accounts;
- an inactive company, or one that has not enabled the connector (Settings → AI integration).
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.
- Write tools: on top of the permission, the company must have turned on Allow write tools.
- Stock module:
get_item_stockalso requires the Stock licence module. - No permission:
get_my_profile, which only returns the user's own data. - Fine-grained visibility: other users' private events are masked, e-mails are limited to the mailboxes shared with the user when the company requires it, document types are limited by role, purchase prices require the
profitability.data.viewpermission.
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.
HTTP refusals
| Code | Cause | What to do |
|---|---|---|
401 | Token missing, expired, or for another audience. | The client renews the token or signs in again. |
403 | User or company refused (see above). | Check that the connector is enabled and the account. See Troubleshooting. |
413 | Request larger than 64 KB. | MCP messages are small: reduce the request. |
429 | More than 60 requests per minute for the user. | Wait a minute. |
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.