Remote MCP Entra Id Todo

🚀 Model Context Protocol (MCP) Server + Microsoft Entra ID OAuth + Todo Management

This project presents a Model Context Protocol (MCP) server that enables remote MCP connections. It comes with built - in Microsoft Entra ID (formerly Azure AD) OAuth and offers comprehensive Microsoft To Do task management capabilities. You can deploy it to your Cloudflare account. After creating your own Azure AD OAuth application, you'll have a fully - functional remote MCP server. Users can connect to your MCP server by signing in with their Microsoft accounts and manage their To Do lists, create tasks, set reminders, and more. This can also serve as a reference for integrating other OAuth providers with an MCP server deployed on Cloudflare, using the [workers - oauth - provider library](https://github.com/cloudflare/workers - oauth - provider).

The MCP server, powered by Cloudflare Workers, acts as an OAuth Server for MCP clients and an OAuth Client for Microsoft Entra ID's OAuth services. It securely stores tokens and authentication state in KV storage.

🚀 Quick Start

📦 Installation

First, clone the repo and install dependencies:

npm install

🌐 For Production

Create a new Azure AD Application

1. Navigate to Azure Portal → Azure Active Directory → App registrations.
2. Click New registration.
3. Configure the following:
   • Name: MCP Entra OAuth Todo Server
   • Supported account types:
     • For multi - tenant support (recommended): Select "Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts".
     • For single - organization use: Choose "Accounts in this organizational directory only".
   • Redirect URI:
     • Type: Web
     • URI: https://remote - mcp - entra - oauth - todo.<your - subdomain>.workers.dev/callback
     • Also add: http://localhost:8789/callback (for development).
