How It Works

This page explains the technical internals of msgraph for those who want to understand or extend it.

Architecture Overview

The diagram below shows how an AI agent interacts with the skill. The search layer runs entirely locally against pre-built SQLite FTS5 databases — no network calls, no auth. The execution layer is optional and requires authentication.

Expand

Agent Workflow

When an agent receives a user request involving Microsoft 365 data, it follows a progressive lookup strategy — each level adds more detail:

1. Own knowledge — try first for well-known endpoints (/me, /users, /groups).
2. sample-search — curated, hand-verified samples. Highest quality. Best for common tasks and multi-step workflows.
3. api-docs-search — per-endpoint permissions, supported query parameters, required headers, and resource property details with filter operators.
4. openapi-search — full catalog of 27,700 APIs. Use when the endpoint can’t be found any other way.
5. Reference files — concept docs on paging, batching, throttling, errors, and best practices.

Build Pipeline

The search indexes are built offline and bundled with the skill. Each release runs the indexer tools to produce fresh databases:

Expand

Technical Details

Auth Method Detection

The auth method is auto-detected from environment variables in priority order:

1. MSGRAPH_CLIENT_SECRET set → Client secret
2. MSGRAPH_CLIENT_CERTIFICATE_PATH set → Certificate
3. MSGRAPH_FEDERATED_TOKEN_FILE (or AZURE_FEDERATED_TOKEN_FILE / AWS_WEB_IDENTITY_TOKEN_FILE) set → Workload identity
4. MSGRAPH_AUTH_METHOD=managed-identity → Managed identity
5. None of the above → Delegated (interactive browser / device code)

Silent Token Acquisition

After initial sign-in, tokens are cached. Subsequent calls use silent acquisition:

1. Check the in-memory/file cache for a valid token
2. If expired, MSAL automatically refreshes using the refresh token (delegated) or re-acquires via credentials (app-only)
3. Only if refresh fails does it prompt for interactive auth (delegated only)

Incremental Consent (Delegated Only)

When a 403 Forbidden occurs with delegated auth:

1. Parse the error message for required scope names (regex: [A-Z][a-zA-Z]+\.[A-Z][a-zA-Z]+)
2. Merge new scopes with existing scopes
3. Re-authenticate with the combined scope set
4. Retry the original request with the new token

Incremental consent is not available for app-only auth — all permissions must be pre-configured and admin-consented in the Entra ID app registration.

Safety Enforcement

Safety is enforced at the CLI level before any HTTP request is made:

Method	Default	With —allow-writes
GET	Allowed	Allowed
HEAD	Allowed	Allowed
OPTIONS	Allowed	Allowed
POST	Blocked	Allowed
PUT	Blocked	Allowed
PATCH	Blocked	Allowed
DELETE	Blocked	Blocked

DELETE is blocked unconditionally — there is no flag to enable it.

OpenAPI Index

The index is built by tools/openapi-indexer/:

1. Downloads the official Graph OpenAPI YAML (~60MB)
2. Parses using gopkg.in/yaml.v3 with flexible interface{} unmarshaling
3. Extracts path, method, summary, description, operation IDs, parameters, deprecation info, doc URLs, request/response schema refs, and security scopes
4. Outputs a SQLite FTS5 database (graph-api-index.db, ~27,000 endpoints)

The search algorithm uses SQLite FTS5 full-text search:

• BM25 ranking with weighted columns (path weight 10, summary 5, description 3)
• Porter stemming tokenizer for flexible term matching
• Filters by method (exact match) and resource (path segment match)
• Returns results ranked by relevance

Build System

• Cross-platform: Pre-built for macOS, Linux, and Windows (amd64 and arm64)
• Cross-compilation: 6 platform targets (darwin/linux/windows × amd64/arm64)
• Docs site: Astro + Starlight, deployed to GitHub Pages
• Monorepo: CLI source at root, npm workspace for docs