MCP 服务器

m365-helping-agent

Enables managing car repair records through MCP tools, with OAuth authentication via Microsoft Entra ID.

README

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.

A Microsoft Entra ID application exposes the custom scope:
```
access_as_user
```
The MCP server is configured with:
- OAUTH_ACCEPTED_ISSUERS
- OAUTH_ACCEPTED_AUDIENCES
- OAUTH_REQUIRED_SCOPES
- OAUTH_JWKS_URI
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
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.
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