Azure Setup Guide

Summary: Register a Microsoft Azure app so Outlook Assistant can access your email, calendar, and contacts through the Microsoft Graph API.

This guide walks through the full Azure setup from scratch, including creating an account if you don’t have one. The whole process takes about 10 minutes.

Prerequisites#

• A web browser
• A Microsoft account (personal Outlook.com/Hotmail, or work/school)
• Node.js 18.18+ and Outlook Assistant installed (see README)

1. Create an Azure Account#

Already have an Azure account? Skip to Step 2: Register an App.

Sign up for a free account at azure.microsoft.com/free. You’ll need:

• A phone number for verification
• A credit or debit card

Important: Payment Method Required#

Microsoft requires a payment method even for the free tier. Your card won’t be charged — there’s only a temporary $1 authorisation hold for verification, which is reversed.

However, if you don’t add a payment method, Microsoft will deactivate your account after approximately 30 days. The app registration you create will stop working.

What About Costs?#

App registration is part of Microsoft Entra ID Free tier and costs nothing. You don’t need to pay anything to use Outlook Assistant. The free tier includes:

What	Cost
App registration	Free (always)
Microsoft Graph API calls (delegated)	Free (always)
$200 Azure credit	First 30 days (not needed for Outlook Assistant)

Gotcha: After 30 days, Azure disables “pay-as-you-go” subscriptions that haven’t been upgraded. Your app registration still works because it’s part of the always-free Entra ID tier — but you must have a valid payment method on file to keep your account active.

2. Register an App#

Navigate to App Registrations#

1. Sign in to portal.azure.com
2. In the top search bar, type App registrations and select it

App registrations are part of Microsoft Entra ID (formerly Azure Active Directory). Microsoft’s newer portal at entra.microsoft.com also provides access via Identity > Applications > App registrations. Both portals work identically — use whichever you prefer.

Create the Registration#

3. Click New registration
4. Fill in the form:

Field	What to Enter
Name	Outlook Assistant Server (or any name you like — you can change it later)
Supported account types	Select Accounts in any organizational directory and personal Microsoft accounts
Redirect URI — Platform	Select Web
Redirect URI — URI	http://localhost:3333/auth/callback

5. Click Register

Copy Your Application ID#

After registration, you’ll see the app’s Overview page. Copy the Application (client) ID — this is a UUID like 12345678-abcd-1234-efgh-123456789012.

This becomes your OUTLOOK_CLIENT_ID.

What about Directory (tenant) ID? With the recommended account type you don’t need it: Outlook Assistant uses the /common/ endpoint by default. If you register a single-tenant app instead, set OUTLOOK_AUTH_AUDIENCE to your tenant ID (see below).

Account Type Explained#

The recommended setting — “any organizational directory and personal Microsoft accounts” — means:

Account Type	Supported
Personal (Outlook.com, Hotmail, Live)	Yes
Work/school (Microsoft 365)	Yes
Any organisation’s Microsoft 365	Yes

If you only use a personal Outlook.com account, you could select “Personal Microsoft accounts only” instead, but then you must also set OUTLOOK_AUTH_AUDIENCE=consumers in your MCP client’s env block, or sign-in fails with AADSTS9002331. Likewise, a work-only (“this organizational directory only”) app needs OUTLOOK_AUTH_AUDIENCE set to organizations or the tenant ID. The broader setting works for everyone without it.

3. Add API Permissions#

Outlook Assistant needs permission to access your mailbox data. These are delegated permissions — the app acts on your behalf and can only access what you can access.

Add the Permissions#

1. From your app registration, click API permissions in the left sidebar
2. Click Add a permission
3. Select Microsoft Graph
4. Select Delegated permissions
5. Search for and check each permission below, then click Add permissions

Required Permissions#

Permission	What It Allows
offline_access	Keep access between sessions (refresh tokens)
User.Read	Read your basic profile
Mail.Read	Read your emails
Mail.ReadWrite	Read, create, update, and delete emails
Mail.Send	Send emails on your behalf
Calendars.Read	Read your calendar events
Calendars.ReadWrite	Create, update, and delete calendar events
Contacts.Read	Read your contacts
Contacts.ReadWrite	Create, update, and delete contacts
MailboxSettings.ReadWrite	Read and update mailbox settings (auto-replies, working hours, categories)
People.Read	Search for relevant people

Optional Permissions#

