ms-365-mcp-server

In headless stdio environments, you can pin the local MSAL cache to a specific Microsoft account to ensure the server always uses the correct identity. This collapses the server into single-account mode (the account parameter is not advertised).

Pinning Methods

• By Username: Use --expected-username <username> (case-insensitive).
• By Home Account ID: Use --expected-home-account-id <homeAccountId> (exact match). Use npx @softeria/ms-365-mcp-server --list-accounts to find this ID.

Implementation via Environment Variables

You can also use:

• MS365_MCP_EXPECTED_USERNAME
• MS365_MCP_EXPECTED_HOME_ACCOUNT_ID

Note: CLI flags take precedence over environment variables.

Important Constraints

• Bootstrap Process: If the expected account is not in the cache, startup will fail. You must run --login with the pin set first to populate the cache.
• Cleanup: Use --logout to clear all accounts or --remove-account <id> for specific cleanup.

# Pin by username
MS365_MCP_EXPECTED_USERNAME=work@company.com npx @softeria/ms-365-mcp-server --login

# Pin by exact homeAccountId
npx @softeria/ms-365-mcp-server --expected-home-account-id <homeAccountId> --login

A single server instance can serve multiple accounts. When multiple accounts are logged in, the server injects an account parameter into every tool call, allowing you to specify which account to use.

Workflow

1. Login multiple accounts: Run npx @softeria/ms-365-mcp-server --login for each account you wish to add.
2. List accounts: Use npx @softeria/ms-365-mcp-server --list-accounts to see configured accounts.
3. Specify account in tool calls: Pass the email address or MSAL homeAccountId in the account argument.

Account Selection Behavior

• Single account: The server auto-selects the account; no account parameter is needed.
• Multiple accounts (no parameter): The server uses the default account or returns an error listing available accounts.
• Parameter values: Accepts email addresses (e.g., user@outlook.com) or MSAL homeAccountId.

// Example tool call specifying an account
{
  "tool": "list-mail-messages",
  "arguments": {
    "account": "work@company.com"
  }
}

In headless local-MSAL deployments, you can replace the built-in storage with a provider-neutral external command via MS365_MCP_AUTH_CACHE_COMMAND. The server invokes this executable with specific subcommands and keys.

Protocol v1 Requirements:

• load <key>: Reads no stdin. Exit 0 with {"found":true,"value":"<value>"} if present, or {"found":false} if missing.
• save <key>: Receives {"value":"<value>"} on stdin. Must exit 0 only after the value is durably committed.
• delete <key>: Reads no stdin. Exits 0 regardless of whether the key existed.
• Keys: The <key> will be either token-cache or selected-account.

Important Notes:

• The value must be a real executable path, not a shell command string.
• Wrappers should handle payloads of at least 256 KB.
• Any non-zero exit is treated as a storage error.
• The server does not fall back to other storage methods if this command is set.

$MS365_MCP_AUTH_CACHE_COMMAND load token-cache
$MS365_MCP_AUTH_CACHE_COMMAND save token-cache
$MS365_MCP_AUTH_CACHE_COMMAND delete token-cache
$MS365_MCP_AUTH_CACHE_COMMAND load selected-account
$MS365_MCP_AUTH_CACHE_COMMAND save selected-account
$MS365_MCP_AUTH_CACHE_COMMAND delete selected-account

After the initial deployment, you must perform these steps to make the server functional:

1. Update Entra ID Redirect URI: Retrieve your Container App FQDN (e.g., ms365mcp-app.<suffix>.<region>.azurecontainerapps.io) and add https://<fqdn>/oauth/callback to your app registration's Authentication -> Redirect URIs.
2. Redeploy with Public Base URL: Run the deployment script again with the -PublicBaseUrl flag so the server advertises the correct URL in OAuth metadata:

   ./deploy.ps1 ... -PublicBaseUrl 'https://<fqdn>'

3. Verify Installation (Smoke Test):
   • Check OAuth metadata: curl https://<fqdn>/.well-known/oauth-authorization-server (expect 200 OK).
   • Check MCP endpoint: curl -i https://<fqdn>/mcp (expect 401 Unauthorized).

# Example of redeploying to set the base URL
./deploy.ps1 -ResourceGroup 'rg-ms365mcp' -BaseName 'ms365mcp' -PublicBaseUrl 'https://ms365mcp-app.eastus.azurecontainerapps.io'