Copilot Studio Agent Direct Line

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

Install with NPX in VS Code Install with NPX in 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
      • 🛠️ Install from Source (For Development)
  • 🔧 Configuration
    • Using NPX (Recommended)
    • Using Source Installation
  • 🚀 Development
  • 📖 Usage
    • Using with VS Code
    • Standalone Server Usage
    • Using the Tools
    • MCP Tools Reference
      • send_message
      • start_conversation
      • end_conversation
      • get_conversation_history
  • 🏗️ Architecture
  • 🔑 Key Components
    • DirectLineClient
    • TokenManager
    • ConversationManager
    • CircuitBreaker
  • 🛡️ Error Handling
  • 🔒 Security
  • 📝 Troubleshooting
    • MCP Server Not Connecting in VS Code
    • Direct Line Connection Issues
    • Common Errors
      • Failed to generate Direct Line token
      • Conversation not found or expired
      • Circuit breaker is OPEN
    • Example VS Code mcp.json Configuration
  • 🧪 Testing
    • Testing the MCP Server
    • Running Test Client (For Development)
  • 📌 Contributing
  • License
  • 💬 Support

📺 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
• ✅ Error Handling - Retry logic with exponential backoff, circuit breaker pattern
• ✅ Input Validation - Zod schemas for type-safe validation
• ✅ Security - Secret masking in logs, secure environment configuration

🔐 Authentication Requirements

Important: This MCP server currently supports Copilot Studio Agents configured with "No authentication" only.

In Copilot Studio, ensure your agent's Security > Authentication setting is set to "No authentication" for this MCP server to work properly.

🚧 Coming Soon: Entra ID (Azure AD) authentication support is under development and will be available in a future release.

⚒️ 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.

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)

Click one of the badges below to automatically configure the MCP server in VS Code:

Install with NPX in VS Code Install with NPX in VS Code Insiders

After clicking, VS Code will:

1. Prompt you for your Direct Line secret key
2. Automatically configure the MCP server
3. Start the server using npx (no manual installation needed!)

Then:

1. Select GitHub Copilot Agent Mode
2. Click "Select Tools" and choose the available Copilot Studio tools
3. Try a prompt like: Start a conversation with my Copilot Studio Agent

Learn more about Agent Mode in the VS Code Documentation.

🧨 Manual Install with NPX

If you prefer manual configuration, add this to your .vscode/mcp.json file:

{
  "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 and click 'Start' in the MCP Server panel. VS Code will prompt you for your Direct Line secret.

🛠️ Install from Source (For Development)

For contributing or local development:

# Clone and build
git clone https://github.com/bradcstevens/copilot-studio-agent-direct-line-mcp.git
cd copilot-studio-agent-direct-line-mcp
npm install
npm run build

# Add to .vscode/mcp.json
{
  "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": "node",
      "args": ["/absolute/path/to/copilot-studio-agent-direct-line-mcp/dist/index.js"],
      "env": {
        "DIRECT_LINE_SECRET": "${input:direct_line_secret}"
      }
    }
  }
}

Important: Replace /absolute/path/to/ with the actual path to the cloned repository.

💥 Pro Tip: Create a .github/copilot-instructions.md file in your project with:

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.

This will enhance your experience with GitHub Copilot Chat!

🔧 Configuration

Using NPX (Recommended)

When using npx, configuration is handled through VS Code's MCP input prompts or environment variables:

• DIRECT_LINE_SECRET (required): Your Direct Line secret key from Copilot Studio
• LOG_LEVEL (optional): Logging level (default: info)
• TOKEN_REFRESH_INTERVAL (optional): Token refresh interval in milliseconds (default: 1800000 = 30 minutes)

The one-click install will automatically prompt you for the Direct Line secret. For manual configuration, you can add these to the env section of your mcp.json file.

Using Source Installation

Create a .env file based on .env.example:

# Required
DIRECT_LINE_SECRET=your_direct_line_secret_here

# Optional
LOG_LEVEL=info
TOKEN_REFRESH_INTERVAL=1800000  # 30 minutes in ms

🚀 Development

# Build
npm run build

# Development mode with watch
npm run dev

# Lint
npm run lint

# Format
npm run format

📖 Usage

Using with VS Code

After installation, the MCP server runs automatically when you use GitHub Copilot. The server is invoked via npx, which automatically downloads and runs the latest version from NPM.

Standalone Server Usage

You can run the server standalone for testing or integration with other MCP clients:

# Using npx (recommended)
DIRECT_LINE_SECRET=your_secret npx -y copilot-studio-agent-direct-line-mcp

# Or from source after building
node dist/index.js

The server uses stdio transport and will wait for MCP client connections.

Using the Tools

You can now interact with your Copilot Studio Agent directly from GitHub Copilot:

Start a conversation with my bot and ask about product sizing

GitHub Copilot will use the start_conversation and send_message tools to communicate with your Copilot Studio Agent.

MCP Tools Reference

send_message

Send a message to the Copilot Studio Agent.

Parameters:

• message (string, required): The message text
• conversationId (string, optional): Conversation ID to continue existing conversation

Returns: JSON with conversationId, response, and activityId

start_conversation

Start a new conversation with the Agent.

Parameters:

• initialMessage (string, optional): First message to send

Returns: JSON with conversationId, status, and optional response

end_conversation

End a conversation and clean up resources.

Parameters:

