Copilot Studio Agent Direct Line MCP

🚀 ⭐ Copilot Studio Agent Direct Line MCP Server

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

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

🚀 Quick Start

The Copilot Studio Agent Direct Line MCP Server brings Microsoft Copilot Studio Agent context to your development environment. You can 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"

✨ 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

You can 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

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.

💡 Usage Tip

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.

📚 Documentation

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.

⚠️ Important Note

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