Skip to main content

Authentication with the ONLYOFFICE Apps MCP Server

The ONLYOFFICE Apps MCP server acts as an OAuth proxy between MCP clients and the ONLYOFFICE Apps authorization server, handling compatibility gaps in dynamic client registration and scope handling automatically.

Dynamic client registration​

The ONLYOFFICE Apps authorization server does not support OAuth dynamic client registration, which the MCP authorization specification relies on. Without this support, MCP clients cannot register themselves directly with the ONLYOFFICE Apps authorization server.

The MCP server addresses this limitation by operating in one of two modes:

  1. When configured with pre-defined OAuth credentials, the MCP server exposes a registration endpoint that returns these credentials to all MCP clients. All MCP clients effectively share the same OAuth application;
  2. When configured without pre-defined OAuth credentials, the MCP server expects users to provide their own OAuth client credentials through the MCP client interface.

The first mode is optional. The second mode is always available when OAuth is enabled.

Scope handling​

The MCP server modifies the OAuth flow to address scope-related compatibility issues between MCP clients and the ONLYOFFICE Apps authorization server:

  1. Some MCP clients request scopes that the ONLYOFFICE Apps authorization server does not recognize, causing the authorization server to reject the request. The MCP server ignores all scope parameters from incoming requests and omits them when forwarding to the authorization server. The ONLYOFFICE Apps authorization server interprets requests without scope parameters as requesting all scopes granted to the application;
  2. Some MCP clients validate scope values in token responses. When the ONLYOFFICE Apps authorization server returns all scopes granted to the application, these clients may fail or display errors if the returned scopes differ from those they requested. The MCP server removes scope values from token responses before returning them to MCP clients.

Users effectively operate with all permissions granted to the OAuth application, regardless of which scopes the MCP client originally requested.

How the MCP server addresses the ONLYOFFICE Apps authorization limitations​

The MCP server acts as an OAuth proxy to address these limitations by using the ONLYOFFICE Apps API to create an OAuth application and then using the client details to authenticate the MCP server-client connection.

To create an ONLYOFFICE Apps OAuth application, follow the steps in the ONLYOFFICE Apps OAuth application creation guide. When configuring the application, ensure the following settings are properly configured:

  • Redirect URIs: Set to the MCP server's callback endpoint. For the public instance, use https://mcp.onlyoffice.com/oauth/callback. For self-hosted instances, replace the base URL with your MCP server's URL;
  • Allowed Origins: Set to the MCP server's base URL. For the public instance, use https://mcp.onlyoffice.com. For self-hosted instances, use your MCP server's URL;
  • PKCE: Enable PKCE (Proof Key for Code Exchange) for the application.

After creating the application, note the Client ID and Client Secret values. Use these credentials to configure the MCP server or provide them through the MCP client interface.

Other authentication methods​

Aside from authenticating with OAuth, the ONLYOFFICE Apps MCP server also allows you to authenticate with:

  • API Key (Header)
  • Personal Access Token (PAT)
  • API key in Authorization header

Resolving authentication​

The authentication resolution process depends on the transport type used and the authentication methods configured. For detailed flowcharts of each scenario, see Authentication resolution.