Model Context Protocol (MCP) Server + WorkOS AuthKit

This is an example Model Context Protocol (MCP) server that allows remote clients to connect and authenticate using WorkOS AuthKit.

AuthKit supports user management features including an organization-centric authentication model allowing you to control tool access based on user and organization permissions.

[!WARNING] This is a demo template designed to help you get started quickly. While we have implemented several security controls, you must implement all preventive and defense-in-depth security measures before deploying to production. Please review our comprehensive security guide: Securing MCP Servers

Getting Started

First to create a WorkOS account by signing into the WorkOS Dashboard.

Next, add the MCP server's callback URL as a Redirect URI under Redirects -> Sign in callback. If you are testing locally, this will be http://localhost:8788/callback, or if deployed, the domain of your deployed worker with the same /callback path.

Next, you must set the WORKOS_CLIENT_ID, WORKOS_CLIENT_SECRET, and COOKIE_ENCRYPTION_KEY environment variables. The WorkOS credentials can be obtained from the WorkOS Dashboard under API Keys.

You can set these in the Cloudflare dashboard or using the wrangler CLI:

$ npx wrangler secret put WORKOS_CLIENT_ID <your_workos_client_id>
$ npx wrangler secret put WORKOS_CLIENT_SECRET <your_workos_client_secret>
$ npx wrangler secret put COOKIE_ENCRYPTION_KEY # add any random string here e.g. openssl rand -hex 32

Note: The WORKOS_CLIENT_ID isn't technically a secret and so you may also choose to set it via your wrangler.jsonc configuration file. But WORKOS_CLIENT_SECRET and COOKIE_ENCRYPTION_KEY are not public and should be securely set elsewhere.

Set up a KV namespace

Create a KV namespace for OAuth state storage:

$ npx wrangler kv namespace create OAUTH_KV

Update the KV namespace in the wrangler.jsonc file with the ID you receive:

"kv_namespaces": [
  {
    "binding": "OAUTH_KV",
    "id": "your-kv-namespace-id"
  }
]

And that's it! You can now test out your remote MCP server using the example playground below.

Testing MCP Authentication

Visit the Cloudflare Workers AI playground and enter the URL of your worker:

# Local
http://localhost:8788/sse

# Deployed
https://<your-worker-domain>/sse

After clicking Connect, you'll be redirected to your WorkOS AuthKit domain, where you can sign-in, and be returned to the playground authenticated as a WorkOS AuthKit user.

In the demo code, the generateImage tool is gated behind the image_generation permission. You can read more about Permissions in AuthKit here. Try assigning a permission with the image_generation slug to your user to see how it enables additional tools in the playground.