Teams MCP - Flows

User Connection Flow

Everything starts when a user connects to the MCP server. This triggers OAuth authentication. Once tokens are stored, the chat and messaging tools are immediately available.

Deployments with transcript capture enabled have an additional per-user step after this flow — creating the Microsoft Graph subscription. See Recordings & Transcripts — Subscription lifecycle.

OAuth Scopes Required: See Microsoft Graph Permissions for detailed justification.

Important: Microsoft access and refresh tokens are never sent to the client. They are received by the server, encrypted, and stored securely. After the Microsoft OAuth flow completes, the server issues opaque JWT tokens to the client for MCP authentication.

Microsoft OAuth Setup Flow

The following sequence shows the complete Microsoft OAuth authentication flow with detailed token handling:

Microsoft Token Refresh Flow

Microsoft tokens are refreshed on-demand when the Graph API returns a 401 error:

Transcript Capture Flows

When UNIQUE_INTEGRATION=enabled, the server also runs a webhook-driven capture pipeline: a Microsoft Graph subscription per user, lifecycle-notification renewal, and asynchronous transcript and recording ingestion into the Unique knowledge base. Those sequence diagrams live with the feature they belong to:

• Ingestion pipeline

• Subscription lifecycle

Chat Flows

The Chat Module exposes a synchronous request/response tool surface. Each tool call is handled inline — there is no queue or background worker, and nothing is stored in Unique.

Each tool targets a chat or channel by id: list_* tools return identifiers that the caller passes to subsequent get_*_messages or send_*_message calls. See also: Tools Reference.

Chat Read Flow

The read flow applies to both personal chats (list_chats → get_chat_messages) and team channels (list_teams → list_channels → get_channel_messages). The diagram below shows the personal chat variant; the channel variant substitutes list_teams/list_channels for list_chats and queries /teams/{teamId}/channels/{channelId}/messages instead of /chats/{chatId}/messages.

Key points:

• list_chats returns a single bounded page (no auto-pagination); hasMore indicates whether more chats exist.

• Graph does not support server-side messageType filtering on message endpoints. When excludeSystemMessages=true, the server pages through results client-side until the requested number of user messages is collected.

• Message bodies are returned as-is from Graph (HTML). The get_channel_messages path is identical but targets /teams/{teamId}/channels/{channelId}/messages.

Chat Search Flow

search_messages queries the Microsoft Search API (POST /search/query on Graph v1.0) and optionally hydrates each hit with its full message body.

Key points:

• Pagination uses offset/size on the request body and moreResultsAvailable on the response — not @odata.nextLink. The caller advances the page by incrementing offset by size.

• The source filter (chat/channel/all) is applied client-side after the Graph response, because the Search API's entityTypes: ['chatMessage'] covers both containers with no sub-filter.

• detail=full issues one additional Graph call per hit. Concurrency is capped at 5 to avoid Graph throttling. A forbidden or deleted hit falls back to its summary row rather than failing the page.

• See Tools Reference for the full search_messages parameter list.

Chat Send Flow

The send flow applies to personal chats (send_chat_message) and team channels (send_channel_message). The caller must first obtain the target ID via a list_* call.

Key points:

• Only plain-text messages are supported (contentType: 'text'). Rich HTML or adaptive cards are not sent.

• send_channel_message returns a webUrl linking directly to the posted message in Teams. send_chat_message returns only the message id.

• The entire flow is synchronous — the tool returns only after Graph confirms the message was created.

Related Documentation

• Architecture - System components and infrastructure

• Security - Encryption, PKCE, and threat model

• Microsoft Graph Permissions - Required scopes and least-privilege justification

• Recordings & Transcripts - Technical Manual - Subscription lifecycle and transcript ingestion flows

Standard References

• Microsoft Graph API - Graph API overview

• Microsoft Graph Webhooks - Webhook documentation

• Microsoft Graph Subscriptions - Subscription API reference