Skip to main content

Integrate WorkOS with MCP Servers

This guide explains how to add WorkOS authentication to MCP servers using an API-first approach. You will deploy authentication directly from an OpenAPI (Swagger) specification without writing backend code.

Requires the Enterprise Auth plugin

Interactive OAuth2 — the flow this guide walks through — is a licensed feature in v1: it needs the @mcp-com-ai/enterprise-plugin-auth plugin and a core.enterprise/auth.oauth-broker entitlement installed alongside the free, open-source HAPI CLI. See What's New in v1: Authentication & Licensing before following the steps below.

Introduction​

WorkOS provides enterprise authentication for applications. MCP servers require authentication to secure MCP Tools and user access. This guide shows how to connect WorkOS authentication to MCP servers using OpenAPI specifications and the HAPI server.

Prerequisites​

Before you begin, ensure you have the following:

Configure WorkOS​

You must configure WorkOS to enable authentication for your MCP server.

  1. Create an organization and add users in WorkOS.
  2. Create a WorkOS application and enable Dynamic Client Registration (DCR).
  3. Set up redirect URIs to the Application (MCP Inspector or your MCP client).
tip

Dynamic Client Registration allows MCP servers to register applications in WorkOS automatically if no client ID is provided.

Define API Security in OpenAPI Specification​

Extend your OpenAPI specification to include authentication and CORS settings.

  1. Add a security definition for OAuth2, specifying the client ID, authorization URL, and token URL.
  2. Configure CORS to allow requests from the MCP Client.
tip

WorkOS provides a .well-known authorization endpoint. If your API does not provide a .well-known authorization endpoint, HAPI server generates one automatically.

Start the MCP Server​

Start the MCP server using your OpenAPI specification.

hapi serve demo -f "api.yaml" --headless
# or
hapi serve https://docs.mcp.com.ai/apis/openapi/demo.yaml -f "api.yaml" --headless

Example files:

This command loads your API spec with security and runs the MCP server in headless mode for backend integration.

Connect MCP Server to WorkOS​

You can authorize Apps (MCP Clients) with WorkOS (Authorization Server) in two ways:

Authenticate with Client ID​

  1. Provide the WorkOS client ID in your configuration.
  2. Users log in through WorkOS (for example, only users from @example.com).
  3. MCP application Client is approved.

Authenticate with Dynamic Registration​

  1. Remove the client ID from your configuration.
  2. Start the authentication process.
  3. WorkOS automatically registers a new application for your MCP.

WorkOS creates a new application entry (such as "MCP Inspector") without manual dashboard changes.

Review Authentication in WorkOS​

After authentication, verify the following events in the WorkOS dashboard:

  • Users are authenticated successfully.
  • Applications is dynamically created, if using DCR.

WorkOS Dashboard Events

Demo Authentication with WorkOS​

Wrapping Up​

You have integrated WorkOS authentication with MCP servers using OpenAPI specifications and the HAPI server. This approach enables secure, API-driven deployments without backend code.

You can now deploy MCP servers with authentication quickly and efficiently.

With the HAPI Server, you can:

  • Deploy MCP servers straight from OpenAPI specifications (OAS).
  • Add authentication via WorkOS.
  • Do it all without writing a single line of backend code.

This makes it incredibly fast to go from API spec → secure MCP server.

note

To request integration with another API or authentication provider, contact the team.

Be-HAPI and go rebels! ✊🏽