HelpingAgent

A learning project demonstrating how to connect a Microsoft 365 Declarative Agent to a remote Model Context Protocol (MCP) server secured with Microsoft Entra ID OAuth authentication.

Overview

HelpingAgent is a Microsoft 365 Copilot Declarative Agent that helps users manage car repair records. Instead of calling a traditional REST API directly, the agent communicates with a remote MCP server over Streamable HTTP. Every tool invocation is protected using OAuth 2.0 with Microsoft Entra ID, ensuring that only authenticated users can access repair data.

The project uses Azure Table Storage (emulated locally using Azurite) as the backend datastore and demonstrates an end-to-end implementation of:

• Microsoft 365 Declarative Agents

• Model Context Protocol (MCP)

• OAuth authentication with Microsoft Entra ID

• Azure Table Storage

• Microsoft 365 Agents Toolkit

Features

Declarative Agent

• List repair records

• View repair details

• Create new repairs

• Update existing repairs

• Filter repairs by assigned technician

Remote MCP Server

• Built using FastMCP

• Uses Streamable HTTP transport

• Exposes repair operations as MCP tools

• Communicates securely with Microsoft 365 Copilot

OAuth Authentication

• Microsoft Entra ID issued Bearer (JWT) tokens

• JWKS-based signature verification

• Validation of:

  • Issuer

  • Audience

  • Required scopes

Data Storage

• Azure Table Storage

• Local development using Azurite

Architecture

                Microsoft 365 Copilot
              (Declarative Agent)

                       │
                       │
      OAuth Protected MCP Tool Calls
         (Bearer JWT Access Token)
                       │
                       ▼

          MCP Server (FastMCP)
        Streamable HTTP Transport
        src/mcp_server.py

      • JWT Signature Validation
      • Issuer Validation
      • Audience Validation
      • Scope Validation

                       │
                       ▼

          Azure Table Storage
           Repairs Table
      (Azurite for Local Development)

Repository Structure

OAuth Authentication Flow

The MCP server is secured using Microsoft Entra ID OAuth.

1. A Microsoft Entra ID application exposes the custom scope:

   access_as_user

2. The MCP server is configured with:

   • OAUTH_ACCEPTED_ISSUERS

   • OAUTH_ACCEPTED_AUDIENCES

   • OAUTH_REQUIRED_SCOPES

   • OAUTH_JWKS_URI

3. For every MCP tool call:

   • Extract the Bearer token

   • Verify the JWT signature using Microsoft's JWKS

   • Validate the issuer

   • Validate the audience

   • Validate the required scope

   • Reject unauthorized requests

4. The plugin (ai-plugin.json) uses:

   "auth": {
     "type": "OAuthPluginVault"
   }

   Microsoft 365 Copilot handles user authentication, consent, token acquisition, and automatically includes the Bearer token with every MCP request.

5. During provisioning, the Microsoft 365 Agents Toolkit registers the OAuth configuration using the oauth/register step and stores the generated reference ID in the environment configuration for use by the plugin.

Prerequisites

• Python 3.13

• Node.js

• Microsoft 365 Agents Toolkit

• Microsoft 365 Copilot enabled tenant

• Microsoft Entra ID App Registration

• Azure Table Storage (Azurite for local development)

Local Development

Install dependencies

pip install -r requirements.txt
npm install

Start Azurite

npm run start:azurite

Seed sample data

npm run init-data

Start the MCP Server

npm run start:mcp-http

The MCP server runs at:

http://127.0.0.1:3001

Inspect available MCP tools

npm run inspector

Run the legacy HTTP Azure Function (optional)

npm run dev

Run the complete solution

Press F5 in Visual Studio Code using the Microsoft 365 Agents Toolkit.

The toolkit will:

• Provision the application

• Start the MCP server

• Create a Development Tunnel

• Configure OAuth

• Sideload the Declarative Agent into Microsoft 365 Copilot

Environment Configuration

Environment variables are organized by deployment stage.

env/
├── .env.local
├── .env.local.user
├── .env.dev
└── .env.dev.user

• .env.* files contain non-secret configuration.

• .env.*.user files contain secrets and are excluded from source control.

Important Variables

Technologies Used

• Microsoft 365 Copilot

• Microsoft 365 Declarative Agents

• Model Context Protocol (MCP)

• FastMCP

• Streamable HTTP

• Microsoft Entra ID

• OAuth 2.0

• JSON Web Tokens (JWT)

• JSON Web Key Sets (JWKS)

• Azure Table Storage

• Azurite

• Microsoft 365 Agents Toolkit

• Python 3.13

Project Status

• ✅ Microsoft 365 Declarative Agent implemented

• ✅ Remote MCP Server implemented

• ✅ Azure Table Storage integration completed

• ✅ OAuth authentication with Microsoft Entra ID implemented

• ✅ JWT validation using JWKS implemented

• ✅ Streamable HTTP transport configured

• ✅ End-to-end communication between Microsoft 365 Copilot and the MCP server verified

Learning Objectives

This project was built as a hands-on learning exercise to understand:

• Building Microsoft 365 Declarative Agents

• Developing MCP servers using FastMCP

• Exposing functionality as MCP tools

• Securing MCP servers with Microsoft Entra ID OAuth

• Validating JWT access tokens using JWKS

• Connecting Microsoft 365 Copilot to remote MCP servers

• Using Azure Table Storage as the backend datastore

• Provisioning and deploying applications with the Microsoft 365 Agents Toolkit