BrainBlitz is a quiz-game Declarative Agent that runs inside Microsoft 365 Copilot. It connects to a remote MCP (Model Context Protocol) server to let users create quizzes, add questions, host live games, and play — all through natural-language prompts in the Copilot chat.
Built with the Microsoft 365 Agents Toolkit (ATK) in VS Code.
| Capability | Description |
|---|---|
| Create Quiz | Create a new quiz with a title and visual theme (classic, ocean, volcano, forest, galaxy). |
| Add Questions | Add multiple-choice questions (2-4 options) to any quiz in a single batch call. |
| Show Quizzes | Browse all quizzes in an interactive Copilot widget with IDs, titles, themes, and question counts. |
| Get Quiz | Fetch full quiz details — questions and answer options — as structured data. |
| Search | Search quizzes and questions by keyword. |
| Play Game | Join a live BrainBlitz game by entering a game PIN and player name directly in Copilot. |
| Delete Quiz | Permanently remove a quiz and all its questions. |
| Requirement | Details |
|---|---|
| Node.js | v18, 20, or 22 — download |
| VS Code | Latest stable release |
| Agents Toolkit | Microsoft 365 Agents Toolkit extension v5.0.0+ |
| M365 Dev Account | Set up a dev account |
| Copilot License | Microsoft 365 Copilot license |
git clone https://github.com/MarcusCastroMSFT/BrainBlitzDA.git
cd BrainBlitzDAcode .Click the Microsoft 365 Agents Toolkit icon in the Activity Bar, then under Accounts sign in with your M365 developer account.
Open .vscode/mcp.json and click the Start button. When prompted, enter the authentication credentials for the BrainBlitz MCP server.
In the Agents Toolkit sidebar, click Provision. ATK will:
- Register the Teams app in the Developer Portal.
- Package the app manifest, declarative agent config, and AI plugin.
- Extend the app to Microsoft 365 and Outlook.
Click Start Debugging (F5). The agent will launch in Copilot within Edge or Chrome. Select BrainBlitz from the Copilot agent list and start chatting.
Once BrainBlitz is running in Copilot, try these:
| Prompt | What happens |
|---|---|
| "Show my quizzes" | Opens the interactive quiz-browser widget. |
| "Create a quiz called Azure Fundamentals with a galaxy theme" | Creates a new quiz and returns its ID. |
| "Add 5 questions about Azure regions to quiz abc12345" | Generates and adds multiple-choice questions in one call. |
| "Get quiz abc12345" | Returns all questions and answers for that quiz. |
| "Search for networking" | Finds quizzes and questions matching the keyword. |
| "Play a game — my PIN is 721703 and my name is Marcus" | Joins a live game inside the Copilot widget. |
| "Delete quiz abc12345" | Permanently removes the quiz. |
BrainBlitz/
├── .vscode/
│ ├── extensions.json # Recommended VS Code extensions
│ ├── launch.json # Debug configurations
│ ├── mcp.json # MCP server connection config
│ └── settings.json # Workspace settings
├── appPackage/
│ ├── ai-plugin.json # Function definitions, runtime spec & auth for Copilot
│ ├── declarativeAgent.json # Agent configuration & conversation starters
│ ├── instruction.txt # System instructions for the agent
│ ├── manifest.json # Teams / Outlook app manifest
│ ├── build/ # Auto-generated build artifacts (git-ignored)
│ └── EmbeddedKnowledge/ # Static assets (icons, etc.)
├── env/
│ ├── .env.dev # Environment variables (MCP URL, app IDs)
│ └── .env.dev.user # User-specific secrets (git-ignored)
├── m365agents.yml # ATK lifecycle definition (provision, publish)
├── .gitignore
└── README.md
| File | Purpose |
|---|---|
appPackage/ai-plugin.json |
Declares every MCP tool (function name, description, input schema, annotations) and the remote MCP server endpoint. This is what Copilot uses to discover and invoke BrainBlitz actions. |
appPackage/declarativeAgent.json |
Defines the agent's name, description, system instructions (via instruction.txt), conversation starters, and links to the AI plugin. |
appPackage/manifest.json |
Standard Teams app manifest — registers the Copilot agent, sets permissions, and declares valid domains. |
m365agents.yml |
ATK lifecycle file — defines the provision and publish stages (create app, zip package, update, extend to M365). |
.vscode/mcp.json |
Configures the local MCP server connection used during development and tool fetching. |
BrainBlitz connects to a remote MCP server hosted on Azure Container Apps:
- Endpoint: Defined in
appPackage/ai-plugin.jsonunderruntimes[0].spec.url - Protocol: Remote MCP over HTTPS (Streamable HTTP)
- Auth: OAuth 2.0 — credentials are stored in
env/.env.dev.user(git-ignored)
| Tool | Read-Only | Destructive | Description |
|---|---|---|---|
show_quizzes |
Yes | — | List all quizzes in an interactive widget |
get_quiz |
Yes | — | Fetch full quiz details by ID |
search |
Yes | — | Search quizzes/questions by keyword |
fetch |
Yes | — | Fetch any item by prefixed ID (quiz-* / question-*) |
play_game |
Yes | — | Join a live game by PIN and player name |
create_quiz |
— | — | Create a new quiz |
add_questions |
— | — | Add questions to an existing quiz |
delete_quiz |
— | Yes | Permanently delete a quiz |
Edit appPackage/instruction.txt to modify the system prompt that guides the agent's behavior.
Edit the conversation_starters array in appPackage/declarativeAgent.json:
"conversation_starters": [
{ "title": "Show my quizzes", "text": "Show my quizzes" },
{ "title": "Create a quiz", "text": "Create a quiz about world history" },
{ "title": "Play a game", "text": "I want to join a game" }
]If the MCP server adds new tools, re-fetch them:
- Open
.vscode/mcp.jsonand click ATK: Fetch Action from MCP. - Select the tools you want to expose.
- ATK updates
appPackage/ai-plugin.jsonautomatically.
Tip: For full tool definitions including
_metaandannotations, use MCP Inspector and paste the schemas intoai-plugin.json.
| Issue | Fix |
|---|---|
| Agent doesn't appear in Copilot | Re-run Provision and ensure the app is extended to M365. Check that your account has a Copilot license. |
| MCP tools fail at runtime | Verify the MCP server is running and the URL in ai-plugin.json is reachable. Check credentials in env/.env.dev.user. |
| "Tool not found" errors | Run ATK: Fetch Action from MCP again to sync the tool list. |
| Auth errors on provision | Ensure env/.env.dev.user has valid OAuth client ID/secret. ATK will prompt if values are missing. |
- Build Declarative Agents — Official Microsoft docs
- Model Context Protocol (MCP) — Protocol specification
- Agents Toolkit Guide — GitHub wiki
This project is provided as a sample. See your organization's policies for usage and distribution.