Add onboarding doc for Azure MCP Server

.github/agents/onboarding.agent.md

@@ -0,0 +1,44 @@
+---
+description: Azure MCP Server onboarding assistant - guides new contributors through prerequisites, adding namespaces and tools, and integrating external MCP servers
+---
+
+# Azure MCP Server Onboarding Agent
+
+This agent helps **new contributors** get productive in the Azure MCP Server repository. It
+orients you, then routes you to the right section of
+[Onboarding.md](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md) and the deeper
+authoritative docs.
+
+## What This Agent Helps With
+
+Ask about any of these and the agent will point you to the relevant steps and files:
+
+- **Prerequisites & setup** — required tooling (.NET, Node.js, PowerShell, Azure CLI/PowerShell,
+  Bicep), the NuGet feed, and the local build/test quick start.
+- **Adding a new namespace (toolset)** — scaffolding `tools/Azure.Mcp.Tools.{Toolset}`,
+  implementing `IAreaSetup`, registering in `Program.cs` `RegisterAreas()`, solution + AOT steps.
+- **Adding a new tool to an existing namespace** — the required files, naming conventions,
+  option/JSON/AOT rules, and how to validate with unit and recorded live tests.
+- **Integrating an external MCP server** — editing
+  `servers/Azure.Mcp.Server/src/Resources/registry.json`, choosing HTTP/SSE vs stdio transport,
+  and the authentication considerations.
+- **Opening a pull request** — the full PR checklist (format, build, spelling, changelog,
+  recorded tests, docs).
+
+## How To Route
+
+Match the contributor's intent to the matching section of
+[Onboarding.md](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md):
+
+| Intent | Section | Authoritative deep dive |
+| --- | --- | --- |
+| Set up my machine / build the repo | [Prerequisites](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#1-prerequisites), [Quick start](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#2-quick-start) | [CONTRIBUTING.md](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md) |
+| Create a brand-new namespace | [Add a new namespace](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#3-add-a-new-namespace-toolset) | [new-command.md](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md) |
+| Add one command/tool | [Add a new tool](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#4-add-a-new-tool-to-an-existing-namespace) | [new-command.md](https://github.com/microsoft/mcp/blob/main/servers/Azure.Mcp.Server/docs/new-command.md) |
+| Proxy an external MCP server | [Integrate an external MCP server](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#5-integrate-an-external-mcp-server) | [CONTRIBUTING.md](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md#configuring-external-mcp-servers) |
+| Get ready to submit | [PR checklist](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md#6-pull-request-checklist) | [CONTRIBUTING.md](https://github.com/microsoft/mcp/blob/main/CONTRIBUTING.md) |
+
+## Source Control
+
+Contributors work on a branch in **their fork** (for example `RickWinter/mcp`) and open the PR
+against `microsoft/mcp:main`. Encourage small, focused PRs.

.vscode/cspell.json

@@ -373,6 +373,7 @@
         "codesign",
         "codespace",
         "cognitiveservices",
+        "configfile",
         "containerapp",
         "containerapps",
         "contentazurefileconnectionstring",
@@ -538,6 +539,7 @@
         "ragzrs",
         "rainfly",
         "redisearch",
+        "remotemcp",
         "requesturl",
         "resourcegroup",
         "resourcegroups",
@@ -557,6 +559,7 @@
         "skillset",
         "skillsets",
         "skiptoken",
+        "slnx",
         "southafricanorth",
         "southcentralus",
         "southeastasia",
@@ -595,6 +598,7 @@
         "ukwest",
         "uncompress",
         "unhex",
+        "uniqueprefix",
         "upns",
         "usersession",
         "vectorizable",

CONTRIBUTING.md

@@ -6,6 +6,9 @@ After cloning and building the repo, check out the [GitHub project](https://gith
 >[!IMPORTANT]
 If you are contributing significant changes, or if the issue is already assigned to a specific milestone, please discuss with the assignee of the issue first before starting to work on the issue.
 
+>[!TIP]
+> New to the project? Start with the [Onboarding Guide](https://github.com/microsoft/mcp/blob/main/docs/Onboarding.md) for a guided walkthrough of prerequisites, adding a new namespace or tool, and integrating an external MCP server. You can also invoke the `@onboarding` agent in GitHub Copilot Chat.
+
 ## Table of Contents
 
 - [Contributing to Azure MCP](#contributing-to-azure-mcp)
@@ -240,7 +243,7 @@ Requirements:
 
 To ensure the product code and unit tests can be cancelled quickly, contributors are required to write async methods (any returning `Task`, `ValueTask`, generic variants of those, etc.) to accept and invoke async methods with a `System.Threading.CancellationToken` parameter. The latter is enforced with the [CA2016 analyzer](https://learn.microsoft.com/dotnet/fundamentals/code-analysis/quality-rules/ca2016).
 
-Mocks created with `NSubstitute.Substitue.For<T>()` and have [methods set up](https://nsubstitute.github.io/help/set-return-value/#for-methods) should be passed `NSubstitute.Arg.Any<CancellationToken>()` for required `System.Threading.CancellationToken` parameters. The same should be used when [checking for received calls on a mocked object](https://nsubstitute.github.io/help/received-calls/index.html). If the product code is expected to do something interesting with a supplied `System.Threading.CancellationToken` parameter, such as linking with other `System.Threading.CancellationToken`s with [`System.Threading.CancellationTokenSource.CreateLinkedTokenSource`](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtokensource.createlinkedtokensource), then consider testing for that behavior.
+Mocks created with `NSubstitute.Substitute.For<T>()` and have [methods set up](https://nsubstitute.github.io/help/set-return-value/#for-methods) should be passed `NSubstitute.Arg.Any<CancellationToken>()` for required `System.Threading.CancellationToken` parameters. The same should be used when [checking for received calls on a mocked object](https://nsubstitute.github.io/help/received-calls/index.html). If the product code is expected to do something interesting with a supplied `System.Threading.CancellationToken` parameter, such as linking with other `System.Threading.CancellationToken`s with [`System.Threading.CancellationTokenSource.CreateLinkedTokenSource`](https://learn.microsoft.com/dotnet/api/system.threading.cancellationtokensource.createlinkedtokensource), then consider testing for that behavior.
 
 Real product code under unit testing must be passed `Xunit.TestContext.Current.CancellationToken` when async methods are invoked. This is to ensure the tests can end to avoid possible issues with the parent process waiting indefinitely for the test runner executable to exit.
 
@@ -700,7 +703,7 @@ The Azure MCP Server implements the [Model Context Protocol specification](https
 
 ### Package README
 
-A single package README.md could be used to generate context specific content for different package types (npm, nuget, vsix) using html comment annotations to mark sections for removal or insertion whem processed with script at `.\eng\scripts\Process-PackageReadMe.ps1`
+A single package README.md could be used to generate context specific content for different package types (npm, nuget, vsix) using html comment annotations to mark sections for removal or insertion when processed with script at `.\eng\scripts\Process-PackageReadMe.ps1`
 
 Supported comment annotations:
 
@@ -780,7 +783,7 @@ The registry structure follows this format:
 - Use the `url` property to specify the endpoint
 - Supports HTTP-based communication with automatic transport mode detection
 - Best for web-based MCP servers and remote endpoints
-- Use `title` as the dislay name for the namespace tool (optional)
+- Use `title` as the display name for the namespace tool (optional)
 - Use `description` as the description of the namespace tool for the MCP server
 - Use `toolPrefix` to assign unique prefix to tools of the MCP server
 - If the MCP server requires authentication, use `oauthScopes` to specify the Entra client registration representing the MCP server