[MS] How we built the Microsoft Learn MCP Server - devamazonaws.blogspot.com

When we launched the Microsoft Learn Model Context Protocol (MCP) Server in June 2025, our goal was simple: make it effortless for AI agents to use trusted, up-to-date Microsoft Learn documentation. GitHub Copilot and other agents are increasingly common, and they need to be able to ground responses just like humans with browsers do. Learn MCP Server is a remote server that exposes agent-friendly tools over Streamable HTTP Transport, backed by the same Learn knowledge service described in How we built “Ask Learn”.

Why MCP and why Learn MCP Server?

Modern AI agents can discover and use tools dynamically through Model Context Protocol, a standard that lets agents negotiate capabilities at runtime, stream results, and adapt as tools evolve. Instead of manually searching, scraping pages, or maintaining embeddings, clients simply connect to Learn MCP Server, request the list of tools available and invoke tools as the agent decides. VS Code GitHub Copilot and other MCP Clients can deliver accurate guidance for Microsoft technologies, while users benefit from answers backed by official Learn content.

The server presents three tools:

  • microsoft_docs_search: returns titles, content sections, and URLs to the source article.
  • microsoft_docs_fetch: fetches the full-page article content for additional context.
  • microsoft_code_sample_search: optimized for finding code snippets and examples within Learn documentation, enabling agents to retrieve language-specific samples quickly for coding tasks.

Why a server, not another API?

Traditional APIs require every client to develop integrations, including reading documentation, managing authentication, formatting requests, handling errors, and maintaining compatibility as things change. That model doesn’t scale in an ecosystem where dozens of AI agents—each with different capabilities—need to reliably access the same grounding data. MCP takes a fundamentally different approach. Instead of custom REST calls, it provides a standard, agent‑native way for tools to be discovered at runtime. Any MCP‑compatible agent can connect to our remote endpoint, inspect the available tools, understand their schema automatically, and start using them without custom coding. This plug‑and‑play model lets agents adapt to contract changes, reduces breakage, avoids hardcoded integrations, and delivers relevant content simply by pointing to the Learn MCP server.

Architecture in brief

We host a remote MCP server in front of Learn knowledge service. MCP clients connect over Streamable HTTP Transport. We used the official C# SDK for MCP to implement the transport and session handling, hosted on Azure App Service. Learn MCP Server is backed by a content vector store, the same knowledge service powering Ask Learn. This means agents benefit from the same freshness guarantees, relevance ranking, and index coverage that Microsoft uses for RAG-based experiences. Where Ask Learn serves end-user chats directly, Learn MCP Server wraps the knowledge retrieval capability in a standard protocol, making it discoverable and usable by any MCP-compatible agent.

From left to right users activate AI agents that invoke Learn MCP Server tools to search documentation or code samples using a semantic search layer that consists of Azure app service, AI Search, OpenAI, and blob storage which contains chunks of Microsoft Learn documentation

The lessons that follow explain what the Learn team discovered while designing, launching, and now operating the Microsoft Learn MCP Server. These are lessons that speak to the realities of building agent-facing systems at scale and go beyond implementation details. We are sharing not just what was built, but why the decisions we made mattered and what surprised us on this journey. These lessons are reflections of this experience for shaping our approach to tool design, retrieval integration, and protocol-driven product experiences.

Lesson 1 — “Your API is not an MCP tool”

A key principle: design tools for the agent workflow, not to mirror internal APIs. The Learn knowledge service exposes many parameters, including topK, index selection, thresholds, OData filters, and vector vs. hybrid search. Our tools compress this into two intuitive operations (search, fetch) matching the human “search-and-read” pattern that LLM agents naturally follow. We documented this separation explicitly so that future tool additions don’t bleed lower-level retrieval choices into the agent contract.

Lesson 2 — Remote servers behave like distributed systems

Hosting a public MCP server meant dealing with cross-region deployments, dynamic scaling, CORS, session affinity, statelessness, and data-protection concerns. Even though MCP is “just tools over JSONRPC,” operational realities resemble any stateless, multi-region service. We work with MCP C# SDK maintainers to ensure best practices and achieve our own business objectives.

Lesson 3 — Tool descriptions are your agent experience

We learned that tool and parameter descriptions function like user manuals for agents and language models. Small wording changes can swing tool activation rates materially. We built an automated evaluation tool to iterate descriptions based on observed agent behavior and success metrics—then deployed updated descriptions which clients discover at session refresh.

