Model Context Protocol (MCP) Service Endpoint

This service instance operates under the MCP framework and mandates prior user credential validation. Upon successful authentication, the MCP service gains the authority to invoke restricted APIs on behalf of the authenticated user.

Prerequisites & Setup

Dependent Todos API Service

Prior to initiating the MCP service, deployment of the Todos API is required, as detailed in the documentation found here.

Auth0 Identity Configuration

Within the Auth0 management portal, establish a new client application under the 'Applications' section (Application Type: "Regular Web Application").

When performing local development, ensure the following Uniform Resource Locator (URL) is registered as the redirection endpoint:

http://localhost:8788/callback

Key-Value Storage Namespace Provisioning

• Provision the required persistent storage namespace using the command: wrangler kv:namespace create "OAUTH_KV"
• Integrate the returned KV Identifier into your Wrangler configuration file.

Required Runtime Variables

This MCP Service instance necessitates the definition of several environment parameters:

Parameter	Explanation
AUTH0_DOMAIN	The fully qualified domain name of your Auth0 tenant (e.g., enterprise.auth0.com)
AUTH0_CLIENT_ID	The unique Client Identifier associated with the Auth0 application you provisioned
AUTH0_CLIENT_SECRET	The confidential Client Secret generated for the Auth0 application
AUTH0_AUDIENCE	The designated unique identifier for the target API, as registered within the Auth0 console (e.g., api:inventory-system)
AUTH0_SCOPE	The set of permissions requested by the MCP Service. This includes fundamental identity data (openid email profile), token refreshment capability (offline_access), and specific API permissions (read:inventory)
NODE_ENV	The operational environment context; utilize development for local iterative refinement
API_BASE_URL	The root endpoint URL where the dependent Todos API is accessible

Local Development Guide

To configure the local environment, fabricate a .dev.vars file in the project's root directory, adhering to this structural blueprint:

AUTH0_DOMAIN=yourdomain.cloud.auth0.com
AUTH0_CLIENT_ID=ClientIdentifierGoesHere
AUTH0_CLIENT_SECRET=SecretValueGoesHere
AUTH0_AUDIENCE=api:todos
AUTH0_SCOPE=openid email profile offline_access read:todos
NODE_ENV=development
API_BASE_URL=http://localhost:8789

Initiating the MCP Service for Testing

To commence the MCP service execution, execute the following script via your terminal:

npm run dev

For interactive validation, employ the MCP Inspector utility. Configure the Inspector to communicate via the sse transport protocol, pointing its connection URL to http://localhost:8788/sse.

Cloudflare Deployment Procedure

To host the MCP Service on the Cloudflare edge network, adhere to the following steps for configuring runtime secrets:

wrangler secret put AUTH0_DOMAIN
wrangler secret put AUTH0_CLIENT_ID
wrangler secret put AUTH0_CLIENT_SECRET
wrangler secret put AUTH0_AUDIENCE
wrangler secret put AUTH0_SCOPE
wrangler secret put API_BASE_URL

Once secrets are securely stored, deploy the service utilizing this command:

npm run deploy

Subsequently, update the Auth0 application settings by appending the production callback URL:

https://mcp-auth0-oidc.<your-subdomain>.workers.dev/callback

To validate the deployed endpoint, utilize the Cloudflare AI LLM Playground interface. Navigate to https://playground.ai.cloudflare.com/ and establish a connection to your service endpoint in the lower-left panel, employing this URL format:

https://mcp-auth0-oidc.<your-subdomain>.workers.dev/sse

This action will trigger a sign-in prompt, granting access to all provisioned tools post-successful credential verification.

Debugging and Error Resolution

Should setup or operational challenges arise, consult these diagnostic pathways:

Worker Execution Traces

Review the telemetry data via the Cloudflare Workers Logs interface within your management console.

Auth0 Transaction Records

• Navigate to the 'Logs' section within the Auth0 administrative panel.
• Scrutinize records pertaining to authentication attempts and subsequent failure states.

Recurrent Issues

• Authentication failure suggests a misalignment in Auth0 parameters or improperly configured secrets.
• Connection instability indicates the Worker may not be actively deployed or the endpoint domain is erroneous.
• Confirm all registered redirect URIs within Auth0 are precisely configured.
• Validate that the API_BASE_URL accurately targets the operational API endpoint.