agentic-msteams-mcp

A self-hosted Microsoft Teams MCP server that serves as an agnostic human-in-the-loop gateway for AI agents.

Overview

This project implements a dual-surface architecture to allow AI agents to interact with humans via Microsoft Teams without requiring the agent to have direct Graph API access or complex bot logic.

v0.4.0 Feature: Human-in-the-Loop & Approvals

v0.4.0 provides a comprehensive suite of tools for agents to interact with humans via Microsoft Teams, including notifications, asynchronous questions, and formal approval workflows.

• msteams_send_notification: Sends one-way alerts.

• msteams_ask_user: Poses structured questions; returns request_id.

• msteams_get_user_reply: Tracks responses to asks.

• msteams_request_approval: Requests a formal binary decision (Approve/Reject).

• msteams_get_approval: Checks the state of an approval request.

Related MCP server: Teams Messenger MCP App

Core Architecture

1. The MCP Surface (Stdio)

The primary interface for AI agents. It exposes a strictly limited toolset of six tools:

• msteams_health_check: Verifies server connectivity.

• msteams_send_notification: Sends one-way alerts to allowlisted users/channels.

• msteams_ask_user: Requests information from an allowlisted user.

• msteams_get_user_reply: Checks the state of a requested reply.

• msteams_request_approval: Initiates a formal approval request.

• msteams_get_approval: Retrieves the decision for an approval request.

2. The Teams Surface (HTTP)

A lightweight FastAPI app that acts as the webhook receiver for Microsoft Teams. It is designed to be hosted behind a proxy/gateway.

Security Model (Secure-by-Design)

Closed-World Toolset

The server explicitly denies any arbitrary Graph API operations. All interactions are gated through specific, high-level tools.

Fail-Closed Allowlist

Notifications and Asks are only delivered to IDs defined in the MSTEAMS_ALLOWED_USER_IDS or MSTEAMS_ALLOWED_CHANNEL_IDS environment variables. If an ID is not listed, the request is rejected immediately.

Audit Logging

Every attempt to notify or ask a user is logged to a local audit file (MSTEAMS_AUDIT_LOG_PATH).

• Privacy: Log entries contain metadata and fingerprints but NEVER include the actual message or question body.

• Stability: Uses SHA-256 deterministic fingerprinting for audit evidence.

Dry-Run Mode

By default, MSTEAMS_NOTIFICATION_DRY_RUN=True. In this mode, the server validates all requests and logs them to audit but does not actually call the Microsoft Graph API. NOTE: Real Teams/Graph delivery is currently not implemented; dry-run is the intended safe default for current versions.

Installation & Configuration

Environment Variables

Running the Server

The server provides two distinct modes:

1. MCP Stdio Mode (for AI Agents)

python -m agentic_msteams_mcp.main --mcp

2. HTTP Surface Mode (for Teams Webhooks)

python -m agentic_msteams_mcp.main --http

Deployment

The server is provided as a Docker image for consistent runtime environments.

docker build -t agentic-msteams-mcp .
docker run -p 8000:8000 -e MSTEAMS_ALLOWED_USER_IDS="user1,user2" agentic-msteams-mcp --http