-
Notifications
You must be signed in to change notification settings - Fork 496
[WIP] Conceptual doc for NuGet MCP #3449
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Draft
joelverhagen
wants to merge
3
commits into
main
Choose a base branch
from
jver-mcp
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Draft
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,69 @@ | ||||||
| --- | ||||||
| title: MCP servers in NuGet packages | ||||||
| description: How can MCP servers be distributed using NuGet? | ||||||
| author: joelverhagen | ||||||
| ms.author: jver | ||||||
| ms.topic: conceptual | ||||||
| ms.date: 07/23/2025 | ||||||
| --- | ||||||
|
|
||||||
| # MCP servers in NuGet packages | ||||||
|
|
||||||
| NuGet provides a convenient way to package and distribute MCP servers written in .NET. | ||||||
|
|
||||||
| This document describes how MCP relates to NuGet and what benefits there are for using NuGet and the .NET ecosystem to author and distribute local MCP servers. | ||||||
|
|
||||||
| The intended audience of this document is anyone who is interested in **creating their own local MCP server** and is considering implementing the MCP server using .NET. | ||||||
|
|
||||||
| For more information about Model Context Protocol (MCP) in general, see the [introduction on the MCP website](https://modelcontextprotocol.io/introduction). | ||||||
|
|
||||||
| To create your own MCP server and package it using NuGet, see the [quickstart guide](/dotnet/ai/quickstarts/build-mcp-server). | ||||||
|
|
||||||
| ## Key considerations when building an MCP server | ||||||
|
|
||||||
| If you're interested in building an MCP server, ask yourself the following questions. The answers will help you decide if using a NuGet MCP server is the right decision for you. | ||||||
|
|
||||||
| - **What programming language do you want to write the MCP server in?** MCP is a language agnostic protocol and there are several official SDKs. The [MCP website](https://modelcontextprotocol.io/quickstart/server) lists several official SDKs. | ||||||
| - **Do you want the MCP server to be a local process running in the same context as the MCP client** or should it be a central web service that you manage the operations of? This document focuses on local MCP servers, instead of remote ones. | ||||||
| - **What runtime requirement are tolerable for your clients when launching the local MCP server process?** Popular MCP clients such as VS Code launch a local MCP server using a process like `npx` (for npm-based MCP servers) or `dnx` (for NuGet-based MCP servers). The client must have the appropriate runtime in order to acquire and execute the MCP server package. | ||||||
|
|
||||||
| If you or your team is familiar with C# and the .NET ecosystem, shipping your MCP server via NuGet is a great option. | ||||||
|
|
||||||
| If C# is new to you or your team, consider some of the trade-offs mentioned below. The .NET SDK provides a great way to package MCP servers into a single, optimized package with minimal runtime dependencies. | ||||||
|
|
||||||
| ## Applicable scenarios | ||||||
|
|
||||||
| Shipping your MCP server via NuGet does not apply to all situations. The term "MCP client" is used in this document and refers to an application that orchestrates the interaction between an AI agent or LLM and calls made to an MCP server. Some example MCP clients are [Visual Studio Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers), [Visual Studio](https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers), [GitHub Copilot coding agent](https://docs.github.com/copilot/concepts/coding-agent/about-copilot-coding-agent), Claude Code, or Cursor. | ||||||
|
|
||||||
| Consider the following criteria to determine if shipping your MCP server as a NuGet package makes sense: | ||||||
|
|
||||||
| - ✅ You want your MCP server to run **locally** on the user's system (i.e. in the same context as the MCP client). | ||||||
| - Instead of locally running MCP servers, MCP servers can also be hosted on a web server and communicated with via a streaming HTTP protocol. Local MCP servers, such as those shipped in NuGet package,s run in the same context as the MCP client communicate with the MCP client via a standard IO (stdio) transport. The MCP client is responsible for launching the local MCP server process. | ||||||
| - ✅ The .NET SDK is available to the MCP client. | ||||||
| - NuGet MCP servers are [.NET tool packages](https://learn.microsoft.com/en-us/dotnet/core/tools/global-tools), which are installed and executed using the .NET SDK. | ||||||
| - ✅ You have have a NuGet package feed to host your MCP server package. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There is a duplicate word 'have' in this sentence. It should be 'You have a NuGet package feed...'.
Suggested change
Copilot uses AI. Check for mistakes. Positive FeedbackNegative Feedback |
||||||
| - NuGet.org can be used to public MCP server packages and provides a tailored MCP browsing and consumption experience. However, any NuGet package feed, such as Azure Artifacts, can be used for hosting MCP servers if you wish to keep your MCP server package private. | ||||||
|
|
||||||
| ## Benefits of using NuGet for MCP servers | ||||||
|
|
||||||
| There are several benefits to using NuGet for hosting your MCP server: | ||||||
|
|
||||||
| - **Official SDK** - the [MCP C# SDK](https://github.com/modelcontextprotocol/csharp-sdk) provides a familiar interface for implementing your MCP server in C# and makes it easy to expose tools to MCP clients. | ||||||
| - **Flexible runtime options** - the .NET SDK provides several options for how your MCP is compiled and packaged. Generally, you can choose between using a on a runtime available on the client system, include a specific runtime inside the package, or compile your tool using [AOT](https://learn.microsoft.com/dotnet/core/deploying/native-aot/). | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There is a grammatical error: 'using a on a runtime' should be 'using a runtime' (remove the extra 'on a').
Suggested change
Copilot uses AI. Check for mistakes. Positive FeedbackNegative Feedback |
||||||
| - **Familiar authoring workflows** - if you already use NuGet for creating dependency packages (libraries distributed via NuGet), creating and publishing an MCP server be a very similar experience. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Missing word 'will' in the sentence. It should be 'creating and publishing an MCP server will be a very similar experience'.
Suggested change
Copilot uses AI. Check for mistakes. Positive FeedbackNegative Feedback |
||||||
| - **MCP server browsing experience** - NuGet.org provides a way to showcase your MCP server, allowing potential users to find your MCP server and easily use it from inside from VS Code or Visual Studio. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There is a duplicate preposition 'from' in the phrase 'from inside from VS Code'. It should be either 'from inside VS Code' or 'from VS Code'.
Suggested change
Copilot uses AI. Check for mistakes. Positive FeedbackNegative Feedback |
||||||
|
|
||||||
| ## Comparison with other ecosystems | ||||||
|
|
||||||
| We will compare NuGet and .NET to other ecosystems that are commonly used for implementing local MCP servers: npm (JavaScript, node.js), Python, and Docker. | ||||||
|
|
||||||
| ### Package aquisition | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Misspelled word 'aquisition' should be 'acquisition'.
Suggested change
Copilot uses AI. Check for mistakes. Positive FeedbackNegative Feedback |
||||||
|
|
||||||
| To execute a local MCP server, the code for the server must be located and downloaded. This is generally done with a "single-shot" command which takes the package name and arguments to download and then execute the package as a command-line application. | ||||||
|
|
||||||
| - **NuGet/.NET**: the `dnx` command is available in the .NET SDK starting with .NET 10 preview 6. By default it downloads packages from the central registry, NuGet.org. | ||||||
| - **npm**: the `npx` command downloads and executes from npmjs.com. | ||||||
| - **Python**: the `uvx` command downloads and executes from PyPI.org. | ||||||
| - **Docker**: the `docker run` command downloads and executes from Docker Hub by default, but can fetch from another container registry with a fully qualified name. | ||||||
|
|
||||||
| In all of these cases, the MCP client needs to have the need ecosystem-specific tool (e.g. `dnx`, `npx`) to download and launch the package-based MCP server. | ||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There is a duplicate word 'need' in 'have the need ecosystem-specific'. It should be 'have the needed ecosystem-specific tool' or 'have the ecosystem-specific tool'.
Suggested change
Copilot uses AI. Check for mistakes. Positive FeedbackNegative Feedback |
||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There is a misplaced comma in 'package,s' which should be 'packages'.
Copilot uses AI. Check for mistakes.