Microsoft Learn MCP Server Cursor IDE Setup 2026
Microsoft Learn MCP server Cursor IDE setup 2026: add the free, no-auth endpoint at learn.microsoft.com/api/mcp, what the three docs tools do, a Cursor rule that makes the agent actually use them, token budgets, and fixes for 405 and missing-tool errors.
How do you add the Microsoft Learn MCP server to Cursor? Add a remote server with the URL https://learn.microsoft.com/api/mcp under Settings > Tools & MCP, or put it in ~/.cursor/mcp.json. There is no API key, no sign-in and no charge. Once it connects, Cursor's agent gets three tools: microsoft_docs_search, microsoft_docs_fetch and microsoft_code_sample_search. They search and read Microsoft's official documentation and code samples, so answers about Azure, .NET, C#, PowerShell, Microsoft 365 and the rest come from current docs instead of the model's training data.
That is the whole install. The part most people skip is the second step: telling the agent when to use the tools. Microsoft's own README says even tool-friendly models sometimes don't call MCP tools on their own, and suggests a Cursor rule. This guide covers both, plus the errors you will actually see.
If MCP itself is new to you, read what the Model Context Protocol is first.
What the Microsoft Learn MCP server is (and is not)
Microsoft describes it as a remote MCP server using Streamable HTTP that gives agents "trusted and up-to-date information directly from Microsoft's official documentation." According to the product overview on Microsoft Learn, it sits on the same Learn knowledge service that powers Ask Learn and Copilot for Azure.
A few facts from that page and the MicrosoftDocs/mcp README shape how you use it:
It is a documentation server, not a control plane. It will tell the agent the correct az containerapp create flags; it will not run them. For acting on resources, you want the Azure MCP server or, for Boards and Repos, the Azure DevOps MCP server. Many people run the Learn server alongside one of those, so the agent can look something up and then do it.
The three tools
| Tool | What it does | Input |
|---|---|---|
microsoft_docs_search | Semantic search across Microsoft's official technical documentation | query |
microsoft_docs_fetch | Fetches a full Microsoft documentation page and converts it to markdown | url |
microsoft_code_sample_search | Searches official Microsoft and Azure code snippets and examples | query, optional language |
In practice the agent tends to search first, then fetch the one or two pages that matter. Search returns excerpts; fetch returns the full article, which is what you want for a long procedure or a limits table. The code sample tool is the one to lean on when the question is "what is the actual method signature," since its results come from Microsoft's own samples rather than a blog post.
Before you start
~/.cursor/mcp.json; per-project config is .cursor/mcp.json in the repo root. Our Cursor MCP setup guide covers the basics if you have never added a server.Option 1: One-click install
The MicrosoftDocs/mcp README has an Install in Cursor button. It opens Cursor with a prefilled server named microsoft-learn, type http, URL https://learn.microsoft.com/api/mcp. Accept the prompt, and the server appears under Tools & MCP. Check that its status indicator turns green and that the three tools are listed under it.
This is the fastest route on a personal machine. If you want the config checked into a repo so your whole team gets it, use option 2.
Option 2: Add it to mcp.json
Open ~/.cursor/mcp.json for a global install, or create .cursor/mcp.json in your project for a shared one, and add:
{
"mcpServers": {
"microsoft-learn": {
"type": "http",
"url": "https://learn.microsoft.com/api/mcp"
}
}
}
If the file already has servers, add the microsoft-learn block inside the existing mcpServers object rather than creating a second one. Save, go back to Settings > Tools & MCP, and toggle the server on if it isn't already.
Because there are no secrets in this config, the project-level file is safe to commit. That is a nice property: a .NET or Azure repo can ship with the docs server preconfigured for everyone who opens it.
Note the key name. Microsoft's generic "standard config" in the README uses a top-level servers object, which is the VS Code format. Cursor expects mcpServers. Pasting the VS Code snippet unchanged is one of the more common reasons the server never shows up.
Optional: cap how much text comes back
Microsoft documents an experimental maxTokenBudget query parameter that truncates search tool responses to fit a budget:
{
"mcpServers": {
"microsoft-learn": {
"type": "http",
"url": "https://learn.microsoft.com/api/mcp?maxTokenBudget=2000"
}
}
}
This is useful if long search results are crowding your context window or driving up usage on a metered model. The trade-off is that truncated excerpts may cut off the detail you needed, in which case the agent has to follow up with a fetch. Microsoft labels the parameter experimental and subject to change, so treat it as a tuning knob, not a guarantee. There is also an experimental OpenAI-compatible endpoint at /api/mcp/openai-compatible; that one is aimed at OpenAI Deep Research models and you don't need it in Cursor.
Step 3: Make the agent actually use it
Installing the server gives the agent the option. It doesn't make the agent use it. Microsoft's README says this directly: even strong tool-calling models sometimes fail to call MCP tools by default, and it recommends a system prompt. In Cursor, that means a rule.
Create .cursor/rules/microsoft-docs.mdc in your project (or add it to your user rules) with something like:
---
description: Use Microsoft Learn MCP for Microsoft technology questions
alwaysApply: true
---
## Querying Microsoft documentation
You have access to MCP tools called `microsoft_docs_search`,
`microsoft_docs_fetch`, and `microsoft_code_sample_search`. They search and
fetch Microsoft's latest official documentation and code samples, which may be
newer or more detailed than your training data.
For questions about Azure, .NET, C#, ASP.NET Core, Entity Framework, NuGet,
PowerShell, Microsoft Graph or other Microsoft technologies, search the docs
before answering, fetch the most relevant page for procedures or limits, and
cite the Learn URL you used.
The wording above adapts the example in Microsoft's README, which targets .NET; widen or narrow the technology list to match your stack. Two practical notes. First, "cite the URL" is worth keeping: it lets you click through and confirm the answer in seconds. Second, if you only want the docs lookups in certain repos, put the rule in those projects instead of your global rules, so the agent doesn't go searching Microsoft Learn while you are writing Python for a non-Microsoft stack.
Our Context7 guide uses the same rule pattern for general library docs. The two servers complement each other: Context7 for open-source libraries, Microsoft Learn for Microsoft's own platforms.
Check that it works
Open Agent mode in a new chat and try prompts like the examples Microsoft lists:
IHttpClientFactory in a .NET 8 minimal API?"You should see tool calls to microsoft_docs_search or microsoft_code_sample_search in the agent's steps, followed by an answer that references learn.microsoft.com pages. If the agent answers from memory without any tool call, your rule isn't loading; check that the file is in .cursor/rules/, has the frontmatter, and that you started a new chat after adding it.
A good test is a question where training data is likely stale: a recently renamed service, a new SDK version, or a regional availability question. Those are exactly the cases this server exists for.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
405 Method Not Allowed | You opened the URL in a browser or hit it with a plain GET | Expected. The endpoint only speaks MCP over Streamable HTTP. Test from Cursor or the MCP Inspector instead. |
| Server never appears in Tools & MCP | Wrong top-level key (servers instead of mcpServers) or invalid JSON | Use the Cursor format above and validate the file. A trailing comma is enough to break it. |
| Red status / connection error | Network or proxy blocking learn.microsoft.com, or a typo in the URL | Confirm the URL exactly, then check proxy or firewall rules. |
| Tools listed but never called | Model isn't choosing them | Add the Cursor rule from step 3 and start a new chat. |
| "No results" | Query too vague | Ask with specific product and API names. Microsoft's README suggests more specific technical terms. |
| Answers cut off mid-procedure | maxTokenBudget set too low | Raise or remove the parameter, or ask the agent to fetch the full page. |
For anything else, our general guide to debugging MCP server issues walks through Cursor's MCP logs.
What about the Microsoft Learn CLI?
Microsoft also publishes @microsoft/learn-cli, which exposes the same search, fetch and code-sample functions in a terminal (npx @microsoft/learn-cli search "azure functions timeout"). Its mslearn setup --cli command installs an agent skill for GitHub Copilot, Claude Code and Codex. The README is explicit that this workflow does not configure MCP or install for agents outside those plugin ecosystems, and it names Cursor as an example. In Cursor, use the MCP server. Microsoft also says that when both are installed, agents should prefer the MCP tools and use the CLI only as a fallback.
Limits worth knowing
Frequently asked questions
Does the Microsoft Learn MCP server need an API key?
No. Microsoft states there is no authentication required. You only need an MCP client such as Cursor and network access to learn.microsoft.com. Using it means agreeing to the Microsoft Learn Terms of Use.
Is the Microsoft Learn MCP server free?
Yes. Microsoft's overview says it is publicly available with no charge to use the MCP server. Your Cursor plan and model usage still apply as normal.
What is the Microsoft Learn MCP server URL?
https://learn.microsoft.com/api/mcp. In Cursor, add it as an HTTP server under mcpServers in mcp.json, or use the Install in Cursor button in the MicrosoftDocs/mcp README.
Why do I get a 405 error from learn.microsoft.com/api/mcp?
Because a browser or plain HTTP request can't talk to it. The endpoint expects an MCP client over Streamable HTTP. A 405 in the browser is normal and does not mean the server is down.
Can the Microsoft Learn MCP server manage my Azure resources?
No. It searches and fetches public documentation and code samples. To list or change Azure resources from Cursor, add the Azure MCP server, and use the Learn server alongside it for reference.
Related Guides
Sources: MicrosoftDocs/mcp README, Microsoft Learn MCP Server overview, @microsoft/learn-cli on npm, Cursor MCP documentation. Checked November 11, 2026.
Related guides
- Todoist MCP Server Cursor IDE Setup 2026: mcp.json + OAuth
- Trello MCP Server Cursor IDE Setup (2026): API Key + Token Config for Boards & Cards
- Turso MCP Server Cursor IDE Setup 2026: Read-Only SQLite/libSQL Queries from Chat
- Twilio MCP Server Cursor IDE Setup (2026): API Key Config for SMS, Voice & Lookups