Permission	What It Allows
Mail.Read.Shared	Read shared mailboxes. Requested only when you set OUTLOOK_SHARED_MAILBOX=read or true (work/school accounts)
Mail.ReadWrite.Shared	Organise shared mailboxes — move/categorise/flag/mark-read/create folders via sharedMailbox. Requested only with OUTLOOK_SHARED_MAILBOX=true. Sending/drafting from a shared mailbox isn’t supported, so Mail.Send.Shared is not requested
Place.Read.All	Search for meeting rooms (only if you use the find-meeting-rooms tool)

You can add all permissions now, or start with the required ones and add optional ones later. You’ll need to re-authenticate (auth action=authenticate force=true) after adding new permissions — a token refresh keeps the scopes you were originally granted. See Access Shared Mailboxes for turning on the .Shared scopes.

For Work/School Accounts: Admin Consent#

If you’re using a work/school Microsoft 365 account, your organisation may require admin consent for certain permissions. This depends on your organisation’s user consent settings in Microsoft Entra ID — it is not a universal Microsoft requirement. Some organisations restrict users from granting apps access to mail and calendar data without admin approval.

How to tell if admin consent is needed: When you try to authenticate, Microsoft will either let you grant permissions yourself, or show a message saying “Need admin approval”. If you see the latter, your organisation requires admin consent for this app.

If you’re the admin: Click the Grant admin consent for [your organisation] button on the API permissions page.

If you’re not the admin: Ask your IT administrator to grant consent. They can do this from the Entra admin centre, or you can share the app’s Application ID with them.

Personal Outlook.com accounts are not affected — you can grant consent yourself during the OAuth flow.

4. Create a Client Secret#

Only needed for the browser redirect flow. The default device-code sign-in (step 5) doesn’t use a client secret, so you can skip this step and leave OUTLOOK_CLIENT_SECRET unset.

The client secret proves your app’s identity when the browser flow exchanges its authorisation code for tokens.

1. From your app registration, click Certificates & secrets in the left sidebar
2. Click the Client secrets tab
3. Click New client secret
4. Enter a description (e.g. Outlook Assistant)
5. Select an expiration:

Option	When to Use
24 months	Personal/hobby use (less rotation hassle)
12 months	Balanced option
6 months	Microsoft’s recommended default for production

6. Click Add

Copy the Secret Value — Now#

After clicking Add, the portal shows three columns:

Column	What It Is	Use This?
Description	The label you entered	No
Value	The actual secret (e.g. aB1cD~2eF3gH4iJ5kL6mN7oP8qR9sT0uV1wX)	YES — this is your OUTLOOK_CLIENT_SECRET
Secret ID	A GUID identifying the secret object	NO — do not use this

The Value is only shown once. If you navigate away without copying it, you’ll need to create a new secret. Copy it now and store it securely.

The most common setup error is using the Secret ID (a UUID) instead of the Value (a longer string with special characters). This causes the AADSTS7000215 error.

When Your Secret Expires#

Set a calendar reminder before your secret expires. To rotate:

1. Create a new secret (while the old one still works)
2. Update your OUTLOOK_CLIENT_SECRET configuration
3. Verify authentication works
4. Delete the old secret

5. Enable Device Code Flow (Recommended)#

The device code flow lets you authenticate without running the auth server — ideal for remote, headless, and container environments.

1. From your app registration, click Authentication in the left sidebar
2. Click Add a platform
3. Select Mobile and desktop applications
4. Check the box for https://login.microsoftonline.com/common/oauth2/nativeclient
5. Click Configure
6. Scroll down to Advanced settings
7. Set Allow public client flows to Yes
8. Click Save

Why? Device code flow is a “public client” flow that doesn’t require the client secret during authentication. This is the default auth method in Outlook Assistant v3.5.1+. The native client redirect URI tells Microsoft to handle device code sign-in correctly. In v3.7.2+, device code state is persisted to disk (~/.outlook-assistant-pending-auth.json) so authentication survives MCP server restarts, and token refresh correctly omits client_secret for public client tokens.

If you skip this step, you can still authenticate using the browser redirect flow (method=browser), but you’ll need to run the auth server on port 3333.

When signing in at microsoft.com/devicelogin, use a private/incognito browser window. Cached sessions from previous OAuth flows can interfere with device code authentication.

6. Configure Outlook Assistant#

You now have:

• Application (client) ID → OUTLOOK_CLIENT_ID (always needed)
• Client secret Value → OUTLOOK_CLIENT_SECRET (browser flow only; omit it for device-code sign-in)

You can also leave OUTLOOK_CLIENT_ID out of your config. Your assistant then asks for it the first time you connect and saves it to ~/.outlook-assistant-config.json (auth action=authenticate clientId=…). An environment value always takes precedence over the saved one.

