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

Path	Description
src/mcp_server.py	MCP server implementation containing repair tools and OAuth token validation.
src/init_data.py	Seeds Azure Table Storage with sample repair records.
src/repairsData.json	Sample repair data used during initialization.
appPackage/repairDeclarativeAgent.json	Declarative Agent definition.
appPackage/ai-plugin.json	Plugin configuration connecting the agent to the remote MCP server.
appPackage/instruction.txt	System instructions for the Declarative Agent.
appPackage/adaptiveCards/	Adaptive Card templates used to display repair information.
appPackage/manifest.json	Microsoft Teams/Microsoft 365 app manifest.
infra/azure.bicep	Azure infrastructure definition.
m365agents.yml	Microsoft 365 Agents Toolkit provisioning and deployment pipeline.
m365agents.local.yml	Local development pipeline.
env/	Environment configuration files.
mcp-auth-todo.txt	OAuth implementation checklist.
docs/HelpingAgent-Learning-Guide.pdf	Project learning guide.

---

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

Variable	Description
AZURE_STORAGE_CONNECTION_STRING	Azure Table Storage connection string.
OAUTH_ACCEPTED_ISSUERS	Accepted Microsoft Entra ID issuer(s).
OAUTH_ACCEPTED_AUDIENCES	Accepted App ID URI(s).
OAUTH_REQUIRED_SCOPES	Required OAuth scope(s).
OAUTH_JWKS_URI	Microsoft Entra ID JWKS endpoint.
MCP_SERVER_URL	Public MCP server URL.

---

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

---