microsoft

Microsoft Graph

Complete guide to using Matimo's Microsoft Graph tools for searching organizational knowledge, reading and writing OneDrive/SharePoint files, managing Outlook mail and calendar events, posting to Microsoft Teams, and publishing SharePoint pages.

All Available Tools

Tool	Purpose	Risk
ms_search_knowledge	Search SharePoint sites, OneDrive/SharePoint files, and list items	low
ms_read_file	Read a file's contents from OneDrive/SharePoint	low
ms_list_files	List the children of a OneDrive/SharePoint folder	low
ms_get_email	List messages in the signed-in user's mailbox	low
ms_send_email	Send an email as the signed-in user	high — requires approval
ms_send_teams_message	Post or reply to a message in a Teams channel	medium
ms_create_document	Upload a small file (≤4 MB) to OneDrive/SharePoint	medium
ms_create_calendar_event	Create a calendar event, optionally a Teams meeting	medium
ms_publish_to_sharepoint	Create and publish a SharePoint site page	high — requires approval

Authentication

Microsoft Graph tools use delegated OAuth2 access tokens via the microsoft provider (see the package's definition.yaml). Matimo never performs the OAuth code exchange itself — a valid Graph access token must already be available, supplied either as:

• credentials.MICROSOFT_GRAPH_ACCESS_TOKEN on the execution context, or
• the MICROSOFT_GRAPH_ACCESS_TOKEN environment variable

Common delegated scopes: Sites.Read.All, Files.Read.All, Files.ReadWrite, Mail.Read, Mail.Send, ChannelMessage.Send, Calendars.ReadWrite, Sites.Manage.All. Each tool's YAML lists the narrower scopes it actually needs.

---

Searching Organizational Knowledge

Use ms_search_knowledge with:

• query (required) — KQL-style search string, e.g. "Q3 budget filetype:xlsx"
• entity_types — which content types to search (driveItem, listItem, site, list, drive); defaults to [driveItem, listItem, site]
• top — max results, 1-25 (default 10)
• site_id / drive_id — best-effort scoping hints, folded into the query string. Microsoft Search has no dedicated server-side filter for sites/drives on these entity types, so don't expect a hard filter — narrow the query text itself for reliable scoping.