MCP Builder (microsoft/skills)

tl;dr: the Microsoft-ecosystem variant of the MCP-builder procedure. Same four-phase shape as Anthropic’s mcp-builder (research → implementation → review/test → evaluations), but with a C# / .NET path bolted on via Microsoft.Mcp.Core, and an opening section that tells you to check Microsoft’s existing servers before writing your own (Azure MCP for 48 Azure services, Foundry MCP for models/agents, Fabric MCP, Playwright MCP, GitHub MCP at https://api.githubcopilot.com/mcp). Recommended language is TypeScript with @modelcontextprotocol/sdk + Zod; Python + FastMCP + Pydantic and C# + Microsoft.Mcp.Core are supported alternatives.

What it actually does

The SKILL.md fetched on 2026-09-10 from microsoft/skills/main/.github/skills/mcp-builder/SKILL.md opens with the Microsoft MCP ecosystem (a section Anthropic’s version does not have), then runs the same four sequential phases. Each phase points the agent at a ./reference/ doc loaded on demand.

Microsoft MCP ecosystem (Phase 0 — decide whether to build)

Before writing a custom server, the skill asks you to check what Microsoft already ships:

The recommendation table is concrete: Azure integration → Azure MCP Server; Foundry agents/evals → Foundry MCP remote; custom internal APIs → build custom; third-party SaaS → build custom.

Phase 1 — Deep research and planning

1. API coverage vs workflow tools. Balance comprehensive endpoint coverage with specialized workflow tools. Workflow tools are convenient; comprehensive coverage gives agents flexibility. Some clients benefit from code execution that composes basic tools; others prefer high-level workflows. When in doubt, prioritize comprehensive API coverage.
2. Tool naming. Clear, descriptive names with consistent prefixes (github_create_issue, github_list_repos); action-oriented verbs.
3. Context management. Concise tool descriptions; support filtering and pagination; some clients use code execution to slice results.
4. Actionable error messages. Errors guide the agent toward solutions with specific next steps — not stack traces.
5. Study the spec. Start at https://modelcontextprotocol.io/sitemap.xml, then fetch specific pages with .md suffix (https://modelcontextprotocol.io/specification/draft.md).
6. Choose stack. TypeScript recommended for broad compatibility (@modelcontextprotocol/sdk); Python for data/ML pipelines (mcp / FastMCP); C#/.NET for the Azure/Microsoft ecosystem (Microsoft.Mcp.Core).
7. Choose transport. Streamable HTTP for remote / multi-tenant / Agent Service (stateless, scalable, requires auth). stdio for local / desktop / single-user (simple, no network).
8. Plan the API surface. List endpoints, mark the common ones first, sketch parameter schemas.

Phase 2 — Implementation

• Project scaffold per the language guide (./reference/node_mcp_server.md, ./reference/python_mcp_server.md, ./reference/microsoft_mcp_patterns.md).
• Shared utilities: API client + auth, error helpers, response formatting (JSON or Markdown), pagination.
• Per tool:
  • Input schema: Zod (TypeScript) or Pydantic (Python). Include constraints and clear descriptions, examples in field descriptions.
  • Output schema: define outputSchema where possible; use structuredContent in TypeScript SDK responses.
  • Description: concise summary, parameter docs, return type schema.
  • Implementation: async/await, proper error handling, pagination, return both text and structured content on modern SDKs.
  • Annotations: readOnlyHint, destructiveHint, idempotentHint, openWorldHint — explicit per tool, not implicit.

Phase 3 — Review and test

• DRY, full type coverage, consistent error handling.
• TypeScript: npm run build to verify compilation, then MCP Inspector (npx @modelcontextprotocol/inspector).
• Python: python -m py_compile your_server.py then MCP Inspector.
• C# / .NET: the microsoft_mcp_patterns.md reference covers command hierarchy (BaseCommand → GlobalCommand → SubscriptionCommand), naming conventions ({Resource}{Operation}Command), option handling with .AsRequired() / .AsOptional(), and Azure Functions remote MCP deployment with Bicep test infrastructure.

Phase 4 — Create evaluations

• Write 10 questions, each: independent, read-only, complex (multi-call), realistic, verifiable, stable.
• The workflow is explicit: list available tools → read-only exploration → generate 10 questions → solve each one yourself before publishing.
• Output format is a strict XML envelope:

