Microsoft Graph Agent Skill

msgraph-skill

Quick Start

1. Check auth status before making any Graph call:

   msgraph-skill auth status

2. Sign in if not authenticated:

   msgraph-skill auth signin

3. Make Graph API calls:

   msgraph-skill graph-call GET /me

Authentication

• Interactive browser auth is the default — a browser window opens for sign-in
• Device code flow is used automatically when no browser is detected (SSH sessions, containers) or can be forced with

  --device-code

• Incremental consent is handled automatically — if a 403 Forbidden is returned, the tool re-authenticates with the required scopes and retries
• Session-scoped cache — tokens are cached in a temp file for the session only; no persistent credential storage

Auth Commands

msgraph-skill auth signin

msgraph-skill auth signin --device-code

msgraph-skill auth signin --scopes "Mail.Read,Calendars.Read"

msgraph-skill auth signout

msgraph-skill auth status

msgraph-skill auth switch-tenant <tenant-id>

Making Graph API Calls

msgraph-skill graph-call <METHOD> <URL>

Read Operations (default)

# Get current user profile
msgraph-skill graph-call GET /me

# List users with selected fields
msgraph-skill graph-call GET /users --select "displayName,mail,userPrincipalName" --top 10

# Get user's mail with filtering
msgraph-skill graph-call GET /me/messages --filter "isRead eq false" --top 5 --select "subject,from,receivedDateTime"

# List groups
msgraph-skill graph-call GET /groups --select "displayName,description" --top 25

# Get team channels
msgraph-skill graph-call GET /teams/{team-id}/channels

# Search users
msgraph-skill graph-call GET /users --filter "startsWith(displayName,'John')"

Write Operations (requires --allow-writes)

--allow-writes

# Send a message (ask user first!)
msgraph-skill graph-call POST /me/sendMail --body '{"message":{"subject":"Hello","body":{"content":"Hi there"},"toRecipients":[{"emailAddress":{"address":"user@example.com"}}]}}' --allow-writes

# Update user properties (ask user first!)
msgraph-skill graph-call PATCH /me --body '{"jobTitle":"Engineer"}' --allow-writes

Query Parameters

--select

--select "displayName,mail"

--filter

--filter "isRead eq false"

--top

--top 10

--expand

--expand "members"

--orderby

--orderby "displayName"

--api-version

--api-version v1.0

--scopes

--scopes "Mail.Read"

--headers

--headers "ConsistencyLevel:eventual"

--output

--output raw

Finding the Right Endpoint

Strategy

1. First: Try constructing the Graph API call from your training knowledge. The Microsoft Graph API follows consistent patterns:

   • /me

     — current user

   • /users

     — all users

   • /users/{id}

     — specific user

   • /me/messages

     — current user's mail

   • /groups

     — all groups

   • /teams/{id}/channels

     — team channels
2. If unsure: Use the OpenAPI search command to find endpoints:

   msgraph-skill openapi-search --query "send mail"
   msgraph-skill openapi-search --resource users --method GET
   msgraph-skill openapi-search --query "calendar events" --method POST

3. Check the reference for detailed API documentation: See references/REFERENCE.md for common Graph API patterns and endpoint details.

OpenAPI Search Command

# Search by keyword
msgraph-skill openapi-search --query "list users"

# Search by resource and method
msgraph-skill openapi-search --resource messages --method GET

# Combined search
msgraph-skill openapi-search --query "create" --resource groups --method POST

Important Rules

1. Always check auth status before the first Graph call in a session
2. GET requests are the default — no special flags needed
3. Write operations require

   --allow-writes

   — always confirm with the user first
4. DELETE is always blocked — inform the user this is not supported
5. The default API version is beta — use

   --api-version v1.0

   for production-stable endpoints
6. 403 errors trigger automatic re-auth — the tool will request additional scopes and retry
7. All output is JSON — parse the

   statusCode

   and

   body

   fields from the response

Error Handling

• 401 Unauthorized: Token expired. Run

  msgraph-skill auth signin

  again.
• 403 Forbidden: Insufficient permissions. The tool automatically attempts incremental consent. If it still fails, the user may need admin consent for those permissions.
• 404 Not Found: The resource doesn't exist or the URL is incorrect. Verify the endpoint path.
• 429 Too Many Requests: Rate limited. Wait and retry.

Environment Variables

MSGRAPH_CLIENT_ID

MSGRAPH_TENANT_ID

common

MSGRAPH_API_VERSION

beta

MSGRAPH_INDEX_PATH