Microsoft Teams Chats & Channels
Catch up on Microsoft Teams and answer without switching apps: read channel threads and their replies, read one-on-one and group chats, see who is in a team or chat, and post a channel message, a thread reply or a chat message (HTML allowed) as the signed-in user.
Connect this API to an AI agent Browse all specs
What you can do with Microsoft Teams Chats & Channels via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /me/joinedTeams |
listJoinedTeams | List the teams the signed-in user belongs to |
| GET | /teams/{team-id}/channels |
listChannels | List a team's channels |
| GET | /teams/{team-id}/channels/{channel-id} |
getChannel | Get a channel's name, description and link |
| GET | /teams/{team-id}/channels/{channel-id}/messages |
listChannelMessages | List the top-level posts in a channel |
| POST | /teams/{team-id}/channels/{channel-id}/messages |
sendChannelMessage | Post a new message in a channel |
| GET | /teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id} |
getChannelMessage | Get one channel post |
| GET | /teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/replies |
listReplies | List the replies in a channel thread |
| POST | /teams/{team-id}/channels/{channel-id}/messages/{chatMessage-id}/replies |
replyToChannelMessage | Reply in a channel thread |
| GET | /teams/{team-id}/channels/{channel-id}/members |
listChannelMembers | List the members of a channel |
| GET | /teams/{team-id}/members |
listTeamMembers | List the members of a team |
| GET | /me/chats |
listMyChats | List the signed-in user's one-on-one, group and meeting chats |
| GET | /chats/{chat-id} |
getChat | Get a chat's topic, type and web link |
| GET | /chats/{chat-id}/messages |
listChatMessages | List the messages in a chat |
| POST | /chats/{chat-id}/messages |
sendChatMessage | Send a message in a chat |
| GET | /chats/{chat-id}/messages/{chatMessage-id} |
getChatMessage | Get one chat message |
| GET | /chats/{chat-id}/members |
listChatMembers | List the people in a chat |
Authentication
microsoftOAuth
OAuth 2.0
Scopes: https://graph.microsoft.com/Team.ReadBasic.All https://graph.microsoft.com/Channel.ReadBasic.All https://graph.microsoft.com/ChannelMessage.Read.All https://graph.microsoft.com/ChannelMessage.Send https://graph.microsoft.com/ChannelMember.Read.All https://graph.microsoft.com/TeamMember.Read.All https://graph.microsoft.com/Chat.ReadBasic https://graph.microsoft.com/Chat.Read https://graph.microsoft.com/ChatMessage.Send offline_access
How to get a credential
- Sign in to the Microsoft Entra admin center (entra.microsoft.com) with an account in your Microsoft 365 tenant.
- Go to App registrations → New registration, choose the supported account types and add the VX Agents redirect URI shown on the credential form (platform Web).
- Under Certificates & secrets, create a client secret and copy its value.
- Under API permissions → Microsoft Graph → Delegated, add the scopes below.
ChannelMessage.Read.All,ChannelMember.Read.AllandTeamMember.Read.Allneed admin consent. - Enter the Application (client) ID and secret in VX Agents and sign in as the Teams user the agent should act as.
Permissions used
| Scope | Operations |
|---|---|
| Team.ReadBasic.All | listJoinedTeams |
| Channel.ReadBasic.All | listChannels, getChannel |
| ChannelMessage.Read.All | listChannelMessages, getChannelMessage, listReplies |
| ChannelMessage.Send | sendChannelMessage, replyToChannelMessage |
| ChannelMember.Read.All | listChannelMembers |
| TeamMember.Read.All | listTeamMembers |
| Chat.ReadBasic | listMyChats, getChat, listChatMembers |
| Chat.Read | listChatMessages, getChatMessage |
| ChatMessage.Send | sendChatMessage |
| offline_access | refresh tokens |
Common errors
- 401 Unauthorized: the token expired; reconnect the credential.
- 403 Forbidden: a scope above is missing or lacks admin consent, or the user is not a member of that team, channel or chat.
- 400 Bad Request:
body.contentmissing, orcontentTypenottextorhtml. - 429 Too Many Requests: Teams throttling; wait for
Retry-After.
Store it as a VX Agents OAuth2 credential.
Usage guide
Setup
- Credential: Microsoft identity OAuth2 (authorization code, delegated) with the scopes in the credential docs.
ChannelMessage.Read.All,ChannelMember.Read.AllandTeamMember.Read.Allneed tenant admin consent. Everything runs as the signed-in user. - Worth pinning:
team-idandchannel-idof the channel the agent works in (fromlistJoinedTeams→listChannels, or from a channel link in Teams:groupIdis the team id and the19:[email protected]part is the channel id).
Catch up on a channel and reply
listJoinedTeams→ pick the team;listChannels→ pick the channel.listChannelMessageswith$topfor the latest posts. Follow@odata.nextLinkfor older ones.listReplieson a post to read its thread;getChannelMessagefor one post.replyToChannelMessagewith{"body": {"contentType": "html", "content": "..."}}to answer in the thread, orsendChannelMessage(optionalsubject) for a new post.
Chats
listMyChats($expand=membersshows who is in each;chatTypeisoneOnOne,groupormeeting).listChatMessageswith$top(up to 50), thensendChatMessageto answer. Chats have no threads.listChatMembers,listChannelMembersandlistTeamMembersgive user ids and display names for @mentions.
Before any send or reply, show the final text and the target team/channel or chat to the user and get a yes: messages go out under the user's name and notify people.
Good to know
- @mention: put
<at id="0">Ada Lovelace</at>in HTML content and add{"id": 0, "mentionText": "Ada Lovelace", "mentioned": {"user": {"id": "<user id>", "displayName": "Ada Lovelace", "userIdentityType": "aadUser"}}}tomentions. - Message
body.contentcomes back as HTML; strip tags before summarising. System events appear withmessageTypeother thanmessage. - Ids: team ids are GUIDs, channel and chat ids look like
19:...@thread...; message ids are numbers in a string. - Times are ISO 8601 UTC.
- On 429, wait for
Retry-After.
Source: Microsoft Graph Teams API reference (https://learn.microsoft.com/en-us/graph/api/resources/teams-api-overview?view=graph-rest-1.0), checked 2026-10-19.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Microsoft Teams Chats & Channels” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.