Agent 365 Bridge for Claude Code

Connect Claude Code to Microsoft Agent 365 MCP servers — giving Claude direct access to Outlook Mail, Calendar, Word, Excel, PowerPoint, Teams, SharePoint, OneDrive, Copilot Search, Knowledge, and User Profile data through the enterprise-grade MCP tooling gateway.

Architecture

┌─────────────┐      stdio       ┌──────────────────┐     HTTPS + Auth     ┌─────────────────────────┐
│ Claude Code  │ ◄──────────────► │  MCP Proxy Bridge │ ◄──────────────────► │  Agent 365 MCP Servers  │
│ (CLI / IDE)  │   MCP protocol   │  (this project)   │   StreamableHTTP    │  (Mail, Calendar, Word, │
└─────────────┘                  └──────────────────┘                      │   Teams, SharePoint...) │
                                                                           └─────────────────────────┘

The bridge runs as a local stdio MCP server that Claude Code connects to. When Claude calls a tool (e.g. createMessage, getEvents), the bridge authenticates with Azure Entra ID using delegated permissions and forwards the call to the appropriate Agent 365 MCP server — acting on behalf of the signed-in user.

Two-Layer Disk Caching

Claude Desktop enforces a 5-second timeout on tools/list requests. Since discovering 14 Agent 365 servers takes ~20 seconds, the bridge uses a two-layer caching strategy to serve tools instantly:

sequenceDiagram
    participant User
    participant Login as npm run login
    participant Disk as ~/.agent365-bridge/
    participant Bridge as Bridge Process
    participant Claude as Claude Desktop

    Note over User,Login: One-time setup
    User->>Login: npm run login
    Login->>Login: Device code auth
    Login->>Disk: auth-record.json
    Login->>Login: Discover 14 servers (56 tools)
    Login->>Disk: tools-cache.json

    Note over Bridge,Claude: Every subsequent launch
    Claude->>Bridge: initialize
    Bridge->>Disk: Load tools-cache.json
    Bridge-->>Claude: initialize response
    Claude->>Bridge: tools/list
    Bridge-->>Claude: 56 tools (instant, <1ms)
    Note over Bridge: Discovery runs in background (~20s)
    Claude->>Bridge: tools/call SearchMessages
    Note over Bridge: Waits for live discovery if needed
    Bridge-->>Claude: Email results

Compatibility Layer

The bridge automatically fixes common MCP compatibility issues:

1. Schema Sanitization: Strips oneOf, allOf, and anyOf from tool schemas (which Anthropic API rejects), merging properties where possible.
2. Name Deduplication: Detects tools with identical names across different servers (e.g. GetDocumentContent in both Word and Excel) and automatically namespaces them (e.g. GetDocumentContent_Word) to prevent collisions.

Why this project exists?

While Microsoft provides a rich set of tools for building and managing AI agents, there is currently a "protocol gap" for 3rd-party coding agents like Claude Code:

1. Protocol Translation: Claude Code and most local IDEs speak the stdio dialect of the Model Context Protocol (MCP). However, the Agent 365 Tooling Gateway (the enterprise cloud back-end) speaks StreamableHTTP. This project acts as the necessary protocol translator.
2. Access to the "Synthetic Workforce": Agent 365 is designed to be the control plane for a new generation of autonomous agents. This bridge allows Claude to tap into that same infrastructure, giving a 3rd-party LLM the same enterprise-governed tools used by Microsoft's first-party agents.
3. Action over Search: Unlike pure semantic search tools (like WorkIQ), this bridge focuses on deterministic actions. It exposes the granular Tooling Servers for Mail, Excel, Word, and Teams, allowing Claude to manipulate data, not just find it.
4. Developer-First Auth: It simplifies the complex "Frontier Preview" and "StreamableHTTP" authentication handshake into a standard MCP sign-in flow that just works.

Status

✅ Production-tested and working — Successfully authenticated and discovered 20+ tools from Microsoft Agent 365 MCP servers (Mail, Excel, Knowledge, and more confirmed).

Prerequisites

Requirement	Purpose
Node.js ≥ 18	Runtime
Claude Code CLI	MCP client
Frontier Preview	Required for Agent 365 access (enroll here)
Azure AD App Registration	Authentication (see setup guide below)
A365 CLI (optional)	Agent registration & mock server — requires .NET 8+

---

Setup Guide

