Skip to main content
← Back to Articles
mcpcursormicrosoftazuredotnetdocumentationsetup2026

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.

By Web MCP Guide•November 11, 2026•12 min read

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:

  • No authentication. Anyone can connect. Using it means agreeing to the Microsoft Learn Terms of Use.

  • Free. Microsoft states there is no charge to use it.

  • Public docs only. It covers publicly available documentation, not training progress or user profile data, and it cannot see your Azure tenant.

  • Refresh cadence. The knowledge service refreshes incrementally as content changes and does a full refresh once a day.

  • Tools can change. Microsoft tells developers building their own clients not to hard-code tool names or parameters, because the tool list will evolve. Cursor discovers tools at connect time, so this mostly matters if you script against 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

    ToolWhat it doesInput
    microsoft_docs_searchSemantic search across Microsoft's official technical documentationquery
    microsoft_docs_fetchFetches a full Microsoft documentation page and converts it to markdownurl
    microsoft_code_sample_searchSearches official Microsoft and Azure code snippets and examplesquery, 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


  • A recent Cursor build with MCP. Servers live under Settings > Tools & MCP. Global config is ~/.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.

  • Outbound HTTPS to learn.microsoft.com. That is the only network requirement. On a locked-down corporate network, check that a proxy is not blocking it.

  • Nothing to install. There is no npm package, Docker image or Python runtime involved for the MCP server itself.
  • 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:

  • "Give me the Azure CLI commands to create an Azure Container App with a managed identity."

  • "Are you sure this is the right way to implement IHttpClientFactory in a .NET 8 minimal API?"

  • "Show me runnable Python code for an evaluation using the Azure AI Foundry evaluation SDK."
  • 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

    SymptomLikely causeFix
    405 Method Not AllowedYou opened the URL in a browser or hit it with a plain GETExpected. The endpoint only speaks MCP over Streamable HTTP. Test from Cursor or the MCP Inspector instead.
    Server never appears in Tools & MCPWrong top-level key (servers instead of mcpServers) or invalid JSONUse the Cursor format above and validate the file. A trailing comma is enough to break it.
    Red status / connection errorNetwork or proxy blocking learn.microsoft.com, or a typo in the URLConfirm the URL exactly, then check proxy or firewall rules.
    Tools listed but never calledModel isn't choosing themAdd the Cursor rule from step 3 and start a new chat.
    "No results"Query too vagueAsk with specific product and API names. Microsoft's README suggests more specific technical terms.
    Answers cut off mid-proceduremaxTokenBudget set too lowRaise 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


  • It only knows what is published. Private docs, internal wikis and your own Azure resources are out of scope.

  • Up to a day behind on some changes. Incremental refreshes catch most updates, but the full refresh runs daily.

  • Answers are only as good as the page it picks. Microsoft Learn has overlapping articles for similar tasks. If an answer looks off, ask the agent which page it fetched and read it.

  • It adds tools to your list. Three tools is light, but if you run many servers, toggle off the ones a project doesn't need so the agent's tool choice stays sharp.
  • 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


  • Azure MCP Server Cursor IDE Setup (2026)

  • Azure DevOps MCP Server Cursor IDE Setup (2026)

  • Context7 MCP Server Cursor IDE Setup (2026)

  • Cursor IDE MCP Setup Guide
  • Sources: MicrosoftDocs/mcp README, Microsoft Learn MCP Server overview, @microsoft/learn-cli on npm, Cursor MCP documentation. Checked November 11, 2026.




    Related guides