Configuration

msgraph is configured through environment variables. All settings have sensible defaults.

Setting Environment Variables

The quickest way is to create a .env file in your project root (the same directory where you run the agent/CLI). Use simple KEY=VALUE lines (no export). Example:

MSGRAPH_CLIENT_ID=your-app-id
MSGRAPH_TENANT_ID=contoso.onmicrosoft.com

How different platforms pick up the .env file:

• Claude Code, Cursor, OpenCode, Windsurf, Goose: Read .env from the workspace root automatically.
• VS Code / GitHub Copilot: Uses the terminal environment. Either put vars in your shell profile (~/.zshrc, ~/.bashrc) or load a .env via your terminal/extension before running msgraph.
• CI/CD or Docker: Set environment variables in your pipeline config, Dockerfile, or docker run -e flags.

One-off shell session: you can also export variables directly in your terminal before running the tool:

export MSGRAPH_CLIENT_ID="your-app-id"
export MSGRAPH_TENANT_ID="contoso.onmicrosoft.com"

Environment Variables

Core

Variable	Description	Default
MSGRAPH_CLIENT_ID	Entra ID app registration client ID	14d82eec-204b-4c2f-b7e8-296a70dab67e
MSGRAPH_TENANT_ID	Target tenant ID	common
MSGRAPH_API_VERSION	Default Graph API version	beta
MSGRAPH_INDEX_DB_PATH	Path to the OpenAPI index database	Auto-detected
MSGRAPH_NO_TOKEN_CACHE	Disable persisted token cache (in-memory only)	false

App-Only Auth

Variable	Description	Required for
MSGRAPH_CLIENT_SECRET	App registration client secret	Client secret auth
MSGRAPH_CLIENT_CERTIFICATE_PATH	Path to PEM certificate file (cert + key)	Certificate auth
MSGRAPH_CLIENT_CERTIFICATE_PASSWORD	Password for encrypted private key	Certificate auth (optional)
MSGRAPH_AUTH_METHOD	Set to managed-identity to use managed identity	Managed identity auth
MSGRAPH_MANAGED_IDENTITY_CLIENT_ID	Client ID for user-assigned managed identity	Managed identity (optional)
MSGRAPH_FEDERATED_TOKEN_FILE	Path to federated token file	Workload identity auth

Auto-Read Variables

These standard environment variables are also read as fallbacks:

Variable	Used by	Fallback for
AZURE_FEDERATED_TOKEN_FILE	AKS workload identity	MSGRAPH_FEDERATED_TOKEN_FILE
AWS_WEB_IDENTITY_TOKEN_FILE	AWS IRSA / EKS	MSGRAPH_FEDERATED_TOKEN_FILE
AZURE_CLIENT_ID	AKS workload identity	MSGRAPH_CLIENT_ID
AZURE_TENANT_ID	AKS workload identity	MSGRAPH_TENANT_ID

Auth Method Detection

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

1. Client secret — MSGRAPH_CLIENT_SECRET is set
2. Client certificate — MSGRAPH_CLIENT_CERTIFICATE_PATH is set
3. Workload identity — MSGRAPH_FEDERATED_TOKEN_FILE (or AZURE_FEDERATED_TOKEN_FILE / AWS_WEB_IDENTITY_TOKEN_FILE) is set
4. Managed identity — MSGRAPH_AUTH_METHOD=managed-identity
5. Delegated (default) — none of the above

There is no need to explicitly set an auth method variable (except for managed identity which requires MSGRAPH_AUTH_METHOD=managed-identity).

Client ID

The default client ID (14d82eec-204b-4c2f-b7e8-296a70dab67e) is the Microsoft Graph Command Line Tools app. This is a first-party Microsoft app that is pre-registered in most Microsoft 365 tenants.

When to use a custom client ID

• Your organization blocks the default app
• You need app-specific consent policies
• You want to track usage separately
• You are using app-only auth (client secret, certificate, or workload identity)

Setting up a custom app

1. Go to Azure Portal > App Registrations
2. Click “New registration”
3. Set redirect URI to http://localhost (Mobile and desktop applications) — for delegated auth only
4. Note the Application (client) ID
5. Under API Permissions:
   • For delegated auth: add Delegated permissions
   • For app-only auth: add Application permissions and grant admin consent
6. Under Certificates & secrets:
   • For client secret auth: add a client secret
   • For certificate auth: upload a public certificate
   • For workload identity: add a federated credential
7. Set the environment variable:

export MSGRAPH_CLIENT_ID="your-app-id"

Tenant ID

The default tenant (common) allows sign-in to any Entra ID tenant. To restrict to a specific tenant:

export MSGRAPH_TENANT_ID="contoso.onmicrosoft.com"
# or use the tenant GUID
export MSGRAPH_TENANT_ID="12345678-1234-1234-1234-123456789012"

Important: App-only auth requires a specific tenant ID. Using common, organizations, or consumers with app-only auth will produce an error.

API Version

Version	Description
beta (default)	Latest features, may change without notice
v1.0	Stable, production-ready

Override per-session:

export MSGRAPH_API_VERSION="v1.0"

Or per-request:

msgraph graph-call GET /me --api-version v1.0

OpenAPI Index

The tool uses a SQLite FTS5 database (graph-api-index.db) for full-text search with BM25 ranking. It searches for the database in these locations (in order):

1. MSGRAPH_INDEX_DB_PATH environment variable
2. references/graph-api-index.db (relative to the skill or CLI location)

Override if the index database is in a non-standard location:

export MSGRAPH_INDEX_DB_PATH="/path/to/graph-api-index.db"

Token Cache

Tokens are cached by default using an encrypted on-disk cache with the key stored in the OS keyring. This keeps sign-ins silent after the first authentication and survives process restarts.

To turn off the persisted cache and keep tokens in-memory only for the current process, set:

export MSGRAPH_NO_TOKEN_CACHE=true

When disabled, every new process will require a fresh sign-in. This is useful for CI/CD, ephemeral containers, or shared environments where you do not want tokens written to disk.