Lesson 4 — Compose tools for better outcomes

Search and fetch work better together. For example, a client can first find the best match and then ground the answer with the full-page Markdown. We tuned the descriptions to explicitly teach this follow-up usage, improving both groundedness and citation quality in downstream agents.

Lesson 5 — Expect (and defend against) hardcoded callers

Even with MCP dynamic tool discovery, some clients still hardcode tool schemas as if they were fixed APIs. When we renamed a parameter from question to query, 2–5% of requests broke until we supported both names (optional) during a deprecation window. Defensive evolution is part of operating a public service. To help the community avoid such pitfalls, Microsoft Research introduced guidance on tool space interference and released MCP Interviewer, which can flag schema and behavioral issues before agents trip over them. We used these learnings when refining our tool contracts.

Lesson 6 — Let data drive iteration

Aggregated usage patterns showed that most requests are related to coding tasks, explaining, and troubleshooting. We prioritized description and retrieval changes against these observed intents to maximize impact. In parallel, the product documentation contains agent instructions that nudge tools to be used when Microsoft technologies are involved—another data-driven change to improve grounding.

What this enables

Previously, an engineer working in a development environment would have to open a browser window, enter a search query, skim search results, open one or more links, read pages to find an answer, and copy that back to the development environment. Now you can add Learn MCP Server to your favorite agent and make it apply Learn content directly from the source straight to your situation.

Connect with us in the Learn MCP Server repository to configure your agent and for more information.


Post Updated on February 11, 2026 at 07:23PM
Thanks for reading
from devamazonaws.blogspot.com

Comments

Post a Comment

Popular posts from this blog

[MS] Debugger breakpoints are usually implemented by patching the in-memory copy of the code - devamazonaws.blogspot.com

In practice, when you set a code breakpoint in the debugger, the debugger replaces the instruction at that location with a breakpoint instruction.¹ When execution reaches that instruction, it will encounter the breakpoint instruction and break into the debugger. When the program has been stopped in the debugger, what happens next can vary from debugger to debugger. Some debuggers remove all their breakpoints when the program stops, and then restore the breakpoints when the program resumes. Other debuggers leave the breakpoints in place even when the program is stopped. In both cases, if you inspect the memory in the debugger, you will see the original unpatched code. In the first case, it's because the code really is unpatched; the breakpoint instructions are removed. In the second case, it's because the debugger is lying to you and showing you the original bytes even though they aren't what are in memory right now. Most of the time, this deception is insignificant. Eve...
Read more

Amazon EKS now enforces upgrade insights checks as part of cluster upgrades - devamazonaws.blogspot.com

Today, Amazon Elastic Kubernetes Service (EKS) announced a new control to prevent accidental cluster upgrades when issues are already detected that may impact application compatibility with the next Kubernetes version. This feature leverages EKS upgrade insights and is significant step towards giving cluster administrators confidence with Kubernetes version upgrades. EKS upgrade insights automatically scan clusters against a list of potential Kubernetes version upgrade impacting issues such as deprecated Kubernetes API usage. EKS periodically updates the list of insight checks to perform, based on evaluations of changes in the Kubernetes project, as well as changes introduced in the EKS service along with new versions. With this new control, EKS will prevent you from upgrading the EKS clusters if there are any Kubernetes version upgrade impacting issues surfaced by EKS upgrade insights. Once the upgrade impacting issues are resolved, you will be able to upgrade the Kubernetes versio...
Read more

[MS] Exciting new T-SQL features: Regex support, Fuzzy string-matching, and bigint support in DATEADD – preview - devamazonaws.blogspot.com

We are thrilled to announce the public preview of three powerful T-SQL features that will elevate your SQL queries: Regular Expressions (Regex) support, Fuzzy string-matching , and bigint support in DATEADD . These enhancements are now available in Azure SQL Database and SQL Database in Microsoft Fabric , offering developers more flexibility, efficiency, and precision in their data operations. They will also help simplify complex operations that previously required workarounds or external processing. In this post, we'll explore the capabilities of each feature, provide practical examples, and explain how they will transform the way you write T-SQL queries. Regular Expressions (Regex) support in T-SQL Regular expressions are a powerful tool for pattern matching and data extraction. They allow you to search, validate, and manipulate text based on specific patterns. With native Regex support in T-SQL, you can now use POSIX-compliant regular expressions to perform sophisticated stri...
Read more