In-Depth

Hands On: Building an MCP Server with VS Code AI Toolkit's New Tool Catalog

• By David Ramel
• 03/10/2026

Microsoft recently added a "Tool Catalog" to its AI Toolkit extension for VS Code with a Manual category where you can "Create New MCP server" with Python or TypeScript.

Both options provide a weather tool template that you can customize with your own logic. The promise is a working server with zero boilerplate, pre-configured for both HTTP and stdio transport, and ready to connect to AI assistants like Copilot.

I've been experimenting with agentic AI in VS Code and decided to test out MCP server functionality to duplicate some of the stuff I did with agents, namely format and prepare my articles for Visual Studio Magazine. Although I chose a proof-of-concept for my editorial workflow, the same process would apply to any custom tool you want to build, where coding is obviously foremost. The template handles the MCP plumbing; you just write the logic. As I'm not a coder, I used GitHub Copilot Chat to guide me through the process, which is where the fun and frustration began.

The Idea: A Linter for Tech Journalism
As a tech journalist, I publish to a CMS with specific house rules that I enforced with agentic AI in a couple different ways. An MCP server that checks articles against those rules seemed like a natural fit.

The template's server.py used FastMCP -- a Python wrapper around the Model Context Protocol that reduces a tool definition to a decorated function. Replacing the weather tool with an editorial checker meant writing 12 regex-based check functions and two initial tool endpoints: one that accepts pasted text, one that reads a file from disk by path. I got Copilot to polish the project to the point where I just need to type QA in a terminal and it would go to work on the most recently edited file, which is always the file I have open in VS Code. I wanted to trigger it with a keyboard command but Copilot couldn't get that to work, even through what seemed like hours of trying.

The initial result: a server that checks for curly quotes, em/en dashes, missing target="_blank", <q> tags, <p> inside <li>, bold in body copy, hype words, unnecessary adverbs, passive voice, sentences over 30 words, and generic homepage links. Each issue comes back with a severity (error, warning, or info), position, and suggested fix. I changed a lot of that afterward just to get a tool I could use, beyond a simple PoC.

The whole initial customization took about 20 minutes, most of which was writing the check functions. The MCP plumbing -- transport, tool registration, JSON serialization -- was handled entirely by the template. That's the actual value of the Tool Catalog: not that it writes your logic, but that it eliminates everything else.

Testing: The Good Path and the Bad One
The template includes two ways to test your server. Both are pre-configured and documented in the README.

MCP Inspector is a browser-based UI that connects directly to your server's HTTP endpoint. You start the server in one terminal, start the Inspector in another, open localhost:5173 in a browser, connect to localhost:3001/mcp, and call your tools directly. It's raw -- you get JSON back, not a conversation -- but it's completely isolated from VS Code's internals. Nothing can freeze. This is the right way to verify your server is working before showing it to anyone.

Running check_article_file against a test HTML file returned 5 correctly identified issues in under a second: two hype words, a missing target="_blank", and a generic homepage link flagged twice by overlapping regex patterns. The server worked exactly as designed.

Agent Builder is where things got complicated. Note that it's optional -- useful for chat‑testing agents that call tools -- but not required to create or validate an MCP server built from the Tool Catalog. If it misbehaves, test the server in MCP Inspector first

The Extension Host Problem
AI Toolkit's Agent Builder is a conversational interface -- you chat with an AI model that can call your MCP tools on your behalf. It's a more compelling demo than raw JSON. And it's configured to launch automatically when you press F5 in the project.

The problem is architectural. VS Code runs all extensions in a single process called the extension host. When F5 triggers the "Debug in Agent Builder" compound task, it starts the Python server, then signals AI Toolkit to open Agent Builder as a panel. If Agent Builder gets stuck -- trying to connect to a model endpoint that times out, or loading into a bad state -- it blocks the entire extension host. Every other extension in that process stops responding. Including Copilot.

This happened twice. The symptom both times was a spinning "Loading extension" indicator in the Agent Builder panel that never resolved, combined with Copilot going silent.

There was a lot of frantic troubleshooting just to get Copilot back, and the fix might have involved going to the Extensions panel (Ctrl+Shift+X), finding AI Toolkit, and disabling it. Disabling an extension unloads it from the extension host, which forces a restart of that process. Everything else -- including Copilot -- eventually came back. Re-enabling AI Toolkit loads it fresh, clearing whatever state caused the hang -- neither I nor Copilot was sure what it was. I feared VS Code would need to be re-installed and I was so worried about losing my entire customized setup I was trying things fast and furiously and wasn't sure what finally did the trick.

This is not a bug you can file a clear report on. It's a consequence of VS Code's single-process extension model combined with a network operation (model endpoint connection) that lacks a timeout short enough to prevent blocking. It may be resolved in future versions of AI Toolkit. For now, the workaround might be to open Agent Builder manually and confirm it's healthy before pressing F5 -- and to know that disabling the extension might be the escape hatch if it isn't.

The Simpler Path: A Keyboard Shortcut That Should Work but Doesn't
After fighting the server and Inspector workflow, I (aka Copilot) realized something: the check functions in server.py are plain Python. They don't need the MCP server running. They don't need a browser. They don't need Agent Builder. They just need a file path and an import.

So I (aka Copilot) wrote a 70-line CLI wrapper -- check_article_cli.py -- that imports the check functions directly and prints results sorted by severity. Then I tried to wire it to two VS Code tasks bound to keyboard shortcuts.

