[amargiovanni]

Summary

The design for an optional MCP server, with no code. It covers the proposal, the phase 1 spec, the phase 2 spec, the roadmap and ADRs 0001–0005. It is meant to be read before #167, the phase 1 implementation stacked on top of it, so the direction is agreed on a few text files rather than on a 5,000-line diff.

What we ask the maintainers: is this the direction you want for Frontdoor? Comments on the principles, the phases and the open points are the most useful input at this stage.

The goal

Frontdoor administration by conversation, with a human always applying the change in Frontdoor.

An admin asks their AI assistant:

"Remove Figma from the Interns group and give Payroll to HR Milan."

Frontdoor does not apply it. It prepares the change and the assistant answers with a link. The admin opens Frontdoor, sees the exact effect with real names (who gains and who loses access to what) and clicks Apply.

The assistant proposes, Frontdoor decides, and the human confirms with their own Entra session. A prompt injection can at worst produce a proposal nobody applies (ADR 0005).

Phase	What users get	Where
1. Read and own preferences	"Which tools do I have for accounting?", "add Jira to my favourites", read-only admin answers (counts, never identities)	Spec 02-phase1-spec.md, code in #167
2. Admin write proposals	The flow above. It starts with which groups can open which apps, then app creation and edits, then Entra import	Spec 04-phase2-spec.md for the first step; built after phase 1 holds in production
3. Log answers for owners	"Which apps has nobody opened in 90 days?" (aggregates only)	Roadmap 03-roadmap.md; DPIA screening first

Related issue

Part of #171.

Type of change

• Bug fix
• New feature
• Refactor / internal change (no user-visible behavior change)
• Documentation
• Other:

What changed

• docs/design/mcp/01-proposal.md: the proposal, covering the principles, the outbound filter, writes as proposals, owner controls, the non-goals and the open questions.
• docs/design/mcp/02-phase1-spec.md: the phase 1 specification, with the authorization server rules, the mediation layer, the data model, GDPR and the threat model.
• docs/design/mcp/03-roadmap.md: what phase 1 delivers for phase 2, the plan for phases 2 and 3, and the open question on the shared admin API key of the bulk endpoints (review round 1).
• docs/design/mcp/04-phase2-spec.md and mockups/: the first step of phase 2, covering the propose_access_change tool, pending changes, the review page, apply with an effect digest, the audit and the threat model.
• docs/design/mcp/research/: the codebase survey and the MCP spec and SDK research behind the decisions.
• docs/adr/: the ADR process (0001), SDK v2 (0002), Frontdoor as a minimal OAuth authorization server (0003), client registration via metadata documents and pre-registration without DCR (0004), and writes only as confirmed proposals (0005), all Accepted by the author. ADR 0006, which splits the scope into frontdoor.read and frontdoor.preferences chosen at consent, is Proposed (review round 1). accepted.ledger freezes the Context and Decision of accepted ADRs, and check_adr_immutability.py verifies it. Wiring that check into CI can be a small follow-up PR.

ADRs 0001–0005 say "Accepted" for decisions whose code is still in review in #167 or not written yet (0005). That is normal for ADRs: they record the decision, not the merge. If the maintainers disagree with one, it is superseded, not edited.

Review round 1 (lombax85, 2026-11-10)

• Future of the bulk endpoints: recorded as an open question in 03-roadmap.md, not decided and nothing removed; the "Never via MCP" line in the phase 2 spec points to it.
• From the review of feat(mcp): AI assistants via MCP, phase 1 of 3 (foundation) #167: ADR 0006 (two scopes) and the phase 1 spec rules for scopes (§4 rule 15) and paged list results (§7).

Breaking changes

None. Documentation only.

Checklist

• I have read CONTRIBUTING.md.
• All commits are signed off (DCO).
• Lint and tests pass locally: not affected (no code).
• I updated CHANGELOG.md under [Unreleased]: not needed for design documents; feat(mcp): AI assistants via MCP, phase 1 of 3 (foundation) #167 carries the feature entry.
• I updated relevant documentation.
• No PII (emails, names, tokens) in new log statements (none).
• New SQL queries are parameterized (none).
• New HTML rendered from user input goes through DOMPurify (none; the mockup is a static file, not served).

Merge order

Merge this first. #167 contains these commits as its base: until this merges, its diff also shows them. Once this is in, its diff shrinks to the implementation. GitHub cannot stack a PR from a fork on another fork branch, so #167 keeps targeting main.

🤖 Generated with Claude Code

[lombax85]

Future of the API-key bulk endpoints

As part of the MCP roadmap, I would suggest discussing the eventual deprecation of the bulk endpoints authenticated with the shared ADMIN_API_KEY.

To locate the current implementation:

• In server/routes/apps.js, search for requireBulkApiKey: it checks the X-API-Key header against ADMIN_API_KEY.
• In the same file, router.get('/bulk', ...) implements GET /api/apps/bulk: it exports the catalogue, including inactive apps and metadata such as target_url and SSO configuration.
• router.post('/bulk', ...) implements POST /api/apps/bulk: it creates or updates apps by slug, merges tags and can assign groups to newly created apps.
• The key configuration appears in .env.example.node, .env.example.docker and docker-compose.yml. Changes are recorded in the audit log under the actor api-key.

The idea would be to migrate these use cases towards more granular, revocable access through MCP, rather than indefinitely maintaining an administrative path based on a shared key.

However, the current proposal does not yet provide an equivalent replacement. Phase 1 has no catalogue-write tools, MCP results omit some fields included in the export, and docs/design/mcp/04-phase2-spec.md explicitly excludes the bulk endpoints under “Never via MCP”. Also, a change requiring human confirmation does not directly replace unattended server-to-server synchronisation.

Could we add an explicit migration decision to the roadmap? It would help to clarify which use cases MCP should support, how unattended automation should work, and which data should be available.

If we agree on that direction, I would suggest updating the proposal and specifications, delivering the replacement workflows first, and providing a migration guide. Removal of the routes, guard and ADMIN_API_KEY configuration could then follow in a documented breaking release, rather than removing them in #167.

[amargiovanni]

Re: Future of the API-key bulk endpoints

Agreed on the direction, and agreed that nothing should be removed in #167.

One refinement: I don't think MCP can be the whole replacement. MCP fits the interactive catalogue work an admin does. Phase 2 applies writes only after a person confirms on a Frontdoor page (ADR 0005), so it cannot serve unattended server-to-server sync, as you note. That case would need a credential of its own, such as per-integration, revocable, scoped tokens on the regular API.

I recorded this as an open question rather than a decision (e775013). 03-roadmap.md now has a section listing what the endpoints do today and the gaps you listed. It also sets out the order you suggested: decision, then the replacement workflows, then a migration guide, then removal of the routes, the guard and ADMIN_API_KEY in a documented breaking release. The "Never via MCP" line in the phase 2 spec now points to it, and the CHANGELOG roadmap has an entry. Once the ADR practice from this PR is adopted, it can become a proper decision record.