Option A: MCP Client Config (Recommended)#

Add to your MCP client config (example for Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "outlook": {
      "command": "npx",
      "args": ["@littlebearapps/outlook-assistant"],
      "env": {
        "OUTLOOK_CLIENT_ID": "your-application-client-id",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-VALUE"
      }
    }
  }
}

Option B: Environment File (auth server only)#

The MCP server takes its settings from your MCP client’s env block and doesn’t read .env files. The browser-flow auth server does, so if you use that flow from a source checkout, create a .env file in the project root:

OUTLOOK_CLIENT_ID=your-application-client-id
OUTLOOK_CLIENT_SECRET=your-client-secret-VALUE
USE_TEST_MODE=false

Backwards compatibility: The server also accepts MS_CLIENT_ID and MS_CLIENT_SECRET.

Verify It Works#

1. Authenticate (Device Code Flow)#

In your AI assistant, use the auth tool with action=authenticate. With the default device code flow it returns a short code and the URL microsoft.com/devicelogin.

1. Open the URL in a private/incognito browser window, on any device
2. Enter the code and sign in with your Microsoft account
3. Review and accept the requested permissions
4. Back in your AI assistant, use the auth tool with action=device-code-complete

Tokens are saved to ~/.outlook-assistant-tokens.json and refresh automatically. No auth server is needed.

Browser redirect flow instead? Start the auth server first (npm run auth-server from source, or node "$(npm root -g)/@littlebearapps/outlook-assistant/outlook-auth-server.js" from a global install), then use auth with action=authenticate and method=browser. The auth server reads OUTLOOK_CLIENT_ID and OUTLOOK_CLIENT_SECRET (or the legacy MS_CLIENT_ID/MS_CLIENT_SECRET) from the environment or a .env file in the directory you start it from.

2. Verify Access#

In your AI assistant, use the auth tool with action=status. You should see “Authenticated and ready” with the token’s remaining lifetime. Use action=about to see which mailbox is connected and which scopes were granted.

Then try search-emails to confirm email access is working.

Troubleshooting#

AADSTS7000215: Invalid Client Secret#

Cause: You’re using the Secret ID instead of the Secret Value.

Fix: Go to Azure Portal > your app > Certificates & secrets. If you can still see the Value, copy it. If not, create a new secret and copy the Value immediately.

Other causes:

• Secret has expired (check the expiration date)
• Whitespace was accidentally included when copying
• The secret belongs to a different app registration

---

AADSTS50011: Redirect URI Mismatch#

Cause: The redirect URI in your app registration doesn’t match what the auth server sends.

Fix:

1. Go to Azure Portal > your app > Authentication
2. Under Platform configurations, check that http://localhost:3333/auth/callback is listed
3. Make sure the platform is Web (not SPA or Mobile)
4. The URI must match exactly — check for typos, trailing slashes, and http vs https

---

Permission Denied / 403 Errors#

Cause: Missing API permissions or consent not granted.

Fix:

1. Check that all required permissions are added (see Step 3)
2. For work accounts: admin consent may be required — ask your IT admin
3. Re-authenticate with auth action=authenticate force=true to pick up new permissions, then check auth action=about for the granted scopes

---

Token Refresh Fails After Days/Weeks#

Cause: Refresh tokens can expire after extended inactivity (90+ days) or when passwords change.

Fix: Re-authenticate with auth action=authenticate force=true (device code flow), then auth action=device-code-complete. If the token file itself is corrupted, delete it first:

rm ~/.outlook-assistant-tokens.json
# Then use the auth tool with action=authenticate in your AI assistant

---

“EADDRINUSE: address already in use :::3333”#

Cause: The auth server port is already in use.

Fix:

npx kill-port 3333
npm run auth-server

---

Missing Permissions / Scope Mismatch After Adding New Permissions#

Cause: You added new API permissions in Azure Portal but your existing tokens still have the old scopes.

Fix: Re-authenticate to pick up the new permissions — token refresh never adds scopes:

auth action=authenticate force=true
auth action=device-code-complete

After re-authenticating, use the auth tool with action=about to check the new scopes appear under Granted scopes. For the .Shared scopes, OUTLOOK_SHARED_MAILBOX must also be set before you sign in.

What’s Next?#

• Connect Outlook to Your AI Assistant — Install, configure your MCP client, and authenticate
• README — Full feature overview and configuration
• Tools Reference — All 22 tools with parameters
• Back to Docs