Microsoft Learn (MCP) Integration Guide

Technology: microsoft-learn · Category: tooling · Last reviewed: 2026-08-23

Source: https://tech-stack.codeamanilabs.org/guide/microsoft-learn

Insight:

The Microsoft Learn MCP Server is a free, remote, unauthenticated connector (https://learn.microsoft.com/api/mcp, generally available since Nov 2025) that grounds Claude Code in live, first-party Azure / .NET / Entra / Microsoft 365 docs — the same "no trained-data guessing" rule as Context7, but Microsoft-specific. In Claude Code the official path is now the microsoft-docs plugin (/plugin install microsoft-docs@microsoft-docs-marketplace), which bundles the MCP server plus three helper skills; then research any Microsoft product with microsoft_docs_search → microsoft_docs_fetch → microsoft_code_sample_search.

███╗   ███╗██╗ ██████╗██████╗  ██████╗ ███████╗ ██████╗ ███████╗████████╗
████╗ ████║██║██╔════╝██╔══██╗██╔═══██╗██╔════╝██╔═══██╗██╔════╝╚══██╔══╝
██╔████╔██║██║██║     ██████╔╝██║   ██║███████╗██║   ██║█████╗     ██║
██║╚██╔╝██║██║██║     ██╔══██╗██║   ██║╚════██║██║   ██║██╔══╝     ██║
██║ ╚═╝ ██║██║╚██████╗██║  ██║╚██████╔╝███████║╚██████╔╝██║        ██║
╚═╝     ╚═╝╚═╝ ╚═════╝╚═╝  ╚═╝ ╚═════╝ ╚══════╝ ╚═════╝ ╚═╝        ╚═╝

██╗     ███████╗ █████╗ ██████╗ ███╗   ██╗
██║     ██╔════╝██╔══██╗██╔══██╗████╗  ██║
██║     █████╗  ███████║██████╔╝██╔██╗ ██║
██║     ██╔══╝  ██╔══██║██╔══██╗██║╚██╗██║
███████╗███████╗██║  ██║██║  ██║██║ ╚████║
╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝

Microsoft Learn (MCP) Integration Guide

Focus: Pairing the Microsoft Learn MCP connector into Claude Code so the agent grounds every Microsoft answer — Azure, .NET, Entra ID, Microsoft 365, Power Platform — in current, first-party documentation instead of stale training data, and using it to comprehensively research and prep Microsoft products and services.

Overview

The Microsoft Learn MCP Server is a cloud-hosted Model Context Protocol server that lets AI agents pull trusted, up-to-date content directly from Microsoft's official documentation. It is the Microsoft equivalent of this stack's Context7 rule: instead of Claude guessing at an Azure SDK signature or an az CLI flag, the connector fetches the actual current docs and injects them into the conversation.

Core value proposition: ground Microsoft answers in real Microsoft Learn content. Search returns up to 10 ranked chunks (≤500 tokens each); fetch returns a full doc page as markdown; code-sample search returns official, language-filtered snippets.

It is free (rate-limited), remote (no install), uses streamable HTTP, and is unauthenticated — so there is no API key to manage and nothing for this repo's freshness checker to version-track (hence packages: [], like the Context7 and Visual Studio guides). The server has been generally available since 2025-11-07 (preview disclaimers removed); check the release notes for what shipped when.

Not a traditional API. The endpoint is meant to be consumed through an MCP client / agent framework, not called directly as REST. Tool names, request, and response shapes can change; always let the client list tools at init.

Official Documentation

MCP Server Setup

The server is remote — there is nothing to npm install. You only register the endpoint.

Endpoint:

https://learn.microsoft.com/api/mcp

Add to Claude Code — official plugin (recommended)

Since 2026-03-23 Microsoft ships the connector as a first-party Claude Code / Copilot CLI plugin. This is now the recommended path — it bundles the MCP server plus three agent skills that teach Claude to use the tools well (microsoft-docs for concepts/tutorials, microsoft-code-reference for API lookups & code samples, microsoft-skill-creator for generating custom Microsoft skills):

# Run in Claude Code, then restart
/plugin marketplace add microsoftdocs/mcp
/plugin install microsoft-docs@microsoft-docs-marketplace

When installed this way the tools are namespaced under the plugin (e.g. microsoft_docs_search served by the microsoft-learn MCP inside the microsoft-docs plugin).

Add to Claude Code — manual HTTP (alternative)

If you'd rather register just the raw endpoint (no bundled skills):

# Remote HTTP MCP server — no package, no key
claude mcp add --transport http microsoft-learn https://learn.microsoft.com/api/mcp

Verify it registered and the tools surfaced:

claude mcp list

.mcp.json Configuration (project-scoped)

{
  "mcpServers": {
    "microsoft-learn": {
      "type": "http",
      "url": "https://learn.microsoft.com/api/mcp"
    }
  }
}

The Microsoft docs publish the canonical client snippet (works in VS Code, Cursor, Foundry, and most MCP clients) — note the current server key is microsoft.docs.mcp:

{
  "microsoft.docs.mcp": {
    "type": "http",
    "url": "https://learn.microsoft.com/api/mcp"
  }
}

Token-budget control: append ?maxTokenBudget=<n> to the endpoint URL (e.g. https://learn.microsoft.com/api/mcp?maxTokenBudget=2000) to cap the tokens returned in search responses — handy in agentic loops where each call eats context. It truncates search results only; microsoft_docs_fetch always returns the full page.

Available MCP Tools

How It Works in Practice

Here is the core grounding loop at a glance — search for breadth, fetch for depth, code-sample for the exact pattern, all before writing anything non-trivial.

flowchart TD
    A["Microsoft question<br/>Azure - .NET - Entra - M365"] --> B["microsoft_docs_search<br/>breadth"]
    B --> C["Up to 10 ranked chunks<br/>title plus URL"]
    C --> D["microsoft_docs_fetch<br/>depth"]
    D --> E["Full doc page as markdown"]
    C --> F["microsoft_code_sample_search<br/>practical examples"]
    F --> G["Official language-filtered snippets"]
    E --> H["Grounded answer or code"]
    G --> H

The recommended flow mirrors the Context7 two-step, with a third pass for code:

1. Search for breadth

Tool: microsoft_docs_search
Input: { "query": "deploy ASP.NET web app to Azure App Service az webapp up" }
Output: [up to 10 ranked doc chunks with titles + canonical learn.microsoft.com URLs]

2. Fetch for depth

Tool: microsoft_docs_fetch
Input: { "url": "https://learn.microsoft.com/azure/app-service/quickstart-dotnetcore" }
Output: [the full quickstart as markdown — every step, prerequisite, and CLI flag]

3. Code-sample for the exact pattern

Tool: microsoft_code_sample_search
Input: { "query": "Azure OpenAI chat completions client", "language": "python" }
Output: [official, current snippets you can adapt verbatim]

Best practice (from Microsoft): Search gives breadth. Code Sample Search gives practical examples. Fetch gives depth. Lead with search, then fetch high-value pages before writing anything non-trivial.

Natural-language usage

Once paired, you reference Microsoft docs conversationally and Claude calls the tools for you:

"Using current Microsoft Learn docs, show me how to deploy a .NET 10 app to Azure App Service with az webapp up."

"Fetch the full Azure Functions triggers and bindings page and summarise the HTTP trigger options."

"Find the official C# code sample for chatting with Azure OpenAI on your own data."

Using It Within Limits

The endpoint is free and unauthenticated, but it is a shared public service with rate limits in place to ensure fair usage — Microsoft confirms this in the FAQ and asks for "responsible use" to keep it available for everyone. The repo describes it as "completely free" with "high search capacity tailored for heavy coding sessions" — generous, but not unmetered.

No published numbers. As of this review Microsoft does not publish the specific request/token thresholds. Don't assume a number — assume it's tuned for normal interactive use and budget your calls accordingly. If you hit throttling, back off and raise it in the MicrosoftDocs/mcp repo.

The search → fetch → code flow already is the budgeting pattern — spend calls in that order and most sessions stay well under any limit:

• Search broad first. One well-phrased microsoft_docs_search returns up to 10 ranked chunks — usually enough to pick the right page without a second search. Refine the query rather than firing several near-identical ones.
• Fetch only the 1–2 best URLs. microsoft_docs_fetch is the expensive, high-value call. Fetch the single most authoritative result; pull a second only if the first is genuinely incomplete. Don't fetch every chunk search returned.
• Code-sample once, with a language. A filtered microsoft_code_sample_search lands the right snippet in one shot; an unfiltered one wastes a call on the wrong language.
• Batch related questions. Group everything you need on a topic into one search → fetch pass instead of drip-feeding follow-ups that re-search the same area.

flowchart TD
    A["Microsoft question"] --> B["microsoft_docs_search<br/>one broad query"]
    B --> C{"Right page in<br/>the 10 chunks?"}
    C -->|"no"| D["Refine query<br/>not re-fire"]
    D --> B
    C -->|"yes"| E["microsoft_docs_fetch<br/>1 or 2 best URLs only"]
    E --> F["microsoft_code_sample_search<br/>once · with language"]
    F --> G["Grounded answer<br/>calls minimised"]

Gotcha: the MCP has no topic result-filtering parameter (per the FAQ) — you can't narrow which chunks come back server-side, only scope it inside your question text. So a vague query wastes a whole call returning broad chunks; spend an extra second sharpening the query instead of burning a retry. (There is a ?maxTokenBudget=<n> URL parameter that caps the size of search responses — see Setup — but it truncates, it doesn't filter by relevance.)

Using It to Research & Prep Microsoft Products

This connector is the research engine for evaluating or onboarding any Microsoft service. Below is the verified landscape (sourced live via the connector) of the services most relevant to codeAmani's stack decisions.

AI & agents

Compute & hosting

Identity

Research recipe: to prep any of the above, run microsoft_docs_search for the service + "overview", microsoft_docs_fetch the quickstart page, then microsoft_code_sample_search with the target language. You get a grounded, citeable brief without leaving Claude Code.

Two other ways to reach the same knowledge service

The MCP connector isn't the only front door to Learn's Ask Learn knowledge service:

• @microsoft/learn-cli (released 2026-03-10, latest = 0.1.0 on npm) gives the same three tools — search docs, fetch pages, find code samples — from the terminal with no MCP client. Handy for one-off lookups in scripts/CI where you don't want a full agent session.
• OpenAI-compatible endpoint (released 2025-12-10) exposes the search + fetch tools in the OpenAI "deep research" tool shape, for agents built against that surface. In Claude Code you'll almost always use the MCP tools directly instead.

Integration Patterns

Put the rule in CLAUDE.md

Mirror the existing Documentation Policy so Microsoft questions are always grounded:

## Microsoft Documentation Policy

For any Azure, .NET, Entra ID, Microsoft 365, or Power Platform work:
1. Use `microsoft_docs_search` to find the relevant official page(s)
2. Use `microsoft_docs_fetch` on the best match for full, current steps
3. Use `microsoft_code_sample_search` (with a `language`) before writing code
4. Never use remembered Azure API patterns if they differ from fetched docs

Slash command: research a Microsoft product

.claude/commands/ms-research.md:

Research the Microsoft product/service: $ARGUMENTS.

1. `microsoft_docs_search` for "$ARGUMENTS overview" and "$ARGUMENTS quickstart"
2. `microsoft_docs_fetch` the most authoritative result
3. `microsoft_code_sample_search` for a starter snippet in our stack language
4. Summarise: what it is, when to use it, pricing/tier notes, and the canonical
   docs URLs. Flag any codeAmani / M-Pesa / African-market considerations.

Usage: /project:ms-research Azure Container Apps

Pair-with-Context7 routing

Both connectors enforce "no trained-data guessing" — route by source of truth. This quick decision keeps every question pointed at the right grounded source.

flowchart TD
    Q1{"Question about Microsoft<br/>Azure - .NET - Entra - M365?"}
    Q1 -->|"yes"| A["Microsoft Learn MCP"]
    Q1 -->|"no"| Q2{"npm or PyPI library<br/>or framework?"}
    Q2 -->|"yes"| B["Context7"]
    Q2 -->|"no"| C["Use the connector<br/>matching the source of truth"]

Route by source of truth:

codeAmani Notes

• Security / secrets: the Learn connector itself needs no key (unauthenticated, read-only docs). But anything you build from its research — Azure OpenAI, Storage, Entra apps — keeps secrets server-side only (.env.local, Vercel/Key Vault env vars), never in client code. Prefer keyless auth (Entra / Managed Identity) over API keys where Azure supports it.
• AI routing: Azure OpenAI becomes a third provider behind the existing policy — Anthropic Claude stays primary for reasoning/codegen; reach for Azure OpenAI only when a client contractually requires models inside their Azure tenant.
• When to bring in Azure at all: the default stack (Vercel + Cloudflare + Supabase/Neon + Clerk) covers most consumer/SME work. Azure earns its place for enterprise East-African clients with Microsoft-365 estates, data-residency mandates, or .NET backends — use this connector to scope the migration before committing.
• M-Pesa / mobile-first: Azure is heavier than the edge-first default; if you host an M-Pesa callback on Azure Functions, keep the same idempotency rules (store CheckoutRequestID on STK Push, dedupe on callback) and ensure the callback URL is HTTPS.
• Freshness: remote MCP with no package version → the checker can't track it; last_reviewed is the signal. Re-verify endpoint + tool names against the developer reference periodically, and skim the release notes for new tools/surfaces — the tool list is deliberately dynamic. (The @microsoft/learn-cli package is version-tracked on npm if you ever need a pinned surface.)

Troubleshooting

Best practice: pair this connector and add the Microsoft Documentation Policy to CLAUDE.md. The connector makes current docs available; the policy makes Claude actually use them before writing Azure/.NET code.

The file C:\Users\info.claude\tech-stack\microsoft-learn\CLAUDE_CODE_INTEGRATION.md has been written.

Official docs:

• https://learn.microsoft.com/training/support/mcp
• https://learn.microsoft.com/training/support/mcp-developer-reference
• https://learn.microsoft.com/training/support/mcp-best-practices
• https://learn.microsoft.com/training/support/mcp-get-started
• https://learn.microsoft.com/training/support/mcp-release-notes
• https://github.com/MicrosoftDocs/mcp