Using Liferay as an MCP Server

Liferay DXP 2026.Q3+ Release Feature

The Model Context Protocol (MCP) is an open source standard for connecting AI applications like GitHub Copilot or Cursor to external tools and data. Liferay DXP can function as an MCP server that AI applications can connect to. To turn it on, enable the LPD-63311 feature flag, and then enable the MCP Server configuration. You can then configure any AI service that supports MCP to interact with Liferay DXP.

The MCP server accepts two authentication schemes on /o/mcp: basic authentication and OAuth 2.0 bearer tokens. For basic authentication, encode the credentials to create a token and pass it in the Authorization header. For bearer tokens, see Connecting with OAuth 2.0.

Important

Both schemes identify the Liferay DXP user behind the request, and the AI client operates with that user’s permissions.

Enabling the MCP Server

The MCP Server configuration applies to a single virtual instance, and it’s disabled by default. If you run more than one virtual instance, enable it only in the instances that serve MCP requests.

Enable the LPD-63311 release feature flag. The MCP Server entry does not appear in Instance Settings until you enable this flag.
Go to Control Panel → Instance Settings → Platform → MCP Server.
Check Enabled and click Save.

Disabling the MCP Server

To disable the MCP Server, go to Control Panel → Instance Settings → Platform → MCP Server, clear Enabled, and click Save.

Once disabled, requests to /o/mcp return 404 for the virtual instance. AI applications configured against that instance can no longer reach Liferay DXP, and other virtual instances are unaffected.

Configuring GitHub Copilot

Note

Configuring GitHub Copilot requires using Visual Studio Code.

Follow these steps for VS Code.

When you add the mcp.json file, save this configuration for Liferay DXP:

{
  "servers": {
    "liferay": {
      "url": "http://localhost:8080/o/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Basic [basic auth token]"
      }
    }
  }
}

Configuring Cursor

Follow the Quickstart steps and set up an MCP server in the Cursor application.

The MCP server configuration is in [home directory]/.cursor/mcp.json by default. Save this configuration in the file to use Liferay DXP:

{
  "mcpServers": {
    "liferay": {
      "url": "http://localhost:8080/o/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Basic [basic auth token]",
        "Content-Type": "application/json"
      }
    }
  }
}

Configuring Claude Desktop

Follow these instructions.

Open the developer settings in the Claude Desktop application to access the server configuration, in claude_desktop_config.json. Save this configuration to use Liferay DXP:

{
  "mcpServers": {
    "liferay": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:8080/o/mcp",
        "--header",
        "Authorization: Basic [basic auth token]"
      ]
    }
  }
}

Configuring Gemini CLI

Follow these instructions.

When you add the settings.json file, save this configuration for Liferay DXP:

{
  "mcpServers": {
    "liferay": {
      "httpUrl": "http://localhost:8080/o/mcp",
      "headers": {
        "Authorization": "Basic [basic auth token]"
      }
    }
  }
}

Connecting with OAuth 2.0

Liferay DXP issues Bearer tokens through its OAuth 2.0 authorization server, and the MCP server validates them itself rather than delegating to Liferay DXP’s usual REST authentication. See Using OAuth 2.0 and Creating an OAuth 2.0 Application.

To use a bearer token with any of the above clients, replace the Basic [basic auth token] value with Bearer [access token].

Bearer tokens are only valid for the resources listed in its audience. The MCP server’s resource URI combines your Liferay DXP instance’s base URL, the path context, and /o/mcp. On a default installation the path context is empty, making it http://localhost:8080/o/mcp. A client requests that audience by sending the URI as the resource parameter when it requests the token. The MCP server rejects any token that lacks this audience, even one that works for Liferay DXP’s other REST APIs.

Discovering the Authorization Server

A request to /o/mcp with no Authorization header returns 401 with this response header:

WWW-Authenticate: Bearer realm="mcp", resource_metadata="http://localhost:8080/o/.well-known/oauth-protected-resource/mcp"

A disabled server returns 404, so a 401 confirms the server is running. An MCP client follows the resource_metadata URL to discover the authorization server.

Important

The resource_metadata endpoint requires the RFC 8414: Authorization Server Metadata release feature flag (LPD-63415) in addition to LPD-63311. Without it, the endpoint returns 404 and a client cannot complete discovery.

Why Tokens Are Rejected

A rejected Authorization header on /o/mcp returns 401 with error="invalid_token" and one of these error_description values:

Error Description	Cause
`Authorization header is not a bearer token`	The `Authorization` header is present, but it begins with neither `Basic` nor `Bearer`.
`Access token is unknown or revoked`	No matching authorization exists, the authorization belongs to a different virtual instance, or the authorization’s stored token content has been invalidated. The server also returns this description when the token resolves to a missing user or a guest user, which it checks after validating the audience.
`Access token has expired`	The token’s expiration date has passed.
`Access token is not bound to this MCP server`	The token’s audience list does not contain the MCP server resource URI.

Debugging with the Official MCP Inspector

Once you’ve configured your server, you can use the official MCP inspector to test and debug it.

Start the inspector by running

npx @modelcontextprotocol/inspector

Configure the inspector with these parameters:

URL: http://localhost:8080/o/mcp

Transport: Streamable HTTP

Headers: Authorization: Basic [basic auth token] or Authorization: Bearer [access token]

Feature Availability

Liferay Version	Feature Status	Feature Flag Label	Dependencies
Liferay DXP 2025.Q4	Beta	Liferay Model Context Protocol (MCP) Server (LPD-63311)	N/A
Liferay DXP 2026.Q3	Release	Liferay Model Context Protocol (MCP) Server (LPD-63311)	Release LPD-63415, for OAuth 2.0 discovery only

Resource Type:

Official Documentation

Deployment Approach:

Liferay PaaS

Liferay SaaS

Liferay Self-Hosted