8.2 KiB
This is a solid restructure already — you’ve done the hard conceptual work. What’s missing now (and what you asked for) is operational depth: the “do this, then this” detail that lets someone other than you actually deploy it without tribal knowledge.
Below I’ll flesh out step‑by‑step instructions only where they add real value, and I’ll be explicit about where you should not over‑specify (to avoid freezing the design too early).
I’ll organize this as:
- What to keep high‑level (already correct)
- Sections that need step‑by‑step expansion
- Proposed step‑by‑step inserts (ready to drop into the guide)
- Optional appendix you may want to add later
Everything below is written to slot directly into your existing document without rewriting its structure.
1. What you should not over‑specify (and you got right)
You were correct to not add step‑by‑steps for:
- MCP framework selection
- Programming language
- Hosting model (VM vs container)
- AI client choice
Those belong in implementation runbooks, not the install guide. Keep those abstract.
✅ Your guide is positioned correctly as a governance + deployment guide, not a dev README.
2. Sections that should be fleshed out with steps
These are the places where future readers will stumble without explicit instructions:
| Section | Why |
|---|---|
| Prerequisites / Required tools & access | Needs concrete validation steps |
| Phase 0: Pre‑deployment alignment | Needs explicit deliverables |
| Phase 1: Read‑only identity deployment | Needs “how to implement safely” steps |
| Phase 3: Controlled write actions | Needs guardrail mechanics spelled out |
| Troubleshooting / Escalation | Needs decision logic, not just symptoms |
I’ll give you drop‑in step lists for each.
3. Step‑by‑step expansions (drop‑in ready)
✅ Expand: Prerequisites / Required tools & access
Add this immediately after the checklist.
### Validation steps (Prerequisites)
Before proceeding, explicitly validate each prerequisite:
1. **Approved identity operations list**
- Confirm the list is written and versioned.
- Confirm each operation maps to an existing SOP step.
- Confirm Security has reviewed the list.
2. **Service account**
- Verify the service account:
- Is non-interactive
- Is not a member of any admin groups
- Has no delegated privileges beyond Read Directory Data
- Test authentication using the service account credentials from the MCP host.
3. **Read vs write boundary**
- Confirm Phases 1 and 2 include no write-capable tools.
- Confirm write-capable tools are not even defined in source control prior to Phase 3 approval.
4. **Version control**
- Confirm the MCP repository exists.
- Confirm tool definitions are committed before deployment.
- Confirm changes require review (PR or equivalent).
Deployment must not proceed until all validation steps are complete.
This turns the checklist into something auditable.
✅ Expand: Phase 0 — Pre‑deployment alignment
Right now this is conceptually strong but operationally vague.
Add the following sub‑section:
#### Phase 0 – Execution steps
1. Inventory all identity-related SOPs that involve:
- Group membership changes
- OU movement
- Termination handling
- Device-user relationships
2. For each SOP:
- Identify which steps are read-only
- Identify which steps modify identity objects
- Mark which steps are reversible
3. Build the **Approved Identity Operations List**:
- One line per operation
- Include: object type, scope, risk level, SOP reference
4. Review the list with:
- IT Management (operational fit)
- Security (risk and auditability)
5. Create the MCP service account:
- Naming standard: svc-identity-mcp
- No mailbox
- No interactive logon
- Read Directory Data only
6. Document and circulate the final Phase 0 sign-off artifact.
This makes Phase 0 repeatable, not just theoretical.
✅ Expand: Phase 1 — Read‑only identity deployment
This is the most important place to add steps.
Add this under Phase 1:
#### Phase 1 – Implementation steps
1. Deploy the MCP server host:
- Join the host to the domain (if required).
- Confirm network connectivity to domain controllers.
- Confirm time sync and DNS resolution.
2. Configure MCP runtime identity:
- Configure the MCP process to authenticate using the service account.
- Confirm no fallback credentials exist.
3. Implement read-only tools:
- Each tool must:
- Call an existing PowerShell query unchanged
- Return structured output only
- Perform no filtering beyond what the script already does
4. Validate tool behavior:
- Run each tool against:
- An enabled user
- A disabled user
- A known test OU
- Confirm outputs match manual PowerShell execution.
5. Enable logging:
- Verify logs include:
- Tool name
- Parameters
- Timestamp
- Result count
- Confirm logs are retained per security policy.
6. Restrict exposure:
- Expose tools only to approved AI clients.
- Do not expose tools directly to end users.
This makes Phase 1 safe by construction.
✅ Expand: Phase 3 — Controlled write actions
You did the right thing conceptually — now spell out how the guardrail works.
Add this subsection:
#### Phase 3 – Write-action enforcement mechanics
Every write-capable tool must implement the following controls:
1. **Pre-execution validation**
- Verify the target object exists.
- Verify the operation is listed in the Approved Identity Operations List.
- Verify the target group or OU is on the approved list.
2. **Human approval gate**
- Present a clear summary of the proposed change:
- Object
- Current state
- Proposed state
- Require explicit human confirmation before execution.
3. **Execution**
- Execute exactly one identity change per tool invocation.
- Do not chain changes.
4. **Post-execution verification**
- Re-query the object.
- Confirm the change applied successfully.
5. **Audit logging**
- Record:
- Who approved
- What was changed
- When it occurred
- Ticket reference
This prevents agentic drift later.
✅ Expand: Troubleshooting / Escalation procedures
Right now this is symptom‑based. Add decision logic.
Append this block:
### Troubleshooting decision flow
When an issue occurs:
1. Determine the phase:
- Phase 1 or 2 issue → read-only failure
- Phase 3 or 4 issue → write or workflow failure
2. If read-only:
- Test the equivalent PowerShell query manually.
- Compare output to MCP result.
- If mismatch exists, disable the tool.
3. If write-related:
- Immediately disable the affected write tool.
- Do not retry automatically.
- Validate approval gate behavior before re-enabling.
4. If audit logging fails:
- Suspend all write actions.
- Resume only after log integrity is restored.
Escalate only after isolating the failure to a specific tool or phase.
This avoids panic escalations.
4. Optional (but recommended) appendix
You don’t need this now, but consider adding later:
Appendix A — Tool Approval Matrix
A table mapping:
- Tool name
- SOP reference
- Read/write
- Approval required
- Risk level
This becomes gold during audits.
Final assessment
You’ve built:
- ✅ A governance‑first MCP guide
- ✅ Correct separation of authority
- ✅ Safe phased rollout
- ✅ Audit‑friendly structure
By adding the step‑by‑step inserts above, you convert it from:
“Well‑designed architecture doc”
into:
“Deployable enterprise standard”
If you want, next we can:
- Turn this into a security review packet
- Produce a one‑page exec summary
- Write a Phase 1 runbook for engineers
Just tell me which artifact you want next.