• conversationId (string, required): Conversation ID to terminate

Returns: JSON with conversationId, status, and messageCount

get_conversation_history

Retrieve message history for a conversation.

Parameters:

• conversationId (string, required): Conversation ID
• limit (number, optional): Maximum number of messages to return

Returns: JSON with conversationId, messageCount, totalMessages, and messages array

🏗️ Architecture

src/
├── config/          # Environment configuration with Zod validation
├── server/          # MCP server implementation
│   ├── mcp-server.ts       # Main MCP server class
│   ├── tool-schemas.ts     # Zod validation schemas
│   └── mcp-response.ts     # Response formatting & error handling
├── services/        # Core business logic
│   ├── directline-client.ts      # Direct Line API client with circuit breaker
│   ├── token-manager.ts          # Token caching & refresh
│   ├── conversation-manager.ts   # Conversation lifecycle management
│   └── http-client.ts            # Axios HTTP client
├── types/           # TypeScript type definitions
└── utils/           # Utility functions
    ├── retry.ts              # Retry logic with exponential backoff
    ├── circuit-breaker.ts    # Circuit breaker pattern
    └── secret-masking.ts     # Security utilities

🔑 Key Components

DirectLineClient

Handles all Direct Line API interactions with circuit breaker protection:

• Token generation
• Conversation creation
• Message sending
• Activity retrieval

TokenManager

Manages Direct Line tokens with:

• In-memory caching (no disk persistence for security)
• Automatic refresh 5 minutes before expiry
• Metrics tracking

ConversationManager

Tracks conversation state with:

• 30-minute idle timeout
• Watermark-based message tracking
• Message history buffering
• Automatic cleanup

CircuitBreaker

Prevents cascading failures with:

• 3 states: CLOSED, OPEN, HALF_OPEN
• Configurable failure threshold (5 failures in 30s)
• Recovery timeout (60s)
• Success threshold for recovery (3 consecutive successes)

🛡️ Error Handling

The server implements comprehensive error handling:

1. Retry Logic: Exponential backoff (1s, 2s, 4s delays, max 3 retries)
2. Circuit Breaker: Automatic fail-fast when service is degraded
3. Error Classification: Categorizes errors (network, auth, rate limit, etc.)
4. MCP Error Transformation: Converts internal errors to MCP-compliant responses

🔒 Security

• No Secret Logging: Direct Line secret and tokens are never logged
• Secret Masking: Shows only first 4 and last 4 characters in logs
• Environment Validation: Zod schema validation for configuration
• In-Memory Only: No disk persistence of sensitive data

📝 Troubleshooting

MCP Server Not Connecting in VS Code

1. Check the configuration path - Ensure the absolute path to dist/index.js is correct
2. Verify the build - Run npm run build to ensure TypeScript compiled successfully
3. Check logs - Look at VS Code logs for error messages
4. Test standalone - Run node dist/index.js to verify the server starts without errors
5. Restart VS Code - After making config changes, fully quit and restart

Direct Line Connection Issues

1. Verify Secret - Check that DIRECT_LINE_SECRET is correct in your configuration
2. Check Bot Status - Ensure your Copilot Studio Agent is published and Direct Line channel is enabled
3. Review Logs - Server logs will show connection attempts and errors

Common Errors

Failed to generate Direct Line token

• Verify your DIRECT_LINE_SECRET is correct
• Check that the Direct Line channel is enabled in Azure Bot Service

Conversation not found or expired

• Conversations expire after 30 minutes of inactivity
• Start a new conversation with start_conversation tool

Circuit breaker is OPEN

• The server detected multiple failures and is protecting against cascading failures
• Wait 60 seconds for the circuit breaker to attempt recovery
• Check Direct Line API connectivity

Example VS Code mcp.json Configuration

Here's a complete example configuration using npx (works on all platforms):

{
  "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}",
        "LOG_LEVEL": "info",
        "TOKEN_REFRESH_INTERVAL": "1800000"
      }
    }
  }
}

Alternative: Hardcoded secret (not recommended for shared projects):

{
  "servers": {
    "copilot-studio-agent-direct-line-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "copilot-studio-agent-direct-line-mcp"],
      "env": {
        "DIRECT_LINE_SECRET": "your_secret_here"
      }
    }
  }
}

🧪 Testing

Testing the MCP Server

The easiest way to test is through VS Code after installation:

1. Install using the one-click badge or manual npx configuration
2. Open GitHub Copilot Chat in Agent Mode
3. Try prompts like:
   • "Start a conversation with my Copilot Studio Agent"
   • "Send a message: Hello, what can you help me with?"
   • "Get the conversation history"

Running Test Client (For Development)

If you've cloned the repository, you can run the included test client:

# Set your Direct Line secret
export DIRECT_LINE_SECRET=your_secret_here

# Run tests
npx tsx tests/test-mcp-client.ts

This will test all 4 MCP tools and verify integration with your Copilot Studio Agent.

📌 Contributing

We welcome contributions! Please file issues for bugs, enhancements, or documentation improvements.

For development setup:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Run tests: npm test
5. Commit your changes: git commit -am 'Add new feature'
6. Push to the branch: git push origin feature/my-feature
7. Submit a pull request

License

Licensed under the MIT License.

💬 Support

For issues or questions, please open an issue on GitHub.

---

This project is not affiliated with or endorsed by Microsoft Corporation.