You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: 03-GettingStarted/README.md
+389-1Lines changed: 389 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,4 +6,392 @@ This section consists of several lessons:
6
6
7
7
-**Client with LLM**, an even better way of writing a client is by adding an LLM to it so it can "negotiate" with your server on what to do, [to the lesson](/03-GettingStarted/03-llm-client/README.md)
8
8
9
-
-**Consuming a server GitHub Copilot Agent mode in Visual Studio Code**. Here, we're looking at running our MCP Server from within Visual Studio Code, [to the lesson](/03-GettingStarted/04-vscode/README.md)
9
+
-**Consuming a server GitHub Copilot Agent mode in Visual Studio Code**. Here, we're looking at running our MCP Server from within Visual Studio Code, [to the lesson](/03-GettingStarted/04-vscode/README.md)
10
+
11
+
The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications - it provides a standardized way to connect AI models to different data sources and tools.
12
+
13
+
## Learning Objectives
14
+
15
+
By the end of this lesson, you will be able to:
16
+
17
+
- Set up development environments for MCP in C#, Java, Python, TypeScript, and JavaScript
18
+
- Build and deploy basic MCP servers with custom features (resources, prompts, and tools)
19
+
- Create host applications that connect to MCP servers
20
+
- Test and debug MCP implementations
21
+
- Understand common setup challenges and their solutions
22
+
- Connect your MCP implementations to popular LLM services
23
+
24
+
## Setting Up Your MCP Environment
25
+
26
+
Before you begin working with MCP, it's important to prepare your development environment and understand the basic workflow. This section will guide you through the initial setup steps to ensure a smooth start with MCP.
27
+
28
+
### Prerequisites
29
+
30
+
Before diving into MCP development, ensure you have:
31
+
32
+
-**Development Environment**: For your chosen language (C#, Java, Python, TypeScript, or JavaScript)
33
+
-**IDE/Editor**: Visual Studio, Visual Studio Code, IntelliJ, Eclipse, PyCharm, or any modern code editor
34
+
-**Package Managers**: NuGet, Maven/Gradle, pip, or npm/yarn
35
+
-**API Keys**: For any AI services you plan to use in your host applications
36
+
37
+
## To set up an MCP Client and MCP Server in Visual Studio Code, follow these steps:
38
+
39
+
Getting started with MCP in Visual Studio Code is a straightforward process that enables rapid prototyping and testing of AI-powered tools. By following the steps below, you'll set up both an MCP client and server, allowing you to explore the protocol's capabilities in a hands-on way. Let's walk through the essential setup process.
40
+
41
+
1.**Install Required Dependencies**:
42
+
43
+
- Ensure you have Python (version 3.12.9 or later) and Node.js (version 22.14.0 or later) installed on your machine.
Visual Studio Code integrates MCP with GitHub Copilot through [agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode), allowing direct interaction with MCP-provided tools within your agentic coding workflow. Configure servers in Claude Desktop, workspace or user settings, with guided MCP installation and secure handling of keys in input variables to avoid leaking hard-coded keys.
114
+
115
+
**Key Features:**
116
+
- Support for stdio and server-sent events (SSE) transport
117
+
- Per-session selection of tools per agent session for optimal performance
118
+
- Easy server debugging with restart commands and output logging
119
+
- Tool calls with editable inputs and always-allow toggle
120
+
- Integration with existing Visual Studio Code extension system to register MCP servers from extensions
121
+
122
+
#### Command-line configuration
123
+
124
+
You can also use the Visual Studio Code command-line interface to add an MCP server to your user profile or to a workspace.
125
+
126
+
To add an MCP server to your user profile, use the --add-mcp command line option, and provide the JSON server configuration in the form {\"name\":\"server-name\",\"command\":...}.
- **Server Configuration**: Setup port, authentication, and other settings
195
+
- **Resources**: Data and context made available to LLMs
196
+
- **Tools**: Functionality that models can invoke
197
+
- **Prompts**: Templates for generating or structuring text
198
+
199
+
Here's a simplified example in TypeScript:
200
+
201
+
```typescript
202
+
import { Server, Tool, Resource } from "@modelcontextprotocol/typescript-server-sdk";
203
+
204
+
// Create a new MCP server
205
+
const server = new Server({
206
+
port: 3000,
207
+
name: "Example MCP Server",
208
+
version: "1.0.0"
209
+
});
210
+
211
+
// Register a tool
212
+
server.registerTool({
213
+
name: "calculator",
214
+
description: "Performs basic calculations",
215
+
parameters: {
216
+
expression: {
217
+
type: "string",
218
+
description: "The math expression to evaluate"
219
+
}
220
+
},
221
+
handler: async (params) => {
222
+
const result = eval(params.expression);
223
+
return { result };
224
+
}
225
+
});
226
+
227
+
// Start the server
228
+
server.start();
229
+
```
230
+
231
+
In the preceding code we:
232
+
233
+
- Import the necessary classes from the MCP TypeScript SDK.
234
+
- Create and configure a new MCP server instance.
235
+
- Register a custom tool (`calculator`) with a handler function.
236
+
- Start the server to listen for incoming MCP requests.
237
+
238
+
## Testing and Debugging
239
+
240
+
Before you begin testing your MCP server, it's important to understand the available tools and best practices for debugging. Effective testing ensures your server behaves as expected and helps you quickly identify and resolve issues. The following section outlines recommended approaches for validating your MCP implementation.
241
+
242
+
### Testing MCP Servers
243
+
244
+
MCP provides tools to help you test and debug your servers:
245
+
246
+
#### Using MCP Inspector
247
+
248
+
The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a visual testing tool that helps you:
249
+
250
+
1. **Discover Server Capabilities**: Automatically detect available resources, tools, and prompts
251
+
2. **Test Tool Execution**: Try different parameters and see responses in real-time
252
+
3. **View Server Metadata**: Examine server info, schemas, and configurations
253
+
254
+
```bash
255
+
# Installing MCP Inspector
256
+
npm install -g @modelcontextprotocol/inspector
257
+
258
+
# Running the Inspector
259
+
mcp-inspector
260
+
```
261
+
262
+
When you run the above commands, the MCP Inspector will launch a local web interface in your browser. You can expect to see a dashboard displaying your registered MCP servers, their available tools, resources, and prompts. The interface allows you to interactively test tool execution, inspect server metadata, and view real-time responses, making it easier to validate and debug your MCP server implementations.
263
+
264
+
#### Manual Testing
265
+
266
+
You can test MCP servers directly using HTTP requests:
267
+
268
+
```bash
269
+
# Example: Test server metadata
270
+
curl http://localhost:3000/v1/metadata
271
+
272
+
# Example: Execute a tool
273
+
curl -X POST http://localhost:3000/v1/tools/execute \
| Authentication failures | Verify API keys and permissions |
297
+
| Schema validation errors | Ensure parameters match the defined schema |
298
+
| Server not starting | Check for port conflicts or missing dependencies |
299
+
| CORS errors | Configure proper CORS headers for cross-origin requests |
300
+
| Authentication issues | Verify token validity and permissions |
301
+
302
+
## Deploying MCP Servers
303
+
304
+
Deploying your MCP server allows others to access its tools and resources beyond your local environment. There are several deployment strategies to consider, depending on your requirements forscalability, reliability, and ease of management. Below you'll find guidance for deploying MCP servers locally,in containers, and to the cloud.
305
+
306
+
### Local Development
307
+
308
+
For local development and testing, you can run MCP servers directly on your machine:
309
+
310
+
1. **Start the server process**: Run your MCP server application
311
+
2. **Configure networking**: Ensure the server is accessible on the expected port
312
+
3. **Connect clients**: Use local connection URLs like `http://localhost:3000`
313
+
314
+
```bash
315
+
# Example: Running a TypeScript MCP server locally
316
+
npm run start
317
+
# Server running at http://localhost:3000
318
+
```
319
+
320
+
### Container Deployment
321
+
322
+
For production deployments, containerization offers several advantages:
323
+
324
+
1. **Create a Dockerfile**:
325
+
326
+
```dockerfile
327
+
FROM node:18
328
+
WORKDIR /app
329
+
COPY package*.json ./
330
+
RUN npm install
331
+
COPY ..
332
+
EXPOSE 3000
333
+
CMD ["npm", "start"]
334
+
```
335
+
336
+
2. **Build and run the container**:
337
+
338
+
```bash
339
+
# Build the container
340
+
docker build -t my-mcp-server .
341
+
342
+
# Run the container
343
+
docker run -p 3000:3000 my-mcp-server
344
+
```
345
+
346
+
### Cloud Deployment
347
+
348
+
MCP servers can be deployed to various cloud platforms:
349
+
350
+
1. **Serverless Functions**: Deploy lightweight MCP servers as serverless functions
351
+
2. **Container Services**: Use services like Azure Container Apps, AWS ECS, or Google Cloud Run
352
+
3. **Kubernetes**: Deploy and manage MCP servers in Kubernetes clusters for high availability
353
+
354
+
```bash
355
+
# Example: Deploying to Azure Container Apps
356
+
az containerapp create \
357
+
--name my-mcp-server \
358
+
--resource-group my-resources \
359
+
--image my-registry/my-mcp-server:latest \
360
+
--target-port 3000 \
361
+
--ingress external
362
+
```
363
+
364
+
365
+
## Key Takeaways
366
+
367
+
- Setting up an MCP development environment is straightforward with language-specific SDKs
368
+
- Building MCP servers involves creating and registering tools with clear schemas
369
+
- MCP clients connect to servers and models to leverage extended capabilities
370
+
- Testing and debugging are essential for reliable MCP implementations
371
+
- Deployment options range from local development to cloud-based solutions
0 commit comments