⭐ Copilot Studio Agent Direct Line MCP Server

Easily install the Copilot Studio Agent Direct Line MCP Server for VS Code or VS Code Insiders:

This TypeScript project provides a local MCP server for Microsoft Copilot Studio Agents, enabling you to interact with your Copilot Studio Agents directly from your code editor via the Direct Line 3.0 API.

📄 Table of Contents

• ⭐ Copilot Studio Agent Direct Line MCP Server
  • 📄 Table of Contents
  • 📺 Overview
  • 🏆 Expectations
  • ⚙️ Features
  • ⚒️ Supported Tools
  • 🔌 Installation & Getting Started
    • Prerequisites
    • Installation
      • ✨ One-Click Install (Recommended)
      • 🧨 Manual Install with NPX
  • 📝 Troubleshooting
  • 🎩 Examples & Best Practices
  • 🙋‍♀️ Frequently Asked Questions
  • 📌 Contributing
  • 🤝 Code of Conduct
  • License

📺 Overview

The Copilot Studio Agent Direct Line MCP Server brings Microsoft Copilot Studio Agent context to your development environment. Try prompts like:

• "Start a conversation with my Copilot Studio Agent"
• "Ask my agent about product sizing"
• "Send a message to the agent: What are your capabilities?"
• "Get the conversation history"
• "End the current conversation"

🏆 Expectations

The Copilot Studio Agent Direct Line MCP Server is built with tools that are concise, simple, focused, and easy to use—each designed for a specific scenario. We intentionally avoid complex tools that try to do too much. The goal is to provide a thin abstraction layer over the Direct Line 3.0 API, making agent interaction straightforward and letting the language model handle complex reasoning.

⚙️ Features

• ✅ Direct Line 3.0 Integration - Full support for Microsoft Bot Framework Direct Line API
• ✅ Token Management - Automatic token caching and proactive refresh
• ✅ Conversation State - Manages conversation lifecycle with 30-minute idle timeout
• ✅ MCP Tools - Four tools for agent interaction: send_message, start_conversation, end_conversation, get_conversation_history
• ✅ Comprehensive Error Handling - 11 specialized error types, OAuth-specific retry strategies, MCP error transformation
• ✅ Circuit Breaker Pattern - Intelligent failure classification, excludes user errors from circuit state
• ✅ Retry Logic - Exponential backoff with jitter, OAuth-aware retry strategies
• ✅ Input Validation - Zod schemas for type-safe validation
• ✅ Security - Secret masking in logs, secure environment configuration, no disk persistence
• ✅ HTTP Transport Mode - Optional HTTP server with Azure Entra ID OAuth authentication
• ✅ Testing Suite - 45+ tests with 80%+ coverage on critical components
• ✅ Production Ready - Deployment templates for Azure Container Apps, Docker, Kubernetes

⚒️ Supported Tools

Interact with your Copilot Studio Agent using these tools:

• send_message: Send a message to the Copilot Studio Agent and receive a response.
• start_conversation: Start a new conversation with the Agent, optionally with an initial message.
• end_conversation: End a conversation and clean up resources.
• get_conversation_history: Retrieve message history for a conversation.

🔌 Installation & Getting Started

For the best experience, use Visual Studio Code and GitHub Copilot. See the getting started documentation to use our MCP Server with other tools such as Claude Code and Cursor.

Prerequisites

1. Install VS Code or VS Code Insiders
2. Install Node.js 18+
3. Microsoft Copilot Studio Agent with Direct Line 3.0 enabled
4. Direct Line secret key from your Copilot Studio Agent

Installation

✨ One-Click Install (Recommended)

After installation, select GitHub Copilot Agent Mode and refresh the tools list. Learn more about Agent Mode in the VS Code Documentation.

🧨 Manual Install with NPX

This installation method is the easiest for all users of Visual Studio Code.

In your project, add a .vscode/mcp.json file with the following content:

{
  "inputs": [
    {
      "id": "direct_line_secret",
      "type": "promptString",
      "description": "Direct Line secret key from your Copilot Studio Agent"
    }
  ],
  "servers": {
    "copilot-studio-agent-direct-line-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "copilot-studio-agent-direct-line-mcp"],
      "env": {
        "DIRECT_LINE_SECRET": "${input:direct_line_secret}"
      }
    }
  }
}

Save the file, then click 'Start' in the MCP Server panel.

In chat, switch to Agent Mode.

Click "Select Tools" and choose the available tools.

Open GitHub Copilot Chat and try a prompt like Start a conversation with my Copilot Studio Agent. The first time a tool is executed, you will be prompted for your Direct Line secret.

💥 We strongly recommend creating a .github/copilot-instructions.md in your project. This will enhance your experience using the Copilot Studio MCP Server with GitHub Copilot Chat. To start, just include "This project uses Microsoft Copilot Studio Agents. Always check to see if the Copilot Studio MCP server has a tool relevant to the user's request" in your copilot instructions file.

See the getting started documentation for additional installation methods, including local development setup.

📝 Troubleshooting

See the Troubleshooting guide for help with common issues and logging.

🎩 Examples & Best Practices

Explore example prompts and usage patterns in our Examples documentation.

For detailed tool reference and usage guides, refer to the Usage Guide.

🙋‍♀️ Frequently Asked Questions

For answers to common questions about the Copilot Studio Agent Direct Line MCP Server, see the Frequently Asked Questions.

📌 Contributing

We welcome contributions! During preview, please file issues for bugs, enhancements, or documentation improvements.

See our Contributions Guide for:

• 🛠️ Development setup
• ✨ Adding new features
• 📝 Code style & testing
• 🔄 Pull request process

🤝 Code of Conduct

This project follows standard open-source community guidelines. We expect all contributors to be respectful and constructive in their interactions.

License

Licensed under the MIT License.

Disclaimer: This is a personal project by Brad Stevens.
It is not affiliated with or endorsed by Microsoft Corporation.