Step 1: Install & Build

git clone https://github.com/ITSpecialist111/Agent365-Bridge.git
cd Agent365-Bridge
npm install
npm run build

---

Step 2: Create an Azure AD App Registration

You need an Azure AD app registration to authenticate with the Agent 365 platform. Follow these steps in the Azure Portal:

2a. Register the application

1. Navigate to Microsoft Entra ID → App registrations → New registration
2. Fill in the details:
   • Name: Agent365-Claude-Bridge (or any name you prefer)
   • Supported account types: "Accounts in this organizational directory only" (Single tenant)
   • Redirect URI: Leave blank
3. Click Register

2b. Collect the required details

From the app registration Overview page, copy these two values:

Field	Where to find it	.env variable
Directory (tenant) ID	Overview page, top section	AZURE_TENANT_ID
Application (client) ID	Overview page, top section	AZURE_CLIENT_ID

2c. Create a client secret (optional — server deployment only)

Note: If you're only using Claude Code / Claude Desktop with the default Device Code sign-in flow, you can skip this step entirely. The Device Code flow is a public client flow and does not require a client secret.

A client secret is only needed if you plan to:

• Deploy the bridge as an HTTP server with On-Behalf-Of (OBO) auth (AUTH_MODE=obo)
• Use Application permissions with Client Credentials (AUTH_MODE=client_credentials)

1. Go to Certificates & secrets (left sidebar)
2. Click New client secret
3. Enter a description (e.g. Agent365 Bridge) and choose an expiry period
4. Click Add
5. Copy the "Value" immediately — this is your AZURE_CLIENT_SECRET

⚠️ The secret value is only shown once. If you lose it, you'll need to create a new one.

2d. Add API Permissions

1. Go to API permissions (left sidebar)
2. Click Add a permission → APIs my organization uses
3. Search for Agent 365 Tools (or the app ID ea9ffc3e-8a23-4a7d-836d-234d7c7565c1)
4. Select Delegated permissions and add the scopes you need:

Permission	Description
McpServers.Calendar.All	Calendar MCP Server
McpServers.CopilotMCP.All	Copilot MCP Server
McpServers.DASearch.All	M365 Copilot Agent Directory
McpServers.Dataverse.All	Dataverse MCP Server
McpServers.Excel.All	Excel MCP Server
McpServers.Files.All	ODSP Files Tool MCP Server
McpServers.Knowledge.All	Knowledge MCP Server
McpServers.Mail.All	Mail MCP Server
McpServers.Me.All	Me MCP Server (User Profile)
McpServers.OneDriveSharePoint.All	OneDrive & SharePoint MCP Server
McpServers.PowerPoint.All	PowerPoint MCP Server
McpServers.SharepointLists.All	SharePoint Lists MCP Server
McpServers.Teams.All	Teams MCP Server
McpServers.Word.All	Word MCP Server

5. Click Grant admin consent for [your organization] (blue button at the top)
6. Verify that each permission shows a green ✅ checkmark under Status

2e. Enable public client flows

This is required for the device code sign-in flow:

1. Go to Authentication (left sidebar)
2. Scroll to Advanced settings at the bottom
3. Set "Allow public client flows" to Yes
4. Click Save

---

Step 3: Configure the .env file

Create a .env file in the project root with your credentials:

# Azure Entra ID Authentication
AZURE_TENANT_ID=your-directory-tenant-id
AZURE_CLIENT_ID=your-application-client-id

# Client secret — only needed for OBO (server) or client_credentials mode.
# For the default Device Code flow (Claude Code / Claude Desktop), leave this blank or omit it.
# AZURE_CLIENT_SECRET=your-client-secret-value

# Agent 365 Configuration
MCP_PLATFORM_ENDPOINT=https://agent365.svc.cloud.microsoft
MCP_PLATFORM_AUTHENTICATION_SCOPE=ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/.default

# Runtime
NODE_ENV=development

---

Step 4: Sign In (One-Time)

Sign in to Microsoft 365 and cache your credentials:

npm run login

You'll be prompted to visit a URL, then tools will be discovered and cached:

Agent 365 Bridge — Sign In & Setup

Step 1: Sign in to Microsoft 365
[agent365-bridge] SIGN IN REQUIRED
[agent365-bridge] Go to: https://microsoft.com/devicelogin
[agent365-bridge] Enter code: XXXXXXXX

✅ Authentication successful!
   Credentials cached at: ~/.agent365-bridge/auth-record.json

Step 2: Discovering Agent 365 MCP servers...

✅ Discovered 56 tools across 14 servers

🎉 Setup complete!
   Claude Desktop will now load all tools instantly.

To complete sign-in:

1. Open https://microsoft.com/devicelogin in your browser
2. Enter the code shown in the terminal
3. Sign in with your Microsoft 365 account
4. Wait for tool discovery to complete (~20 seconds)

Note: This only needs to be done once. Both credentials and the tool list are cached to disk. Tokens refresh automatically on subsequent launches. Run npm run logout to clear cached credentials.

---

Step 5: Register with Claude Code / Claude Desktop

For Claude Code (CLI):

npm run register

This registers the bridge as a global MCP server in Claude Code. After this, Agent 365 tools are available in any Claude Code session.

For Claude Desktop, add the bridge to your config file (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "agent365-bridge": {
      "command": "node",
      "args": ["C:/path/to/your/Agent365/dist/index.js"]
    }
  }
}

---

Step 6: Use Claude Code

Open Claude Code — Agent 365 tools will appear automatically. Try:

> Search my Outlook inbox for emails about the Q4 report
> Create a new Word document summarizing the project status
> List my upcoming calendar events for this week
> Post a message in the Engineering team channel
> Find files in SharePoint related to the budget
> Create an Excel workbook with monthly revenue data

---

---

Universal MCP Support (Claude Desktop & Others)

This bridge complies with the Model Context Protocol (MCP) specification, meaning it can be used with any MCP-compatible client, not just Claude Code CLI.

adding to Claude Desktop (Windows/Mac)

To use Agent 365 tools inside the Claude Desktop app:

1. Open your config file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the bridge configuration:

{
  "mcpServers": {
    "agent365-bridge": {
      "command": "node",
      "args": [
        "C:/path/to/your/Agent365/dist/index.js"
      ]
    }
  }
}

Note: Update the path to match where you cloned this repository.

3. Restart Claude Desktop. The tools will appear in the 🔌 menu.

---

Available MCP Servers

The bridge connects to all 13 Agent 365 MCP servers:

Server	Scope	Description
Outlook Mail	McpServers.Mail.All	Read, compose, send, search, and manage emails
Outlook Calendar	McpServers.Calendar.All	Create, view, update, and manage calendar events
Word	McpServers.Word.All	Create and read Word documents, add comments
Excel	McpServers.Excel.All	Create workbooks, manage spreadsheets
PowerPoint	McpServers.PowerPoint.All	Create and modify presentations
Teams	McpServers.Teams.All	Chat, channels, and messaging operations
OneDrive & SharePoint	McpServers.OneDriveSharePoint.All	File upload, search, and metadata
SharePoint Lists	McpServers.SharepointLists.All	List and item CRUD operations
Copilot Search	McpServers.CopilotMCP.All	AI-powered search across M365 data
Knowledge	McpServers.Knowledge.All	Federated knowledge retrieval
User Profile	McpServers.Me.All	Profile, manager, direct reports, user search
Files	McpServers.Files.All	ODSP Files tool operations
Agent Directory	McpServers.DASearch.All	Copilot Agent Directory search
Dataverse	McpServers.Dataverse.All	CRUD operations, FetchXML, and Web API for Dataverse
Files	McpServers.Files.All	ODSP Files tool operations

---

Agent 365 Bridge vs. Microsoft WorkIQ

While this bridge connects Claude to the core Agent 365 infrastructure for action and orchestration, Microsoft also provides WorkIQ, an "intelligence layer" for M365.

Feature	Agent 365 Bridge (This Project)	Microsoft WorkIQ
Primary Goal	Action & Automation: Send mail, create docs, update calendar.	Context & Intelligence: "Summarize my meetings regarding X", "What did Sarah say?"
Data Scope	13+ Granular M365 Services (Word, Excel, Teams, etc.)	Federated search across Mail, Teams, and SharePoint.
Authentication	Custom App Registration (Device Code by default — no client secret needed).	Microsoft-managed App (requires one-time Tenant Admin consent).
Setup Mode	Local Proxy to Remote HTTP Gateway.	Native Local stdio Server.

Using Both Together

For the best experience, we recommend running both servers side-by-side in Claude. This gives Claude "hands" (the bridge) and a "brain" (WorkIQ).

Claude Desktop Configuration (%APPDATA%/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "agent365-bridge": {
      "command": "node",
      "args": ["C:/Path/To/Agent365-Bridge/dist/index.js"]
    },
    "workiq": {
      "command": "npx",
      "args": ["-y", "@microsoft/workiq", "mcp"]
    }
  }
}

[!NOTE] WorkIQ is currently in Public Preview. For setup instructions and admin consent details, visit the official WorkIQ repository.

Authentication Modes

Mode	When to use	Config	Client Secret?
Device Code (default)	Claude Code / Desktop with Delegated permissions	Set AZURE_TENANT_ID + AZURE_CLIENT_ID	No — public client flow
Client Credentials	Application-type permissions (headless)	Add AUTH_MODE=client_credentials + AZURE_CLIENT_SECRET	Yes
OBO (On-Behalf-Of)	HTTP server deployment (Copilot Studio)	Add AUTH_MODE=obo + AZURE_CLIENT_SECRET	Yes
Bearer Token	Testing with a pre-acquired token	Set BEARER_TOKEN in .env	No
Mock	Local development without Azure	Endpoint set to localhost	No

Project Structure

├── src/
│   ├── index.ts                    # Entry point
│   ├── auth/
│   │   ├── token-provider.ts       # Device Code / Client Secret / Bearer auth
│   │   └── token-cache.ts          # JWT token caching with auto-refresh
│   ├── config/
│   │   ├── configuration.ts        # Loads .env + ToolingManifest.json
│   │   └── types.ts                # TypeScript interfaces
│   ├── discovery/
│   │   └── server-discovery.ts     # Discovers MCP servers (manifest or gateway)
│   └── proxy/
│       ├── mcp-proxy-server.ts     # stdio MCP server for Claude Code
│       └── tool-forwarder.ts       # Forwards tool calls to remote servers
├── scripts/
│   ├── setup.ts                    # Interactive setup wizard
│   ├── register-claude.ts          # Registers bridge with Claude Code CLI
│   └── start-mock.ts              # Starts mock server for development
├── ToolingManifest.json            # Declares 13 available MCP servers
├── .mcp.json                       # Claude Code project-level MCP config
├── .env.example                    # Environment variable template
├── package.json
└── tsconfig.json

npm Scripts

Script	Description
npm run build	Compile TypeScript to dist/
npm run dev	Run with ts-node (development)
npm run start	Run compiled output
npm run setup	Interactive setup wizard
npm run login	Sign in to M365 and cache credentials (one-time)
npm run logout	Clear cached credentials
npm run register	Register bridge with Claude Code CLI
npm run mock	Start mock server + register
npm run clean	Remove dist/ directory

Troubleshooting

Error	Cause	Fix
Access denied by Frontier access control	Tenant not enrolled in Frontier preview	Enroll here
Scope 'McpServers.X.All' is not present	API permissions not added or not consented	Add permissions in Azure Portal → Grant admin consent
Application not found in directory	Wrong Tenant ID for the app registration	Check the Directory (tenant) ID on the app's Overview page
AADSTS7000218: request body must contain client_assertion	Public client flows not enabled	Set "Allow public client flows" to Yes in Authentication settings
Scope doesn't exist on the resource	Manifest scope names don't match Azure API	Update ToolingManifest.json scope names or use /.default
No authentication configured	Missing credentials in .env	Add AZURE_TENANT_ID and AZURE_CLIENT_ID to .env
Tools don't appear in Claude Desktop	Token not cached / timeout	Run npm run login first, then restart Claude Desktop
Request timed out in MCP logs	Device code sign-in took too long	Run npm run login in terminal first for one-time setup

References

• Agent 365 Tooling Servers Overview
• Agent 365 SDK and CLI
• Agent 365 CLI Install (requires .NET 8+: dotnet tool install --global Microsoft.Agents.A365.DevTools.Cli --prerelease)
• Agent 365 Samples
• MCP Server Reference
• Frontier Preview Program

Disclaimer

Authentication & Liability: This project is an open-source bridge and is not an official Microsoft product. It uses your own Azure AD App Registration and operates under the context of the signed-in user. You are responsible for managing the security of your client secrets and tokens. The maintainers of this repository accept no liability for any data loss, security breaches, or unexpected charges incurred by using this software. Use at your own risk.