4. After registration, note down the Application (client) ID and Directory (tenant) ID.
5. Create a client secret:
   • Go to Certificates & secrets → New client secret.
   • Immediately copy the secret value (you won't see it again).
6. Configure API permissions:
   • Navigate to API permissions → Add a permission → Microsoft Graph → Delegated permissions.
   • Add User.Read (for signing in and reading user profiles) and Tasks.ReadWrite (for reading and writing user tasks).
   • Click Grant admin consent for your organization.

   💡 Usage Tip

   The code uses the https://graph.microsoft.com/.default scope, which dynamically requests all pre - consented permissions. To add new tools or permissions, simply add them in the Azure Portal and grant consent; no code changes are required.

7. Set secrets via Wrangler:

wrangler secret put ENTRA_CLIENT_ID
wrangler secret put ENTRA_CLIENT_SECRET
wrangler secret put ENTRA_TENANT_ID  # Use 'common' for multi - tenant, or your specific tenant ID
wrangler secret put COOKIE_ENCRYPTION_KEY # add any random string here e.g. openssl rand - hex 32
wrangler secret put DEFAULT_TIMEZONE # optional, defaults to Europe/London

⚠️ Important Note

Multi - Tenant Configuration: When setting ENTRA_TENANT_ID, use common to support both work/school accounts and personal Microsoft accounts (recommended for multi - tenant). Use organizations for work/school accounts only, consumers for personal accounts only, or your specific tenant ID for a single organization. For multi - tenant apps, using common ensures tokens are issued in the user's home tenant context, allowing access to personal resources like To Do lists.

When creating the first secret, Wrangler will prompt you to create a new Worker. Enter "Y" to create a new Worker and save the secret.

Set up a KV namespace

• Create the KV namespace:

wrangler kv namespace create "OAUTH_KV"

• Update the Wrangler file with the KV ID.

Deploy & Test

Deploy the MCP server to make it available on your workers.dev domain:

wrangler deploy

Test the remote server using Inspector:

npx @modelcontextprotocol/inspector@latest

Enter https://remote - mcp - entra - oauth - todo.<your - subdomain>.workers.dev/mcp and click connect. After completing the authentication flow, you'll see the tools working.

🔌 Access the remote MCP server from Claude Desktop

Open Claude Desktop and go to Settings -> Developer -> Edit Config. Replace the content with the following configuration:

{
  "mcpServers": {
    "entra - todo": {
      "command": "npx",
      "args": [
        "mcp - remote",
        "https://remote - mcp - entra - oauth - todo.<your - subdomain>.workers.dev/mcp"
      ]
    }
  }
}

Restart Claude Desktop. A browser window will open showing the OAuth login page. Complete the authentication flow to grant Claude access to your MCP server. After access is granted, the tools will be available for use. You can then ask Claude to perform tasks like:

• "Show me all my todo lists"
• "Create a new list called 'Shopping'"
• "Add a task 'Buy groceries' to my Shopping list with a due date of tomorrow at 5pm"
• "What tasks do I have in my Work list?"
• "Update the task 'Call client' to be high importance and due Friday"
• "Mark the 'Submit report' task as completed"
• "Set a reminder for my 'Team meeting prep' task for tomorrow at 9am"
• "Delete all completed tasks from my Personal list"

💻 For Local Development

If you want to develop and test your MCP server locally, create another OAuth App in Azure AD:

• Set the Homepage URL to http://localhost:8789.
• Set the Authorization callback URL to http://localhost:8789/callback.
• Note your Client ID and generate a Client secret.
• Create a .dev.vars file in your project root with the following content:

ENTRA_CLIENT_ID=your_development_azure_ad_client_id
ENTRA_CLIENT_SECRET=your_development_azure_ad_client_secret
ENTRA_TENANT_ID=common  # Use 'common' for multi - tenant, or your specific tenant ID
COOKIE_ENCRYPTION_KEY=any_random_string_here
DEFAULT_TIMEZONE=Europe/London

Develop & Test

Run the server locally:

wrangler dev

To test the local server, enter http://localhost:8789/mcp into Inspector and click connect. After following the prompts, you can "List Tools".

Using Claude and other MCP Clients

When using Claude to connect to your remote MCP server, you may encounter error messages because Claude Desktop doesn't fully support remote MCP servers yet. To verify the connection, hover over the 🔨 icon in the bottom - right corner of Claude's interface; the tools should be available there.

To connect Cursor with your MCP server, choose Type: "Command" and combine the command and args fields into one (e.g., npx mcp - remote https://<your - worker - name>.<your - subdomain>.workers.dev/mcp). Note that while Cursor supports HTTP+SSE servers, it doesn't support authentication, so you still need to use mcp - remote and a STDIO server.

You can connect your MCP server to other MCP clients like Windsurf by opening the client's configuration file, adding the same JSON used for Claude setup, and restarting the MCP client.

🔧 Technical Details

OAuth Provider

The OAuth Provider library is a complete OAuth 2.1 server implementation for Cloudflare Workers. It manages the OAuth flow, including token issuance, validation, and storage. In this project, it authenticates MCP clients, manages the connection to Microsoft Entra ID's OAuth services, and securely stores tokens and authentication state in KV storage.

Durable MCP

Durable MCP extends the base MCP functionality using Cloudflare's Durable Objects. It provides persistent state management, secure storage of authentication context between requests, access to authenticated user information via this.props, and support for conditional tool availability based on user identity.

MCP Remote

The MCP Remote library enables the server to expose tools for MCP clients like the Inspector. It defines the communication protocol, provides a structured way to define tools, handles request and response serialization, and supports both Streamable HTTP (recommended) and Server - Sent Events (SSE) protocols.

🚚 Transport Protocol Migration

This example now supports the new Streamable HTTP transport protocol, replacing the deprecated Server - Sent Events (SSE) protocol. The server exposes two endpoints:

• /mcp - Recommended: Uses the new Streamable HTTP protocol.
• /sse - Deprecated: Legacy SSE protocol (maintained for backward compatibility).

All new integrations should use the /mcp endpoint. The SSE endpoint will be removed in a future version.

💻 Usage Examples

You can ask Claude to assist with various tasks, such as:

• "Show me all my todo lists"
• "Create a new list called 'Shopping'"
• "Add a task 'Buy groceries' to my Shopping list with a due date of tomorrow at 5pm"
• "What tasks do I have in my Work list?"
• "Update the task 'Call client' to be high importance and due Friday"
• "Mark the 'Submit report' task as completed"
• "Set a reminder for my 'Team meeting prep' task for tomorrow at 9am"
• "Delete all completed tasks from my Personal list"

➕ Adding New Tools

Adding new tools is straightforward thanks to the .default scope used in the OAuth flow:

1. Add permission in Azure Portal:
   • Navigate to your app → API permissions.
   • The Tasks.ReadWrite permission is already included for todo functionality.
   • Grant admin consent if not already done.
2. Add tool in code ():

this.server.tool(
  "getTodoTaskList",
  "Get details of a specific todo task list",
  {
    listId: z.string().describe("The ID of the todo list to retrieve"),
  },
  async ({ listId }) => {
    const client = Client.init({
      authProvider: (done) => {
        done(null, this.props!.accessToken);
      },
    });

    try {
      const taskList = await client
        .api(`/me/todo/lists/${listId}`)
        .get();

      return {
        content: [{ text: JSON.stringify(taskList, null, 2), type: "text" }],
      };
    } catch (error) {
      return {
        content: [{
          text: `Error: ${error instanceof Error ? error.message : String(error)}`,
          type: "text"
        }],
        isError: true,
      };
    }
  }
);

3. Deploy:

npm run deploy

🔒 Security Notes

• ✅ The client secret is stored as a Cloudflare Workers secret, ensuring it's never exposed to clients.
• ✅ The OAuth state parameter prevents CSRF attacks.
• ✅ HMAC - signed cookies are used for approval dialog persistence.
• ✅ Access tokens are encrypted in the MCP session token.
• ✅ All communication is over HTTPS.
• ✅ The approval dialog shows client information before authorization.

🛠️ Troubleshooting

"Failed to fetch access token"

• Check that the client secret is correct and not expired in the Azure Portal.
• Verify that the redirect URI matches exactly, including the protocol and port.
• Ensure that ENTRA_TENANT_ID is correct.

"Tasks.ReadWrite permission denied"

• Make sure admin consent has been granted in the Azure Portal.
• Check that the user has appropriate permissions in Azure AD.
• Verify that the permission was added as a Delegated permission, not an Application permission.

"Invalid tenant"

• Verify that ENTRA_TENANT_ID is correct in your secrets.
• For multi - tenant apps, use common to support both work/school and personal accounts.
• Use organizations for work/school accounts only or consumers for personal accounts only.
• Ensure the tenant ID matches the one shown in the Azure Portal if using a specific tenant.
• Important for guest users: If users are guests in your tenant but accessing personal resources like To Do, use common so tokens are issued in their home tenant context.

Connection issues in Claude Desktop

• Restart Claude Desktop after updating the configuration.
• Check that the Worker URL is correct and accessible.
• Verify that all secrets are set correctly using wrangler secret list.

Timezone issues with tasks

• Verify that DEFAULT_TIMEZONE is set correctly in your secrets.
• Use standard timezone names (e.g., America/New_York, not EST).
• You can override the default timezone per task by specifying it in the tool parameters.

🏗️ Architecture

This implementation follows the standard OAuth 2.0 Authorization Code Flow:

1. User opens MCP client → The client attempts to connect to your MCP server.
2. Server initiates OAuth → Displays an approval dialog with client information.
3. User approves → Redirects to the Microsoft login page.
4. User authenticates → Microsoft redirects back with an authorization code.
5. Server exchanges code → Uses the client secret to obtain an access token from Microsoft.
6. Server fetches user info → Calls the Microsoft Graph to get the user profile.
7. Token issued → The MCP client receives an encrypted token with user context.
8. Tools available → The client can now call Microsoft Graph tools with delegated permissions.

The Cloudflare Worker acts as a confidential client (server - side application) that securely stores the client secret, manages the entire OAuth flow, exchanges authorization codes for access tokens, and makes Microsoft Graph API calls on behalf of the authenticated user.

📄 License

This project is licensed under the MIT License.