Ctrl+Shift+Q -- Check: scans the open file and lists every issue with severity and suggested fix. Nothing is changed.

Ctrl+Shift+F -- Fix: automatically corrects everything it can safely fix without editorial judgment -- curly quotes, em/en dashes, missing target="_blank", <q> tags, <p> inside <li> -- writes the file back, then reports what still needs a human rewrite.

Like I said, hours of frustration couldn't get that to work. Copilot never figured out why but kept gamely trying, going in circles. I finally had to tell the poor thing to just give up on that functionality -- it would have churned on forever. One big problem was that some troubleshooting steps required opening a new folder or restarting VS Code, both of which lost the chat I was working in. There are supposedly ways to recover a chat, but they are unreliable in my experience (such as via Command Palette). It's surprising to me that this functionality isn't readily available like in other tools such as ChatGPT. It made for a lot of nail-biting, copying entire long chats (a problematic process in itself) before restarting and duplicating prompts again and again and trying to get Copilot to pick up where it left off. That was the worst part of the experience.

The Conversational Path: Copilot Chat as the Editor
While I did get the tool to work in the terminal, there's another interface. Since the MCP server is registered globally in my VS Code "Writing" profile, Copilot Chat can call it directly. No Agent Builder. No browser. No extra windows. I just wanted a quick and simple keyboard command but I had to settle for the terminal or Copilot.

For the latter, the setup is a single entry in VS Code's mcp.json profile config pointing to the server's stdio transport. Once added, Copilot launches the server silently on demand -- it spins up, answers the tool call, and shuts down. Nothing to manage.

The workflow then becomes:

"Check my-article.html for editorial issues and list each one numbered with your suggested fix."

Copilot calls check_article_file, sees every issue, and responds with a numbered list -- each entry showing what was found, why it's a problem, and a concrete suggested replacement. You review the list and respond:

"Accept 1 and 3, skip 2 and 4."

Copilot edits the file directly, then re-runs the check automatically to confirm the issues are resolved.

This works from any workspace. My Articles folder doesn't need the MCP project open alongside it. The server project only needs to be open when modifying the rules themselves.

What the Tool Catalog Actually Delivers
Setting the Agent Builder friction aside, the Tool Catalog does what it promises. You get:

• A working MCP server in the language of your choice, with zero boilerplate to write
• HTTP and stdio transport pre-configured
• Debug configurations for both Agent Builder and MCP Inspector
• A mcp.json that tells AI Toolkit where your server lives
• A virtual environment setup with the right dependencies pinned

What it doesn't give you is any guidance on what to build. The weather example is functional but deliberately trivial. The interesting work -- deciding what tools to expose, what logic they should contain, how to structure their inputs and outputs -- is entirely on you. The template is scaffolding, not a solution.

For developers who already know what they want to build, that's exactly right. For journalists or non-developers exploring what's possible, the gap between "template works" and "useful tool works" is where the real learning happens.

The Practical Upshot
My editorial checker works. I can open any HTML file in my Articles folder, ask Terminal or Copilot to check it, and within a second get a complete list of everything that violates house style. The mechanical fixes apply themselves. The judgment calls stay with me.

The initial result was flagging too many trivial things, like an author's name about a dozen times, so Copilot installed a spell checker that improved the results significantly. I also had to remove the passive voice checker because it was flagging every sentence that used "is" as a verb, which is a lot in journalism. I also had to remove the long sentence checker because it was flagging every sentence over 30 words, which is also a lot in journalism. The final version is much more usable, and I can run it on any article with a single command.

That's the actual promise of MCP: a standard interface that lets tools plug into AI assistants without tight coupling to any one platform. The AI Toolkit's Tool Catalog is a fast on-ramp to that ecosystem. The Agent Builder instability is a real friction point, but it's a friction point around testing and demonstration -- not around the server itself. And once the server is registered with Copilot directly, Agent Builder becomes optional anyway.

The server runs. The tool works. The scaffolding got me there in an afternoon. And Copilot handles the rest without me switching windows.

That said, I've duplicated the same functionality -- actually much more robust and easier-to-use functionality -- in both a VS Code agent -- with two different approaches, one that uses separate agent orchestration -- and in a custom GPT with ChatGPT. Both of those approaches are more user-friendly and reliable than the MCP server, which is really just a backend API. The agent approach is more flexible and easier to modify on the fly, while the custom GPT approach is more accessible to non-developers. The MCP server is performant and can be integrated into any workflow, but it requires coding and maintenance. But it served to write a PoC article to investigate how it works. So for my actual work, I'm using the agent and custom GPT, and treating the MCP server as an interesting experiment in what's possible with AI tooling in VS Code. As stated, the approach can be easily amended for coding scenarios.

The Parts
For context, the tool's server.py numbered 2,565 words, with the check functions taking up the bulk of that.

Here's the project structure in VS Code:

and the corresponding File Explorer structure, which the tool set up in my User directory:

In summary: The project is a Python MCP server built from the AI Toolkit template, customized to check tech journalism articles for editorial style violations. It uses FastMCP, runs over HTTP on port 3001 or stdio, and exposes three tools: check_article, check_article_file, and fix_article_file. A standalone CLI script (check_article_cli.py) should provide direct keyboard-shortcut access to the same checks without the server -- maybe a coder can get that working.