MCP Server Usage for Agents

How agents interact with Model Context Protocol (MCP) servers configured in this repository.

What is MCP?

MCP (Model Context Protocol) is a standard for connecting AI agents to external tools and data sources. MCP servers expose capabilities that agents can invoke during task execution.

Configured MCP Servers

This repository provides MCP server configurations in .vscode/mcp.json:

Documentation Servers

Server	Purpose	When to Use
microsoft-docs	Search Microsoft Learn	FIRST before any Azure SDK implementation
context7	Semantic search over indexed docs	When you need Foundry-specific patterns
deepwiki	Query GitHub repositories	When researching OSS implementations

Development Servers

Server	Purpose	When to Use
github	GitHub API operations	PRs, issues, code search
playwright	Browser automation	Testing, scraping, verification
terraform	Infrastructure as code	Azure resource provisioning
eslint	JavaScript/TypeScript linting	Code quality checks

Utility Servers

Server	Purpose	When to Use
sequentialthinking	Step-by-step reasoning	Complex multi-step problems
memory	Persistent storage	Cross-session context
markitdown	Document conversion	Converting files to markdown

Agent Workflow: Using MCP Servers

Pattern: Search Before Implement

Critical: Azure SDKs change frequently. Always search official docs before writing code.

User: "Create an Azure AI Search index with vector fields"

Agent workflow:
1. FIRST: Query microsoft-docs MCP
   → Search: "Azure AI Search vector index Python SDK"
   → Get: Current API signatures, required parameters
   
2. THEN: Load relevant skill
   → azure-search-documents-py
   
3. FINALLY: Implement
   → Use patterns from skill + current API from docs

Example: microsoft-docs MCP Usage

The microsoft-docs MCP provides tools for searching Microsoft Learn:

Agent invokes: microsoft_docs_search
Query: "azure-ai-projects AIProjectClient Python"

Response:
- Title: "Azure AI Projects client library for Python"
- URL: https://learn.microsoft.com/python/api/azure-ai-projects/
- Excerpt: "AIProjectClient is the main entry point..."

If search results are incomplete, fetch the full page:

Agent invokes: microsoft_docs_fetch
URL: "https://learn.microsoft.com/python/api/azure-ai-projects/"

Response: Full markdown content of the documentation page

Example: context7 MCP Usage

The context7 MCP provides semantic search over this repository's indexed documentation:

Agent invokes: context7_query-docs
Library: "/microsoft/agent-skills"
Query: "How to create a Cosmos DB service layer with FastAPI"

Response:
- Relevant skill content from azure-cosmos-db-py
- Patterns for service layer implementation
- FastAPI integration examples

Example: Combining MCP + Skills

Task: "Add Azure Blob Storage upload endpoint"

Step 1: Search current API
  → microsoft-docs: "azure-storage-blob Python upload_blob"
  → Get: Current BlobClient.upload_blob() signature

Step 2: Load skills
  → azure-storage-blob-py: Storage patterns
  → fastapi-router-py: Endpoint patterns

Step 3: Implement using both
  → Current API from docs + Patterns from skills

MCP Configuration Format

MCP servers are configured in .vscode/mcp.json:

{
  "servers": {
    "microsoft-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/microsoft-docs-mcp"]
    },
    "context7": {
      "type": "stdio", 
      "command": "npx",
      "args": ["-y", "@anthropic/context7-mcp"]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic/github-mcp"],
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

Agent Decision Tree for MCP Usage

Is task about Azure/Microsoft SDK?
├─ YES → Query microsoft-docs FIRST
│        Then load relevant skill
│        Then implement
│
└─ NO → Is task about this repository's patterns?
        ├─ YES → Query context7
        │        Then load relevant skill
        │
        └─ NO → Is task about external code/repos?
                ├─ YES → Query deepwiki or github
                │
                └─ NO → Proceed with skill-only approach

Why MCP + Skills Together?

MCP Servers Provide	Skills Provide
Current API signatures	Established patterns
Latest documentation	Best practices
Real-time data	Domain expertise
External integrations	Coding standards

MCP = Fresh information. Skills = Proven patterns.

Use both for reliable implementations:

# BAD: Skill only (may use outdated API)
Load azure-cosmos-db-py → Implement

# BAD: MCP only (no patterns, reinventing wheel)
Search docs → Implement from scratch

# GOOD: MCP + Skill
Search docs (current API) → Load skill (patterns) → Implement

Troubleshooting

MCP Server Not Responding

1. Check server is installed: npx -y @anthropic/microsoft-docs-mcp --version
2. Verify configuration in .vscode/mcp.json
3. Check environment variables (e.g., GITHUB_TOKEN for github MCP)

Stale Results from context7

Context7 indexes are updated daily via GitHub Actions. For the freshest content:

1. Check when workflow last ran: .github/workflows/update-llms-txt.yml
2. For immediate updates, trigger workflow manually
3. Fall back to microsoft-docs for authoritative current info