From 052d5b3935ca00bc467ca01aba4001debc8f3db4 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Wed, 18 Feb 2026 15:48:45 -0600 Subject: [PATCH 1/2] Fix client links in `docs/server-quickstart.md` to point to quickstart Both links to `./client.md` were pointing to the comprehensive API reference guide, but readers in the server quickstart tutorial would expect a beginner-friendly tutorial. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/server-quickstart.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/server-quickstart.md b/docs/server-quickstart.md index d0a7e6ed0..6b7aaa5e4 100644 --- a/docs/server-quickstart.md +++ b/docs/server-quickstart.md @@ -11,7 +11,7 @@ In this tutorial, we'll build a simple MCP weather server and connect it to a ho We'll build a server that exposes two tools: `get-alerts` and `get-forecast`. Then we'll connect the server to an MCP host (in this case, Claude for Desktop). > [!NOTE] -> Servers can connect to any client. We've chosen Claude for Desktop here for simplicity, but we also have a guide on [building your own client](./client.md) as well as a [list of other clients here](https://modelcontextprotocol.io/clients). +> Servers can connect to any client. We've chosen Claude for Desktop here for simplicity, but we also have a guide on [building your own client](./client-quickstart.md) as well as a [list of other clients here](https://modelcontextprotocol.io/clients). ## Core MCP Concepts @@ -370,7 +370,7 @@ Let's now test your server from an existing MCP host, Claude for Desktop. ## Testing your server with Claude for Desktop > [!NOTE] -> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Client guide](./client.md) to build an MCP client that connects to the server we just built. +> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Client quickstart](./client-quickstart.md) to build an MCP client that connects to the server we just built. First, make sure you have Claude for Desktop installed. [You can install the latest version here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.** From 335414ce2930edf9fae96e07220e39c4a7b21ee0 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Wed, 18 Feb 2026 17:48:41 -0600 Subject: [PATCH 2/2] Replace Claude for Desktop with VS Code + Copilot in server quickstart Claude for Desktop is not available on Linux, making it a stumbling block for the server quickstart. Replace the testing instructions with VS Code + GitHub Copilot, which works on all platforms and is free to use. - Replace `claude_desktop_config.json` setup with `.vscode/mcp.json` - Replace Claude Desktop troubleshooting with VS Code-specific guidance - Generalize "under the hood" section to say "LLM" instead of "Claude" - Update intro/summary references in `docs/documents.md` - Remove link to legacy debugging guide Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/documents.md | 2 +- docs/server-quickstart.md | 144 +++++++++++--------------------------- 2 files changed, 41 insertions(+), 105 deletions(-) diff --git a/docs/documents.md b/docs/documents.md index 37033ef0c..9e3034782 100644 --- a/docs/documents.md +++ b/docs/documents.md @@ -10,7 +10,7 @@ children: # Documents -- [Server Quickstart](./server-quickstart.md) – build a weather server from scratch and connect it to Claude for Desktop +- [Server Quickstart](./server-quickstart.md) – build a weather server from scratch and connect it to VS Code - [Server](./server.md) – building MCP servers, transports, tools/resources/prompts, sampling, elicitation, tasks, and deployment patterns - [Client Quickstart](./client-quickstart.md) – build an LLM-powered chatbot that connects to an MCP server and calls its tools - [Client](./client.md) – using the high-level client, transports, OAuth helpers, handling server‑initiated requests, and tasks diff --git a/docs/server-quickstart.md b/docs/server-quickstart.md index 6b7aaa5e4..ffa49cec5 100644 --- a/docs/server-quickstart.md +++ b/docs/server-quickstart.md @@ -4,14 +4,11 @@ title: Server Quickstart # Quickstart: Build a weather server -In this tutorial, we'll build a simple MCP weather server and connect it to a host, Claude for Desktop. +In this tutorial, we'll build a simple MCP weather server and connect it to a host. ## What we'll be building -We'll build a server that exposes two tools: `get-alerts` and `get-forecast`. Then we'll connect the server to an MCP host (in this case, Claude for Desktop). - -> [!NOTE] -> Servers can connect to any client. We've chosen Claude for Desktop here for simplicity, but we also have a guide on [building your own client](./client-quickstart.md) as well as a [list of other clients here](https://modelcontextprotocol.io/clients). +We'll build a server that exposes two tools: `get-alerts` and `get-forecast`. Then we'll connect the server to an MCP host (in this case, VS Code with GitHub Copilot). ## Core MCP Concepts @@ -365,80 +362,49 @@ main().catch((error) => { Make sure to run `npm run build` to build your server! This is a very important step in getting your server to connect. -Let's now test your server from an existing MCP host, Claude for Desktop. - -## Testing your server with Claude for Desktop - -> [!NOTE] -> Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Client quickstart](./client-quickstart.md) to build an MCP client that connects to the server we just built. - -First, make sure you have Claude for Desktop installed. [You can install the latest version here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.** +Let's now test your server from an existing MCP host. -We'll need to configure Claude for Desktop for whichever MCP servers you want to use. To do this, open your Claude for Desktop App configuration at `~/Library/Application Support/Claude/claude_desktop_config.json` in a text editor. Make sure to create the file if it doesn't exist. +## Testing your server in VS Code -For example, if you have [VS Code](https://code.visualstudio.com/) installed: +[VS Code](https://code.visualstudio.com/) with [GitHub Copilot](https://github.com/features/copilot) can discover and invoke MCP tools via agent mode. [Copilot Free](https://github.com/features/copilot/plans) is sufficient to follow along. -**macOS/Linux:** - -```bash -code ~/Library/Application\ Support/Claude/claude_desktop_config.json -``` - -**Windows:** +> [!NOTE] +> Servers can connect to any client. We've chosen VS Code here for simplicity, but we also have a guide on [building your own client](./client-quickstart.md) as well as a [list of other clients here](https://modelcontextprotocol.io/clients). -```powershell -code $env:AppData\Claude\claude_desktop_config.json -``` +### Prerequisites -You'll then add your servers in the `mcpServers` key. The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured. +1. Install [VS Code](https://code.visualstudio.com/) (version 1.99 or later). +2. Install the **GitHub Copilot** extension from the VS Code Extensions marketplace. +3. Sign in to your GitHub account when prompted. -In this case, we'll add our single weather server like so: +### Configure the MCP server -**macOS/Linux:** +Create a `.vscode/mcp.json` file in your `weather` project root: ```json { - "mcpServers": { + "servers": { "weather": { + "type": "stdio", "command": "node", - "args": ["/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js"] + "args": ["./build/index.js"] } } } ``` -**Windows:** +VS Code may prompt you to trust the MCP server when it detects this file. If prompted, confirm to start the server. -```json -{ - "mcpServers": { - "weather": { - "command": "node", - "args": ["C:\\PATH\\TO\\PARENT\\FOLDER\\weather\\build\\index.js"] - } - } -} -``` - -This tells Claude for Desktop: - -1. There's an MCP server named "weather" -2. Launch it by running `node /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js` - -Save the file, and restart **Claude for Desktop**. - -### Test with commands +To verify, run **MCP: List Servers** from the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`). The `weather` server should show a running status. -Let's make sure Claude for Desktop is picking up the two tools we've exposed in our `weather` server. You can do this by looking for the "Add files, connectors, and more /" icon. +### Use the tools -After clicking on the plus icon, hover over the "Connectors" menu. You should see the `weather` server listed. - -If your server isn't being picked up by Claude for Desktop, proceed to the [Troubleshooting](#troubleshooting) section for debugging tips. - -If the server has shown up in the "Connectors" menu, you can now test your server by running the following commands in Claude for Desktop: - -- What's the weather in Sacramento? -- What are the active weather alerts in Texas? +1. Open **Copilot Chat** (`Ctrl+Alt+I` / `Ctrl+Cmd+I`). +2. Select **Agent** mode from the mode selector at the top of the chat panel. +3. Click the **Tools** button to confirm `get-alerts` and `get-forecast` appear. +4. Try these prompts: + - "What's the weather in Sacramento?" + - "What are the active weather alerts in Texas?" > [!NOTE] > Since this is the US National Weather Service, the queries will only work for US locations. @@ -447,57 +413,30 @@ If the server has shown up in the "Connectors" menu, you can now test your serve When you ask a question: -1. The client sends your question to Claude -2. Claude analyzes the available tools and decides which one(s) to use +1. The client sends your question to the LLM +2. The LLM analyzes the available tools and decides which one(s) to use 3. The client executes the chosen tool(s) through the MCP server -4. The results are sent back to Claude -5. Claude formulates a natural language response -6. The response is displayed to you! +4. The results are sent back to the LLM +5. The LLM formulates a natural language response +6. The response is displayed to you ## Troubleshooting
-Claude for Desktop integration issues - -**Getting logs from Claude for Desktop** - -Claude.app logging related to MCP is written to log files in `~/Library/Logs/Claude`: +VS Code integration issues -- `mcp.log` will contain general logging about MCP connections and connection failures. -- Files named `mcp-server-SERVERNAME.log` will contain error (stderr) logging from the named server. +**Server not appearing or fails to start** -You can run the following command to list recent logs and follow along with any new ones: +1. Verify you have VS Code 1.99 or later (`Help > About`) and that GitHub Copilot is installed. +2. Verify the server builds without errors: run `npm run build` in the `weather` directory. +3. Test it manually: run `node build/index.js` — the process should start and wait for input. Press `Ctrl+C` to exit. +4. Check the server logs: in **MCP: List Servers**, select the server and choose **Show Output**. +5. If the `node` command is not found, use the full path to the Node binary. -```bash -# Check Claude's logs for errors -tail -n 20 -f ~/Library/Logs/Claude/mcp*.log -``` - -**Server not showing up in Claude** - -1. Check your `claude_desktop_config.json` file syntax -2. Make sure the path to your project is absolute and not relative -3. Restart Claude for Desktop completely - -> [!WARNING] -> To properly restart Claude for Desktop, you must fully quit the application: -> -> - **Windows**: Right-click the Claude icon in the system tray (which may be hidden in the "hidden icons" menu) and select "Quit" or "Exit". -> - **macOS**: Use Cmd+Q or select "Quit Claude" from the menu bar. -> -> Simply closing the window does not fully quit the application, and your MCP server configuration changes will not take effect. - -**Tool calls failing silently** +**Tools don't appear in Copilot Chat** -If Claude attempts to use the tools but they fail: - -1. Check Claude's logs for errors -2. Verify your server builds and runs without errors -3. Try restarting Claude for Desktop - -**None of this is working. What do I do?** - -Please refer to our [debugging guide](https://modelcontextprotocol.io/legacy/tools/debugging) for better debugging tools and more detailed guidance. +1. Confirm you're in **Agent** mode (not Ask or Edit mode). +2. Run **MCP: Reset Cached Tools** from the Command Palette, then recheck the **Tools** list.
@@ -524,9 +463,6 @@ This isn't an error - it just means there are no current weather alerts for that -> [!NOTE] -> For more advanced troubleshooting, check out our guide on [Debugging MCP](https://modelcontextprotocol.io/legacy/tools/debugging). - ## Next steps Now that your server is running locally, here are some ways to go further: