@microsoft/m365copilot-dev-mcp

Build Microsoft 365 Copilot agents faster with AI-powered development tools. This MCP server integrates the Microsoft 365 Agents Toolkit directly into your AI coding assistant.

Why Use This?

Build M365 agents by talking to your AI assistant in plain English. No need to learn complex CLI commands or switch between terminal windows. Just describe what you want to do, and your AI handles all the technical execution automatically.

Traditional approach: Learn ATK CLI → Remember commands → Run commands manually → Debug errors → Repeat

With this MCP server: "Create a customer support agent" → Done. Your AI understands intent, loads best practices, executes commands, and guides you through deployment.

Features

• 2 Powerful MCP Tools - Specialized tools for agent development
  • compile_typespec - Build type-safe agent definitions with TypeSpec compilation
  • get_best_practices - Access comprehensive documentation, ATK CLI reference, and expert guidance on-demand
• Direct ATK CLI Integration - Run all ATK commands directly via npx -p @microsoft/m365agentstoolkit-cli@latest
  • Commands: new, provision, deploy, package, publish, validate, doctor, share, auth, and more
  • Always uses latest version
  • No global installation required
• 11 Guided Prompts - Step-by-step workflows and best practices for common tasks
• 23 Documentation Resources - Comprehensive guides, examples, and troubleshooting
• TypeSpec-First - Build declarative agents with full type safety and IntelliSense
• Cross-Platform - Works on Windows, macOS, and Linux

Quick Start

No command-line experience needed! Just talk to your AI assistant in natural language.

Get started in 3 steps:

1. Install the MCP server (see Installation below)

2. Configure your AI client (see Configuration below)

3. Start building: Simply ask your AI assistant

   • "Create a new M365 agent for customer support"
   • "Deploy my agent to the dev environment"
   • "Share this agent with my team"

   The AI understands your intent and automatically:

   • Loads best practices and command reference
   • Determines the right ATK commands to run
   • Executes everything with correct parameters
   • Provides helpful results and next steps

Installation

Prerequisites

• Node.js 18+ and npm 8+
• Microsoft 365 account with admin permissions
• Azure CLI (for cloud deployments)

Option 1: Global Installation (Recommended)

npm install -g @microsoft/m365copilot-dev-mcp

Option 2: Local Development

Clone and build from source:

git clone https://github.com/sebastienlevert/m365copilot-dev-mcp
cd m365copilot-dev-mcp
npm install
npm run build
npm link

This makes the m365copilot-dev-mcp command available locally for testing.

Configuration

Claude Desktop

Edit your Claude Desktop config file:

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

Add this configuration:

{
  "mcpServers": {
    "m365copilot-dev": {
      "command": "m365copilot-dev-mcp"
    }
  }
}

VS Code with GitHub Copilot

Add to your VS Code settings (.vscode/settings.json or User Settings):

{
  "github.copilot.chat.mcp.servers": {
    "m365copilot-dev": {
      "command": "m365copilot-dev-mcp"
    }
  }
}

Other MCP Clients

Configure stdio transport with command: m365copilot-dev-mcp

⚠️ Important: Restart your AI client after configuration changes to load the MCP server.

Core Tools

compile_typespec - TypeSpec Compilation

Build type-safe agent definitions from TypeSpec source files.

Parameters:

{
  "projectPath": "./my-agent"
}

What it does:

• Compiles TypeSpec agent definitions to JSON manifests
• Validates TypeSpec syntax and structure
• Generates declarativeAgent.json and manifest.json files
• Reports compilation errors with helpful guidance

get_best_practices - Expert Guidance & CLI Reference

Access comprehensive documentation including TypeSpec/JSON best practices AND complete ATK CLI reference.

⚠️ CRITICAL: AI assistants MUST call this tool FIRST before any agent work!

Parameters:

{
  "type": "typespec"  // or "json" or "both"
}

What it includes:

• Best practices for TypeSpec or JSON agent development
• Complete ATK CLI reference with all commands and parameters
• Correct command syntax: npx -p @microsoft/m365agentstoolkit-cli@latest atk <command>
• Capability scoping patterns
• Response formatting guidelines
• Critical warnings about what NOT to do

Once loaded, you don't need to call it again in the same session.

How It Works: Intent-Based Automation

You don't need to learn or remember any commands!

When you tell your AI assistant what you want to do in natural language:

• "I want to create a new agent"
• "Deploy my agent to dev"
• "Share this with my team"

The AI assistant will:

1. Understand your intent
2. Check the loaded best practices and CLI reference
3. Determine the appropriate ATK command(s) to run
4. Execute the commands with correct parameters
5. Format the results with helpful next steps

The commands shown below are for reference only - your AI assistant handles all command execution automatically.

Running ATK Commands (For Reference)

All ATK CLI commands are executed directly via bash using:

npx -p @microsoft/m365agentstoolkit-cli@latest atk <command> [options]

Key ATK Commands:

Create new agent:

npx -p @microsoft/m365agentstoolkit-cli@latest atk new -n my-agent -c declarative-agent -with-plugin type-spec -i false

Provision Azure resources:

npx -p @microsoft/m365agentstoolkit-cli@latest atk provision --env dev

Deploy agent:

npx -p @microsoft/m365agentstoolkit-cli@latest atk deploy --env dev

Package agent:

npx -p @microsoft/m365agentstoolkit-cli@latest atk package --env dev

Share with tenant:

npx -p @microsoft/m365agentstoolkit-cli@latest atk share --scope tenant --env dev -i false

Share with specific users:

npx -p @microsoft/m365agentstoolkit-cli@latest atk share --scope users --email 'user@domain.com' --env dev -i false

Validate agent:

npx -p @microsoft/m365agentstoolkit-cli@latest atk validate

Check environment:

npx -p @microsoft/m365agentstoolkit-cli@latest atk doctor

Why npx -p @latest?

• Always uses the latest ATK version
• No global installation required
• Consistent across all environments
• Perfect for CI/CD pipelines

Guided Workflows

Use prompts for step-by-step assistance:

• create-declarative-agent - Complete project creation workflow
• deploy-agent-complete - End-to-end deployment automation
• configure-environments - Multi-environment setup guidance
• security-checklist - Security review for your agent
• troubleshoot-deployment - Debug common deployment issues

...and 6 more specialized prompts for agent development.

Documentation & Resources

Access 23 comprehensive resources through the MCP server:

• Guides: Commands reference, lifecycle stages, configuration docs
• Examples: Weather agent, declarative agent, API plugin patterns
• Troubleshooting: Common issues, installation help, debugging
• Best Practices: Security, TypeSpec patterns, authentication

Query resources via URIs like atk://docs/commands or atk://examples/declarative-agent.

Get Started: Build Your First Agent

Once configured, simply ask your AI assistant in natural language:

"Create a new M365 agent called customer-support-agent using TypeSpec"

You don't need to know or run any commands yourself! The AI assistant will:

1. Understand your intent
2. Load best practices and ATK CLI reference using get_best_practices tool
3. Automatically determine the right ATK command to run
4. Execute commands directly via npx @latest
5. Compile TypeSpec using compile_typespec tool
6. Guide you through the setup and deployment

Just describe what you want to do - the AI handles all the technical details and command execution.

Example Development Flow

Just tell your AI what you want to do in plain English:

1. Create

   • You say: "Create a new declarative agent for handling FAQs"
   • AI automatically: Loads best practices → Runs atk new command → Sets up project

2. Compile & Validate

   • You say: "Compile my TypeSpec and validate the agent"
   • AI automatically: Uses compile_typespec tool → Runs atk validate command

3. Deploy

   • You say: "Provision Azure resources and deploy to dev environment"
   • AI automatically: Runs atk provision → Runs atk deploy → Provides test link

4. Package & Share

   • You say: "Package and share my agent with my team"
   • AI automatically: Checks AGENT_SCOPE → Runs atk package → Runs atk share with correct parameters

You focus on WHAT you want to build. The AI figures out HOW to execute it.

Common Workflows

New Project: Load best practices → Create project (atk new) → Compile TypeSpec → Provision → Deploy Update Code: Compile TypeSpec → Deploy (atk deploy) Update Manifest: Compile TypeSpec → Package (atk package) → Publish (atk publish) New Environment: Provision (atk provision) → Deploy → Package → Share (if AGENT_SCOPE=shared)

Architecture & Technology

Built on industry-standard tools for reliability and performance:

• MCP SDK - Model Context Protocol for AI integration
• Microsoft 365 Agents Toolkit - Official M365 development tools
• TypeScript - Type-safe implementation with ESM modules
• Zod - Runtime validation for all tool inputs
• Node.js 18+ - Modern JavaScript runtime

Troubleshooting

Authentication Issues: Run az login to authenticate with Azure
ATK CLI Not Found: The CLI is auto-downloaded via npx on first use (may take 10-30 seconds)
Environment Issues: Use the troubleshoot-deployment prompt for guided debugging
Permission Errors: Verify you have Contributor/Owner role in Azure and Admin in M365

Access detailed troubleshooting via atk://troubleshooting/common-issues resource.

Security Best Practices

• Never commit .env files to version control
• Use Azure Key Vault for production secrets
• Follow least-privilege principle for Azure permissions
• Rotate credentials regularly
• Review the security-checklist prompt before deploying

Contributing

Contributions welcome! See AGENTS.md for the complete development guide.

Key development steps:

1. Clone the repository
2. Run npm install to install dependencies
3. Run npm run build to compile TypeScript
4. Run npm link to make the command available locally
5. Test changes with your MCP client

Focus areas for contributions:

• Additional workflow prompts for common scenarios
• More TypeSpec examples and patterns
• Enhanced error messages and guidance
• Cross-platform testing and compatibility
• Documentation improvements

License

MIT License - see LICENSE file for details.

Resources & Support

• Official Docs: Microsoft 365 Agents Toolkit
• MCP Protocol: Model Context Protocol
• Issues: GitHub Issues
• Stack Overflow: Tag microsoft-365-agents-toolkit

Ready to Build?

Install the MCP server, configure your AI client, and start building intelligent Microsoft 365 agents today. Your AI assistant is waiting to help you create amazing conversational experiences.

Get started now:

npm install -g @microsoft/m365copilot-dev-mcp

Then configure your AI client and ask: "Help me create my first M365 Copilot agent"

---

Built with ❤️ for Microsoft 365 developers | View on GitHub