<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames…</question>
    <answer>3</answer>
  </qa_pair>
  <!-- 9 more qa_pairs -->
</evaluation>

The answer string is the ground truth the eval is graded against. The skill warns: a server without evaluations is not done.

Install

mcp-builder ships inside Microsoft’s plugin bundle (175 skills across language plugins). The wizard picks the skill; the README documents the manual path.

# Wizard — interactive install, picks mcp-builder from the Core catalog
npx skills add microsoft/skills

# Manual — clone the repo, copy the single skill folder
git clone https://github.com/microsoft/skills.git
cp -r microsoft/skills/.github/skills/mcp-builder \
  your-project/.github/skills/

# Multi-host: symlink so .claude/skills/ and .opencode/skills/ see it
ln -s ../.github/skills .claude/skills
ln -s ../.github/skills .opencode/skills

Targets GitHub Copilot CLI / VS Code Copilot out of the box (the README’s directory is .github/skills/). Claude Code and Cursor do not auto-discover that path — symlink or copy into .claude/skills/ / .opencode/skills/ as your host expects.

What it explicitly is not

• Not a generator. It does not produce a server without the user providing the API to wrap. The skill is the workflow; the API knowledge comes from the agent’s research phase.
• Not transport-agnostic in detail. Streamable HTTP for remote / multi-tenant; stdio for local. The procedural structure is reusable; the per-language SDK names are not.
• Not a registry publisher. Shipping to a registry (cache.directory, MCP Hub, etc.) is out of scope. The skill’s deliverable is a working server + an evaluation XML file.
• Not a replacement for Microsoft’s first-party servers. Phase 0 explicitly says to use Azure MCP / Foundry MCP / Fabric MCP / Playwright MCP / GitHub MCP if they cover your surface. Building your own Cosmos DB wrapper when Azure MCP already exposes Cosmos is the failure mode Phase 0 is designed to prevent.
• sandbox_test untested — we read the package, we did not run a server build in the sandbox. Per config/skill-safety.md, that verdict does not change until a human runs the eval-vs-prompt harness.

Gotchas

• The reference files must be fetched on demand. SKILL.md points at ./reference/mcp_best_practices.md, ./reference/node_mcp_server.md, ./reference/python_mcp_server.md, ./reference/microsoft_mcp_patterns.md, ./reference/evaluation.md. The skill assumes the host can reach raw.githubusercontent.com (for SDK READMEs) and modelcontextprotocol.io (for the spec). If the host is offline, the workflow stalls at Phase 2.
• TypeScript is recommended, not required. Python + FastMCP and C# + Microsoft.Mcp.Core are fully supported. The skill defaults to loading node_mcp_server.md first, so a Python or .NET user must tell the agent to switch references.
• Phase 0 matters. The Microsoft MCP ecosystem section is unique to this fork of the procedure. Skipping it because “we already know what we’re building” is how teams reinvent Azure MCP poorly.
• MCP Inspector is the verification step, not unit tests. npx @modelcontextprotocol/inspector spins up the server and lets you call tools interactively. The skill treats it as Phase 3’s pass/fail.
• Streamable HTTP ≠ stateful sessions. The skill recommends stateless JSON over streamable HTTP for remote servers. Stateful streaming sessions are not the default — read mcp_best_practices.md before deviating.
• C# / .NET path is non-trivial. The Microsoft.Mcp.Core SDK, the command hierarchy, Bicep test infra, and Entra ID / OBO / managed-identity auth are all referenced, not bundled inline. If you’re picking C#, budget time for microsoft_mcp_patterns.md.
• Eval questions are the gate. Skipping Phase 4 because “the server works” is the common failure mode. The skill’s verdict is explicit: a server without evaluations is not done.
• The skill is in active development. The README is explicit: “Work in Progress — this repository is under active development.” Test coverage for mcp-builder sits in Core (8 skills with 83 scenarios, harness-validated). Expect upstream edits.

Related: MCP Builder (Anthropic, official) (the upstream procedure this fork extends — TypeScript/Python focus, no C# path), Microsoft Copilot SDK (consumes MCP servers via its mcpServers config — pair with the server this skill produces), Cloud Solution Architect (the architecture-review sibling; use it before writing an MCP server for a multi-service system).