Add enhanced best practices to MCP documentation

[Copilot]

Enhances docs/2-mcp.md with actionable security, workflow, and review guidance for MCP setup, Copilot agent mode usage, and backlog management.

Security Best Practices

• MCP server trust verification: Source code review, publisher verification, permission audit, OAuth preference
• PAT security: Minimal scope, rotation schedule, environment variables, secure input properties

Copilot Agent Mode Guidance

• Usage criteria: When to use agent mode vs. standard Copilot (multi-file operations, external tools, complex workflows)
• Model selection: Specific use cases for Claude 3.5 Sonnet (complex reasoning) vs. GPT-4o (balanced performance)
• Tool verification: Count indicators, troubleshooting steps (restart server, reload window)

Backlog Management

• Issue creation: Prompt specificity, context inclusion, template usage, batch operations
• AI review checkpoints: Accuracy, completeness, clarity, security, formatting
• Permission management: Session-scoped vs. permanent permissions, revocation timing
• Post-creation workflow: Labels, assignments, milestones, dependency linking

MCP Configuration

• Remote vs. local server guidance, version control practices, multi-server configuration

Example enhancement - before:

> [!IMPORTANT]
> Remember, AI can make mistakes, so make sure to review the issues before confirming.

After:

> [!IMPORTANT]
> **AI Review Best Practice**: AI can make mistakes, so always review generated content before confirming. Check for:
> - **Accuracy**: Does the content match your intent?
> - **Completeness**: Are all required fields populated?
> - **Clarity**: Is the description clear and actionable?
> - **Security**: Does the content avoid exposing sensitive information?
> - **Formatting**: Is the markdown properly formatted?

~80 lines of enhanced guidance added across 7 sections. All cross-references and document structure preserved.

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repos/chikamsoachumsft/agents_tutorial1/pulls
  • Triggering command: curl -X POST -H Accept: application/vnd.github+json -H Authorization: Bearer REDACTED -d { "title": "Enhanced MCP Documentation Best Practices", "body": "This PR updates docs/2-mcp.md with enhanced best practices for MCP setup, Copilot agent mode, and backlog management.", "head": "copilot/update-docs-mcp-best-practices", "base": "improve-doc-best-practices" } (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

Update docs/2-mcp.md in the improve-doc-best-practices branch with enhanced best practices for MCP setup, Copilot agent mode, and backlog management. This improves clarity and developer experience by adding actionable security, workflow, and review tips throughout the documentation. Open a pull request merging improve-doc-best-practices into main.

This pull request was created as a result of the following prompt from Copilot chat.

Update docs/2-mcp.md in the improve-doc-best-practices branch with enhanced best practices for MCP setup, Copilot agent mode, and backlog management. This improves clarity and developer experience by adding actionable security, workflow, and review tips throughout the documentation. Open a pull request merging improve-doc-best-practices into main.

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Copilot wasn't able to review any files in this pull request.

[Copilot]

Pull Request Overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

docs/2-mcp.md:1

• The model comparison information may become outdated quickly. Consider adding a note that these are general characteristics at the time of writing and that users should refer to current model documentation for up-to-date capabilities and availability.

# Exercise 2 - Setting up the backlog with Copilot agent mode and GitHub's MCP Server

[Copilot]

The guidance to 'comment your MCP configurations' may be misleading since JSON format doesn't support comments natively. Consider clarifying this to suggest using adjacent documentation (like a README) or referring to JSON5/JSONC if supported by VS Code's mcp.json parser.

Suggested change

	> - **Documentation**: Comment your MCP configurations to explain which servers are used and why
	> - **Documentation**: Standard JSON does not support comments. Document your MCP configurations in an adjacent README file, or use JSONC/JSON5 syntax if your environment (such as VS Code's parser) supports it.