---
sidebar_label: Authentication
sidebar_position: 3
title: 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](https://api.onlyoffice.com/docspace/api-backend/get-started/authentication/oauth2/creating-oauth-app.md).
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.](https://api.onlyoffice.com/docspace/mcp-server/getting-started/clients.md)

## 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](https://api.onlyoffice.com/docspace/mcp-server/reference/authentication-resolution.md).
