microsoft/entrabot

microsoft/entrabot

Description: Give a device-local AI agent its own Microsoft Entra identity. Reference implementation for Microsoft Agent 365 and Entra Agent ID.

Language: Python

License: MIT

Stars: 1

Forks: 1

Open issues: 3

Created: 2026-05-26T20:07:04Z

Pushed: 2026-06-09T23:59:49Z

Default branch: main

Fork: no

Archived: no

README:

Entrabot: Identity Research for Microsoft 365 Agents

Entrabot is a Python MCP server that gives a device-local agent its own Entra Agent ID and an Agent User that has all the capabilities of a human user in a Microsoft tenant. It can have a Teams presence and be invited to meetings to chat with your colleagues 1:1, a mailbox it can monitor and respond to, create and edit Word documents, make PowerPoint presentations, and allows you to access your CLI. The agent signs in autonomously, sends Teams messages from its own account, and writes audit events against its own object ID. It runs on macOS, Linux, and Windows, and works with Claude Code, Copilot CLI, or any MCP-speaking client.

All you need to get started is:

• A Free Microsoft 365 Developer tenant (sign up at )
• A license that includes Teams and Outlook (E3 or E5 dev tenant licenses work)
• Python 3.12 installed locally

The scripts will take care of the rest: provisioning the Agent Identity Blueprint, Agent Identity, and Agent User in Entra; uploading a self-signed certificate; assigning the license; and configuring the local MCP server.

Microsoft Entra Agent ID and Microsoft Agent 365 — which enable these experiences — went GA on 2026-05-01. Entrabot is the reference implementation that pulls those primitives together on a real device, today.

---

What this is

A device-local MCP server that turns an LLM agent into a first-class principal in Microsoft Entra. Three things change when you do this:

• Attribution. Every action — Teams message sent, file read, email drafted — is signed by the agent, not by the human who launched it. Sign-in logs distinguish them. Audit trails are honest.
• Authorization. Conditional Access, ID Protection, and DLP apply to the agent's own object. You can restrict what the agent can do without restricting yourself.
• Autonomy. No device-code prompt, no OBO, no human in the loop on every token refresh. The agent authenticates with its own certificate-backed credentials and minds its own session.

It is for developers building agents on Microsoft 365 who want the security posture to match the architecture. The agent's smarts are up to you. entrabot gives it a secure seat at the table and the keys to the kingdom; what it does with that power is your call.

The body prompt (prompts/agent_system.md plus prompts/anatomy/*.md) is non-overridable and loads before any user turn. Security rules, channel discipline, and instruction-injection defense are baked in below the persona line. An agent that runs on entrabot cannot be jailbroken into impersonating its operator.

---

The stack

entrabot is the device-side glue for a set of platform primitives Microsoft shipped at GA.

• Entra Agent ID — the four-object hierarchy: Agent Identity Blueprint → BlueprintPrincipal → Agent Identity → Agent User. Confidential clients only; no public-client flows; tokens carry idtyp=user for the Agent User leaf. ([platform learning](docs/platform-learnings/agent-id-blueprints-and-users.md))
• Microsoft Agent 365 — the control plane: admin-center inventory, OTel observability, Work IQ MCP servers (Mail, Calendar, Teams, SharePoint, OneDrive, Word, User, Copilot, Dataverse), AI-teammate lifecycle. GA 2026-05-01. ([platform learning](docs/platform-learnings/microsoft-agent-365.md))
• Conditional Access for agents — GA. Apply CA policies to Agent Identity sign-ins the same way you apply them to users.
• ID Protection for agents — GA. Risk scoring and remediation against the agent's own object.
• FastMCP — the Python MCP server framework. entrabot registers every Teams, Outlook, Files, Word, audit, and identity tool through it.
• Three-hop certificate chain — Blueprint token (cert JWT) → Agent Identity token (federated identity credential) → Agent User token (user_fic grant). No client secret in flight. Private key in macOS Keychain, Windows TPM via CNG, or Linux Secret Service.

entrabot connects these. The Blueprint is provisioned via Graph. The Agent User is licensed and visible in Teams. The MCP server runs locally, mints tokens against Entra without a human, and exposes the resulting capability surface to the agent.

---

Architecture

flowchart LR
subgraph Device["Local device — Mac / Windows / Linux"]
Client["MCP client
(Claude Code, Copilot CLI)"]
Server["entrabot MCP server
(FastMCP)"]
Body["Body prompt
(non-overridable)"]
Keys[("OS keystore
Keychain / TPM / Keyring")]
end

subgraph Entra["Microsoft Entra ID"]
AgentID["Blueprint →
Agent Identity →
Agent User"]
end

subgraph M365["Microsoft 365 / Azure"]
Graph["Graph API
(Teams / Outlook / Files)"]
A365["Agent 365 Work IQ
(Word, Mail, Copilot)"]
Blob[("Azure Blob
(optional)")]
end

Client |stdio| Server
Server --> Body
Server --> Keys
Server -->|3-hop cert chain| AgentID
AgentID -->|idtyp=user| Graph
AgentID -->|delegated| A365
AgentID -->|user_fic| Blob

The agent talks to the MCP server over stdio. The server reads the Blueprint's private key from the OS keystore, walks the three-hop chain to produce a delegated user token, and uses that token for every Graph and Work IQ call.

Inbound delivery differs by host. On Claude Code, the server's background poll pushes every inbound Teams message and email directly into the LLM as a notifications/claude/channel system reminder — the agent sees a DM the moment it lands, with no tool call and no human prompt required. The conversation in Teams becomes the conversation with the agent. On Copilot CLI, Codex, Cursor, and any MCP host that doesn't implement the channel-push extension, the same background poll runs server-side, but messages accumulate in the interaction log instead of streaming in. The agent reads them on demand via read_teams_messages, send_teams_message auto-blocks for the sponsor's reply when push is unavailable, and scripts/catch_up.py prints recent activity from the CLI. Channel push is the better UX; the polling fallback is a working second-class path for hosts that haven't shipped the extension yet.

Operational state (interaction log, daily…