This is page 2 of 2. Use http://codebase.md/mryanmyn/task-manager-mcp?lines=true&page={x} to view the full context.
# Directory Structure
```
├── app
│ ├── __init__.py
│ ├── api
│ │ ├── __init__.py
│ │ ├── api.py
│ │ └── cli.py
│ ├── core
│ │ ├── __init__.py
│ │ ├── plan_manager.py
│ │ └── task_manager.py
│ └── ui
│ ├── __init__.py
│ ├── input_handler.py
│ ├── terminal_ui.py
│ └── ui_components.py
├── img.png
├── main.py
├── mcp_guidelines
│ ├── __init__.py
│ └── llms_full.txt
├── mcp_server_fixed.py
├── MCP-README.md
├── pyproject.toml
├── README.md
├── setup.py
└── tests
├── __init__.py
└── test_mcp_server.py
```
# Files
--------------------------------------------------------------------------------
/mcp_guidelines/llms_full.txt:
--------------------------------------------------------------------------------
```
1 | # Example Clients
2 | Source: https://modelcontextprotocol.io/clients
3 |
4 | A list of applications that support MCP integrations
5 |
6 | This page provides an overview of applications that support the Model Context Protocol (MCP). Each client may support different MCP features, allowing for varying levels of integration with MCP servers.
7 |
8 | ## Feature support matrix
9 |
10 | | Client | [Resources] | [Prompts] | [Tools] | [Sampling] | Roots | Notes |
11 | | ------------------------------------ | ----------- | --------- | ------- | ---------- | ----- | ------------------------------------------------------------------------------------------------- |
12 | | [Claude Desktop App][Claude] | ✅ | ✅ | ✅ | ❌ | ❌ | Full support for all MCP features |
13 | | [Claude Code][Claude Code] | ❌ | ✅ | ✅ | ❌ | ✅ | Supports prompts, tools, and roots |
14 | | [5ire][5ire] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. |
15 | | [BeeAI Framework][BeeAI Framework] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools in agentic workflows. |
16 | | [Cline][Cline] | ✅ | ❌ | ✅ | ❌ | ❌ | Supports tools and resources. |
17 | | [Continue][Continue] | ✅ | ✅ | ✅ | ❌ | ❌ | Full support for all MCP features |
18 | | [Copilot-MCP][CopilotMCP] | ✅ | ❌ | ✅ | ❌ | ❌ | Supports tools and resources. |
19 | | [Cursor][Cursor] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. |
20 | | [Emacs Mcp][Mcp.el] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools in Emacs. |
21 | | [fast-agent][fast-agent] | ✅ | ✅ | ✅ | ✅ | ✅ | Full multimodal MCP support, with end-to-end tests |
22 | | [Genkit][Genkit] | ⚠️ | ✅ | ✅ | ❌ | ❌ | Supports resource list and lookup through tools. |
23 | | [GenAIScript][GenAIScript] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. |
24 | | [Goose][Goose] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools. |
25 | | [LibreChat][LibreChat] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools for Agents |
26 | | [mcp-agent][mcp-agent] | ❌ | ❌ | ✅ | ⚠️ | ❌ | Supports tools, server connection management, and agent workflows. |
27 | | [Microsoft Copilot Studio] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools |
28 | | [oterm][oterm] | ❌ | ✅ | ✅ | ❌ | ❌ | Supports tools and prompts. |
29 | | [Roo Code][Roo Code] | ✅ | ❌ | ✅ | ❌ | ❌ | Supports tools and resources. |
30 | | [Sourcegraph Cody][Cody] | ✅ | ❌ | ❌ | ❌ | ❌ | Supports resources through OpenCTX |
31 | | [Superinterface][Superinterface] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools |
32 | | [TheiaAI/TheiaIDE][TheiaAI/TheiaIDE] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools for Agents in Theia AI and the AI-powered Theia IDE |
33 | | [VS Code GitHub Copilot][VS Code] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools, roots, dynamic discovery, secure secret configuration, and one-click installation |
34 | | [Windsurf Editor][Windsurf] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools with AI Flow for collaborative development. |
35 | | [Witsy][Witsy] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools in Witsy. |
36 | | [Zed][Zed] | ❌ | ✅ | ❌ | ❌ | ❌ | Prompts appear as slash commands |
37 | | [SpinAI][SpinAI] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools for Typescript AI Agents |
38 | | [OpenSumi][OpenSumi] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools in OpenSumi |
39 | | [Daydreams Agents][Daydreams] | ✅ | ✅ | ✅ | ❌ | ❌ | Support for drop in Servers to Daydreams agents |
40 | | [Apify MCP Tester][Apify MCP Tester] | ❌ | ❌ | ✅ | ❌ | ❌ | Supports tools |
41 |
42 | [Claude]: https://claude.ai/download
43 |
44 | [Claude Code]: https://claude.ai/code
45 |
46 | [Cursor]: https://cursor.com
47 |
48 | [Zed]: https://zed.dev
49 |
50 | [Cody]: https://sourcegraph.com/cody
51 |
52 | [Genkit]: https://github.com/firebase/genkit
53 |
54 | [Continue]: https://github.com/continuedev/continue
55 |
56 | [GenAIScript]: https://microsoft.github.io/genaiscript/reference/scripts/mcp-tools/
57 |
58 | [Cline]: https://github.com/cline/cline
59 |
60 | [LibreChat]: https://github.com/danny-avila/LibreChat
61 |
62 | [TheiaAI/TheiaIDE]: https://eclipsesource.com/blogs/2024/12/19/theia-ide-and-theia-ai-support-mcp/
63 |
64 | [Superinterface]: https://superinterface.ai
65 |
66 | [5ire]: https://github.com/nanbingxyz/5ire
67 |
68 | [Apify MCP Tester]: https://apify.com/jiri.spilka/tester-mcp-client
69 |
70 | [BeeAI Framework]: https://i-am-bee.github.io/beeai-framework
71 |
72 | [fast-agent]: https://github.com/evalstate/fast-agent
73 |
74 | [mcp-agent]: https://github.com/lastmile-ai/mcp-agent
75 |
76 | [Mcp.el]: https://github.com/lizqwerscott/mcp.el
77 |
78 | [Roo Code]: https://roocode.com
79 |
80 | [Goose]: https://block.github.io/goose/docs/goose-architecture/#interoperability-with-extensions
81 |
82 | [Witsy]: https://github.com/nbonamy/witsy
83 |
84 | [Windsurf]: https://codeium.com/windsurf
85 |
86 | [CopilotMCP]: https://github.com/VikashLoomba/copilot-mcp
87 |
88 | [Daydreams]: https://github.com/daydreamsai/daydreams
89 |
90 | [SpinAI]: https://spinai.dev
91 |
92 | [OpenSumi]: https://github.com/opensumi/core
93 |
94 | [oterm]: https://github.com/ggozad/oterm
95 |
96 | [Resources]: https://modelcontextprotocol.io/docs/concepts/resources
97 |
98 | [Prompts]: https://modelcontextprotocol.io/docs/concepts/prompts
99 |
100 | [Tools]: https://modelcontextprotocol.io/docs/concepts/tools
101 |
102 | [Sampling]: https://modelcontextprotocol.io/docs/concepts/sampling
103 |
104 | [Microsoft Copilot Studio]: https://learn.microsoft.com/en-us/microsoft-copilot-studio/agent-extend-action-mcp
105 |
106 | [VS Code]: https://code.visualstudio.com/
107 |
108 | ## Client details
109 |
110 | ### Claude Desktop App
111 |
112 | The Claude desktop application provides comprehensive support for MCP, enabling deep integration with local tools and data sources.
113 |
114 | **Key features:**
115 |
116 | * Full support for resources, allowing attachment of local files and data
117 | * Support for prompt templates
118 | * Tool integration for executing commands and scripts
119 | * Local server connections for enhanced privacy and security
120 |
121 | > ⓘ Note: The Claude.ai web application does not currently support MCP. MCP features are only available in the desktop application.
122 |
123 | ### Claude Code
124 |
125 | Claude Code is an interactive agentic coding tool from Anthropic that helps you code faster through natural language commands. It supports MCP integration for prompts and tools, and also functions as an MCP server to integrate with other clients.
126 |
127 | **Key features:**
128 |
129 | * Tool and prompt support for MCP servers
130 | * Offers its own tools through an MCP server for integrating with other MCP clients
131 |
132 | ### 5ire
133 |
134 | [5ire](https://github.com/nanbingxyz/5ire) is an open source cross-platform desktop AI assistant that supports tools through MCP servers.
135 |
136 | **Key features:**
137 |
138 | * Built-in MCP servers can be quickly enabled and disabled.
139 | * Users can add more servers by modifying the configuration file.
140 | * It is open-source and user-friendly, suitable for beginners.
141 | * Future support for MCP will be continuously improved.
142 |
143 | ### BeeAI Framework
144 |
145 | [BeeAI Framework](https://i-am-bee.github.io/beeai-framework) is an open-source framework for building, deploying, and serving powerful agentic workflows at scale. The framework includes the **MCP Tool**, a native feature that simplifies the integration of MCP servers into agentic workflows.
146 |
147 | **Key features:**
148 |
149 | * Seamlessly incorporate MCP tools into agentic workflows.
150 | * Quickly instantiate framework-native tools from connected MCP client(s).
151 | * Planned future support for agentic MCP capabilities.
152 |
153 | **Learn more:**
154 |
155 | * [Example of using MCP tools in agentic workflow](https://i-am-bee.github.io/beeai-framework/#/typescript/tools?id=using-the-mcptool-class)
156 |
157 | ### Cline
158 |
159 | [Cline](https://github.com/cline/cline) is an autonomous coding agent in VS Code that edits files, runs commands, uses a browser, and more–with your permission at each step.
160 |
161 | **Key features:**
162 |
163 | * Create and add tools through natural language (e.g. "add a tool that searches the web")
164 | * Share custom MCP servers Cline creates with others via the `~/Documents/Cline/MCP` directory
165 | * Displays configured MCP servers along with their tools, resources, and any error logs
166 |
167 | ### Continue
168 |
169 | [Continue](https://github.com/continuedev/continue) is an open-source AI code assistant, with built-in support for all MCP features.
170 |
171 | **Key features**
172 |
173 | * Type "@" to mention MCP resources
174 | * Prompt templates surface as slash commands
175 | * Use both built-in and MCP tools directly in chat
176 | * Supports VS Code and JetBrains IDEs, with any LLM
177 |
178 | ### Cursor
179 |
180 | [Cursor](https://docs.cursor.com/advanced/model-context-protocol) is an AI code editor.
181 |
182 | **Key Features**:
183 |
184 | * Support for MCP tools in Cursor Composer
185 | * Support for both STDIO and SSE
186 |
187 | ### Emacs Mcp
188 |
189 | [Emacs Mcp](https://github.com/lizqwerscott/mcp.el) is an Emacs client designed to interface with MCP servers, enabling seamless connections and interactions. It provides MCP tool invocation support for AI plugins like [gptel](https://github.com/karthink/gptel) and [llm](https://github.com/ahyatt/llm), adhering to Emacs' standard tool invocation format. This integration enhances the functionality of AI tools within the Emacs ecosystem.
190 |
191 | **Key features:**
192 |
193 | * Provides MCP tool support for Emacs.
194 |
195 | ### fast-agent
196 |
197 | [fast-agent](https://github.com/evalstate/fast-agent) is a Python Agent framework, with simple declarative support for creating Agents and Workflows, with full multi-modal support for Anthropic and OpenAI models.
198 |
199 | **Key features:**
200 |
201 | * PDF and Image support, based on MCP Native types
202 | * Interactive front-end to develop and diagnose Agent applications, including passthrough and playback simulators
203 | * Built in support for "Building Effective Agents" workflows.
204 | * Deploy Agents as MCP Servers
205 |
206 | ### Genkit
207 |
208 | [Genkit](https://github.com/firebase/genkit) is a cross-language SDK for building and integrating GenAI features into applications. The [genkitx-mcp](https://github.com/firebase/genkit/tree/main/js/plugins/mcp) plugin enables consuming MCP servers as a client or creating MCP servers from Genkit tools and prompts.
209 |
210 | **Key features:**
211 |
212 | * Client support for tools and prompts (resources partially supported)
213 | * Rich discovery with support in Genkit's Dev UI playground
214 | * Seamless interoperability with Genkit's existing tools and prompts
215 | * Works across a wide variety of GenAI models from top providers
216 |
217 | ### GenAIScript
218 |
219 | Programmatically assemble prompts for LLMs using [GenAIScript](https://microsoft.github.io/genaiscript/) (in JavaScript). Orchestrate LLMs, tools, and data in JavaScript.
220 |
221 | **Key features:**
222 |
223 | * JavaScript toolbox to work with prompts
224 | * Abstraction to make it easy and productive
225 | * Seamless Visual Studio Code integration
226 |
227 | ### Goose
228 |
229 | [Goose](https://github.com/block/goose) is an open source AI agent that supercharges your software development by automating coding tasks.
230 |
231 | **Key features:**
232 |
233 | * Expose MCP functionality to Goose through tools.
234 | * MCPs can be installed directly via the [extensions directory](https://block.github.io/goose/v1/extensions/), CLI, or UI.
235 | * Goose allows you to extend its functionality by [building your own MCP servers](https://block.github.io/goose/docs/tutorials/custom-extensions).
236 | * Includes built-in tools for development, web scraping, automation, memory, and integrations with JetBrains and Google Drive.
237 |
238 | ### LibreChat
239 |
240 | [LibreChat](https://github.com/danny-avila/LibreChat) is an open-source, customizable AI chat UI that supports multiple AI providers, now including MCP integration.
241 |
242 | **Key features:**
243 |
244 | * Extend current tool ecosystem, including [Code Interpreter](https://www.librechat.ai/docs/features/code_interpreter) and Image generation tools, through MCP servers
245 | * Add tools to customizable [Agents](https://www.librechat.ai/docs/features/agents), using a variety of LLMs from top providers
246 | * Open-source and self-hostable, with secure multi-user support
247 | * Future roadmap includes expanded MCP feature support
248 |
249 | ### mcp-agent
250 |
251 | [mcp-agent] is a simple, composable framework to build agents using Model Context Protocol.
252 |
253 | **Key features:**
254 |
255 | * Automatic connection management of MCP servers.
256 | * Expose tools from multiple servers to an LLM.
257 | * Implements every pattern defined in [Building Effective Agents](https://www.anthropic.com/research/building-effective-agents).
258 | * Supports workflow pause/resume signals, such as waiting for human feedback.
259 |
260 | ### Microsoft Copilot Studio
261 |
262 | [Microsoft Copilot Studio] is a robust SaaS platform designed for building custom AI-driven applications and intelligent agents, empowering developers to create, deploy, and manage sophisticated AI solutions.
263 |
264 | **Key features:**
265 |
266 | * Support for MCP tools
267 | * Extend Copilot Studio agents with MCP servers
268 | * Leveraging Microsoft unified, governed, and secure API management solutions
269 |
270 | ### oterm
271 |
272 | [oterm] is a terminal client for Ollama allowing users to create chats/agents.
273 |
274 | **Key features:**
275 |
276 | * Support for multiple fully customizable chat sessions with Ollama connected with tools.
277 | * Support for MCP tools.
278 |
279 | ### Roo Code
280 |
281 | [Roo Code](https://roocode.com) enables AI coding assistance via MCP.
282 |
283 | **Key features:**
284 |
285 | * Support for MCP tools and resources
286 | * Integration with development workflows
287 | * Extensible AI capabilities
288 |
289 | ### Sourcegraph Cody
290 |
291 | [Cody](https://openctx.org/docs/providers/modelcontextprotocol) is Sourcegraph's AI coding assistant, which implements MCP through OpenCTX.
292 |
293 | **Key features:**
294 |
295 | * Support for MCP resources
296 | * Integration with Sourcegraph's code intelligence
297 | * Uses OpenCTX as an abstraction layer
298 | * Future support planned for additional MCP features
299 |
300 | ### SpinAI
301 |
302 | [SpinAI](https://spinai.dev) is an open-source TypeScript framework for building observable AI agents. The framework provides native MCP compatibility, allowing agents to seamlessly integrate with MCP servers and tools.
303 |
304 | **Key features:**
305 |
306 | * Built-in MCP compatibility for AI agents
307 | * Open-source TypeScript framework
308 | * Observable agent architecture
309 | * Native support for MCP tools integration
310 |
311 | ### Superinterface
312 |
313 | [Superinterface](https://superinterface.ai) is AI infrastructure and a developer platform to build in-app AI assistants with support for MCP, interactive components, client-side function calling and more.
314 |
315 | **Key features:**
316 |
317 | * Use tools from MCP servers in assistants embedded via React components or script tags
318 | * SSE transport support
319 | * Use any AI model from any AI provider (OpenAI, Anthropic, Ollama, others)
320 |
321 | ### TheiaAI/TheiaIDE
322 |
323 | [Theia AI](https://eclipsesource.com/blogs/2024/10/07/introducing-theia-ai/) is a framework for building AI-enhanced tools and IDEs. The [AI-powered Theia IDE](https://eclipsesource.com/blogs/2024/10/08/introducting-ai-theia-ide/) is an open and flexible development environment built on Theia AI.
324 |
325 | **Key features:**
326 |
327 | * **Tool Integration**: Theia AI enables AI agents, including those in the Theia IDE, to utilize MCP servers for seamless tool interaction.
328 | * **Customizable Prompts**: The Theia IDE allows users to define and adapt prompts, dynamically integrating MCP servers for tailored workflows.
329 | * **Custom agents**: The Theia IDE supports creating custom agents that leverage MCP capabilities, enabling users to design dedicated workflows on the fly.
330 |
331 | Theia AI and Theia IDE's MCP integration provide users with flexibility, making them powerful platforms for exploring and adapting MCP.
332 |
333 | **Learn more:**
334 |
335 | * [Theia IDE and Theia AI MCP Announcement](https://eclipsesource.com/blogs/2024/12/19/theia-ide-and-theia-ai-support-mcp/)
336 | * [Download the AI-powered Theia IDE](https://theia-ide.org/)
337 |
338 | ### VS Code GitHub Copilot
339 |
340 | [VS Code](https://code.visualstudio.com/) 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.
341 |
342 | **Key features:**
343 |
344 | * Support for stdio and server-sent events (SSE) transport
345 | * Per-session selection of tools per agent session for optimal performance
346 | * Easy server debugging with restart commands and output logging
347 | * Tool calls with editable inputs and always-allow toggle
348 | * Integration with existing VS Code extension system to register MCP servers from extensions
349 |
350 | ### Windsurf Editor
351 |
352 | [Windsurf Editor](https://codeium.com/windsurf) is an agentic IDE that combines AI assistance with developer workflows. It features an innovative AI Flow system that enables both collaborative and independent AI interactions while maintaining developer control.
353 |
354 | **Key features:**
355 |
356 | * Revolutionary AI Flow paradigm for human-AI collaboration
357 | * Intelligent code generation and understanding
358 | * Rich development tools with multi-model support
359 |
360 | ### Witsy
361 |
362 | [Witsy](https://github.com/nbonamy/witsy) is an AI desktop assistant, supoorting Anthropic models and MCP servers as LLM tools.
363 |
364 | **Key features:**
365 |
366 | * Multiple MCP servers support
367 | * Tool integration for executing commands and scripts
368 | * Local server connections for enhanced privacy and security
369 | * Easy-install from Smithery.ai
370 | * Open-source, available for macOS, Windows and Linux
371 |
372 | ### Zed
373 |
374 | [Zed](https://zed.dev/docs/assistant/model-context-protocol) is a high-performance code editor with built-in MCP support, focusing on prompt templates and tool integration.
375 |
376 | **Key features:**
377 |
378 | * Prompt templates surface as slash commands in the editor
379 | * Tool integration for enhanced coding workflows
380 | * Tight integration with editor features and workspace context
381 | * Does not support MCP resources
382 |
383 | ### OpenSumi
384 |
385 | [OpenSumi](https://github.com/opensumi/core) is a framework helps you quickly build AI Native IDE products.
386 |
387 | **Key features:**
388 |
389 | * Supports MCP tools in OpenSumi
390 | * Supports built-in IDE MCP servers and custom MCP servers
391 |
392 | ### Daydreams
393 |
394 | [Daydreams](https://github.com/daydreamsai/daydreams) is a generative agent framework for executing anything onchain
395 |
396 | **Key features:**
397 |
398 | * Supports MCP Servers in config
399 | * Exposes MCP Client
400 |
401 | ### Apify MCP Tester
402 |
403 | [Apify MCP Tester](https://github.com/apify/tester-mcp-client) is an open-source client that connects to any MCP server using Server-Sent Events (SSE).
404 | It is a standalone Apify Actor designed for testing MCP servers over SSE, with support for Authorization headers.
405 | It uses plain JavaScript (old-school style) and is hosted on Apify, allowing you to run it without any setup.
406 |
407 | **Key features:**
408 |
409 | * Connects to any MCP server via SSE.
410 | * Works with the [Apify MCP Server](https://apify.com/apify/actors-mcp-server) to interact with one or more Apify [Actors](https://apify.com/store).
411 | * Dynamically utilizes tools based on context and user queries (if supported by the server).
412 |
413 | ## Adding MCP support to your application
414 |
415 | If you've added MCP support to your application, we encourage you to submit a pull request to add it to this list. MCP integration can provide your users with powerful contextual AI capabilities and make your application part of the growing MCP ecosystem.
416 |
417 | Benefits of adding MCP support:
418 |
419 | * Enable users to bring their own context and tools
420 | * Join a growing ecosystem of interoperable AI applications
421 | * Provide users with flexible integration options
422 | * Support local-first AI workflows
423 |
424 | To get started with implementing MCP in your application, check out our [Python](https://github.com/modelcontextprotocol/python-sdk) or [TypeScript SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
425 |
426 | ## Updates and corrections
427 |
428 | This list is maintained by the community. If you notice any inaccuracies or would like to update information about MCP support in your application, please submit a pull request or [open an issue in our documentation repository](https://github.com/modelcontextprotocol/docs/issues).
429 |
430 |
431 | # Contributing
432 | Source: https://modelcontextprotocol.io/development/contributing
433 |
434 | How to participate in Model Context Protocol development
435 |
436 | We welcome contributions from the community! Please review our [contributing guidelines](https://github.com/modelcontextprotocol/.github/blob/main/CONTRIBUTING.md) for details on how to submit changes.
437 |
438 | All contributors must adhere to our [Code of Conduct](https://github.com/modelcontextprotocol/.github/blob/main/CODE_OF_CONDUCT.md).
439 |
440 | For questions and discussions, please use [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions).
441 |
442 |
443 | # Roadmap
444 | Source: https://modelcontextprotocol.io/development/roadmap
445 |
446 | Our plans for evolving Model Context Protocol
447 |
448 | <Info>Last updated: **2025-03-27**</Info>
449 |
450 | The Model Context Protocol is rapidly evolving. This page outlines our current thinking on key priorities and direction for approximately **the next six months**, though these may change significantly as the project develops. To see what's changed recently, check out the **[specification changelog](https://spec.modelcontextprotocol.io/specification/2025-03-26/changelog/)**.
451 |
452 | <Note>The ideas presented here are not commitments—we may solve these challenges differently than described, or some may not materialize at all. This is also not an *exhaustive* list; we may incorporate work that isn't mentioned here.</Note>
453 |
454 | We value community participation! Each section links to relevant discussions where you can learn more and contribute your thoughts.
455 |
456 | For a technical view of our standardization process, visit the [Standards Track](https://github.com/orgs/modelcontextprotocol/projects/2/views/2) on GitHub, which tracks how proposals progress toward inclusion in the official [MCP specification](https://spec.modelcontextprotocol.io).
457 |
458 | ## Validation
459 |
460 | To foster a robust developer ecosystem, we plan to invest in:
461 |
462 | * **Reference Client Implementations**: demonstrating protocol features with high-quality AI applications
463 | * **Compliance Test Suites**: automated verification that clients, servers, and SDKs properly implement the specification
464 |
465 | These tools will help developers confidently implement MCP while ensuring consistent behavior across the ecosystem.
466 |
467 | ## Registry
468 |
469 | For MCP to reach its full potential, we need streamlined ways to distribute and discover MCP servers.
470 |
471 | We plan to develop an [**MCP Registry**](https://github.com/orgs/modelcontextprotocol/discussions/159) that will enable centralized server discovery and metadata. This registry will primarily function as an API layer that third-party marketplaces and discovery services can build upon.
472 |
473 | ## Agents
474 |
475 | As MCP increasingly becomes part of agentic workflows, we're exploring [improvements](https://github.com/modelcontextprotocol/specification/discussions/111) such as:
476 |
477 | * **[Agent Graphs](https://github.com/modelcontextprotocol/specification/discussions/94)**: enabling complex agent topologies through namespacing and graph-aware communication patterns
478 | * **Interactive Workflows**: improving human-in-the-loop experiences with granular permissioning, standardized interaction patterns, and [ways to directly communicate](https://github.com/modelcontextprotocol/specification/issues/97) with the end user
479 |
480 | ## Multimodality
481 |
482 | Supporting the full spectrum of AI capabilities in MCP, including:
483 |
484 | * **Additional Modalities**: video and other media types
485 | * **[Streaming](https://github.com/modelcontextprotocol/specification/issues/117)**: multipart, chunked messages, and bidirectional communication for interactive experiences
486 |
487 | ## Governance
488 |
489 | We're implementing governance structures that prioritize:
490 |
491 | * **Community-Led Development**: fostering a collaborative ecosystem where community members and AI developers can all participate in MCP's evolution, ensuring it serves diverse applications and use cases
492 | * **Transparent Standardization**: establishing clear processes for contributing to the specification, while exploring formal standardization via industry bodies
493 |
494 | ## Get Involved
495 |
496 | We welcome your contributions to MCP's future! Join our [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions) to share ideas, provide feedback, or participate in the development process.
497 |
498 |
499 | # What's New
500 | Source: https://modelcontextprotocol.io/development/updates
501 |
502 | The latest updates and improvements to MCP
503 |
504 | <Update label="2025-03-26" description="Kotlin SDK 0.4.0 released">
505 | * Fix issues and cleanup API
506 | * Added binary compatibility tracking to avoid breaking changes
507 | * Drop jdk requirements to JDK8
508 | * Added Claude Desktop integration with sample
509 | * The full changelog can be found here: [https://github.com/modelcontextprotocol/kotlin-sdk/releases/tag/0.4.0](https://github.com/modelcontextprotocol/kotlin-sdk/releases/tag/0.4.0)
510 | </Update>
511 |
512 | <Update label="2025-03-26" description="Java SDK 0.8.1 released">
513 | * Version [0.8.1](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.8.1) of the MCP Java SDK has been released,
514 | providing important bug fixes.
515 | </Update>
516 |
517 | <Update label="2025-03-24" description="C# SDK released">
518 | * We are exited to announce the availability of the MCP
519 | [C# SDK](https://github.com/modelcontextprotocol/csharp-sdk/) developed by
520 | [Peder Holdgaard Pedersen](http://github.com/PederHP) and Microsoft. This joins our growing
521 | list of supported languages. The C# SDK is also available as
522 | [NuGet package](https://www.nuget.org/packages/ModelContextProtocol)
523 | * Python SDK 1.5.0 was released with multiple fixes and improvements.
524 | </Update>
525 |
526 | <Update label="2025-03-21" description="Java SDK 0.8.0 released">
527 | * Version [0.8.0](https://github.com/modelcontextprotocol/java-sdk/releases/tag/v0.8.0) of the MCP Java SDK has been released,
528 | delivering important session management improvements and bug fixes.
529 | </Update>
530 |
531 | <Update label="2025-03-10" description="Typescript SDK release">
532 | * Typescript SDK 1.7.0 was released with multiple fixes and improvements.
533 | </Update>
534 |
535 | <Update label="2025-02-14" description="Java SDK released">
536 | * We're excited to announce that the Java SDK developed by Spring AI at VMware Tanzu is now
537 | the official [Java SDK](https://github.com/modelcontextprotocol/java-sdk) for MCP.
538 | This joins our existing Kotlin SDK in our growing list of supported languages.
539 | The Spring AI team will maintain the SDK as an integral part of the Model Context Protocol
540 | organization. We're thrilled to welcome them to the MCP community!
541 | </Update>
542 |
543 | <Update label="2025-01-27" description="Python SDK 1.2.1">
544 | * Version [1.2.1](https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.2.1) of the MCP Python SDK has been released,
545 | delivering important stability improvements and bug fixes.
546 | </Update>
547 |
548 | <Update label="2025-01-18" description="SDK and Server Improvements">
549 | * Simplified, express-like API in the [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
550 | * Added 8 new clients to the [clients page](https://modelcontextprotocol.io/clients)
551 | </Update>
552 |
553 | <Update label="2025-01-03" description="SDK and Server Improvements">
554 | * FastMCP API in the [Python SDK](https://github.com/modelcontextprotocol/python-sdk)
555 | * Dockerized MCP servers in the [servers repo](https://github.com/modelcontextprotocol/servers)
556 | </Update>
557 |
558 | <Update label="2024-12-21" description="Kotlin SDK released">
559 | * Jetbrains released a Kotlin SDK for MCP!
560 | * For a sample MCP Kotlin server, check out [this repository](https://github.com/modelcontextprotocol/kotlin-sdk/tree/main/samples/kotlin-mcp-server)
561 | </Update>
562 |
563 |
564 | # Core architecture
565 | Source: https://modelcontextprotocol.io/docs/concepts/architecture
566 |
567 | Understand how MCP connects clients, servers, and LLMs
568 |
569 | The Model Context Protocol (MCP) is built on a flexible, extensible architecture that enables seamless communication between LLM applications and integrations. This document covers the core architectural components and concepts.
570 |
571 | ## Overview
572 |
573 | MCP follows a client-server architecture where:
574 |
575 | * **Hosts** are LLM applications (like Claude Desktop or IDEs) that initiate connections
576 | * **Clients** maintain 1:1 connections with servers, inside the host application
577 | * **Servers** provide context, tools, and prompts to clients
578 |
579 | ```mermaid
580 | flowchart LR
581 | subgraph "Host"
582 | client1[MCP Client]
583 | client2[MCP Client]
584 | end
585 | subgraph "Server Process"
586 | server1[MCP Server]
587 | end
588 | subgraph "Server Process"
589 | server2[MCP Server]
590 | end
591 |
592 | client1 <-->|Transport Layer| server1
593 | client2 <-->|Transport Layer| server2
594 | ```
595 |
596 | ## Core components
597 |
598 | ### Protocol layer
599 |
600 | The protocol layer handles message framing, request/response linking, and high-level communication patterns.
601 |
602 | <Tabs>
603 | <Tab title="TypeScript">
604 | ```typescript
605 | class Protocol<Request, Notification, Result> {
606 | // Handle incoming requests
607 | setRequestHandler<T>(schema: T, handler: (request: T, extra: RequestHandlerExtra) => Promise<Result>): void
608 |
609 | // Handle incoming notifications
610 | setNotificationHandler<T>(schema: T, handler: (notification: T) => Promise<void>): void
611 |
612 | // Send requests and await responses
613 | request<T>(request: Request, schema: T, options?: RequestOptions): Promise<T>
614 |
615 | // Send one-way notifications
616 | notification(notification: Notification): Promise<void>
617 | }
618 | ```
619 | </Tab>
620 |
621 | <Tab title="Python">
622 | ```python
623 | class Session(BaseSession[RequestT, NotificationT, ResultT]):
624 | async def send_request(
625 | self,
626 | request: RequestT,
627 | result_type: type[Result]
628 | ) -> Result:
629 | """
630 | Send request and wait for response. Raises McpError if response contains error.
631 | """
632 | # Request handling implementation
633 |
634 | async def send_notification(
635 | self,
636 | notification: NotificationT
637 | ) -> None:
638 | """Send one-way notification that doesn't expect response."""
639 | # Notification handling implementation
640 |
641 | async def _received_request(
642 | self,
643 | responder: RequestResponder[ReceiveRequestT, ResultT]
644 | ) -> None:
645 | """Handle incoming request from other side."""
646 | # Request handling implementation
647 |
648 | async def _received_notification(
649 | self,
650 | notification: ReceiveNotificationT
651 | ) -> None:
652 | """Handle incoming notification from other side."""
653 | # Notification handling implementation
654 | ```
655 | </Tab>
656 | </Tabs>
657 |
658 | Key classes include:
659 |
660 | * `Protocol`
661 | * `Client`
662 | * `Server`
663 |
664 | ### Transport layer
665 |
666 | The transport layer handles the actual communication between clients and servers. MCP supports multiple transport mechanisms:
667 |
668 | 1. **Stdio transport**
669 | * Uses standard input/output for communication
670 | * Ideal for local processes
671 |
672 | 2. **HTTP with SSE transport**
673 | * Uses Server-Sent Events for server-to-client messages
674 | * HTTP POST for client-to-server messages
675 |
676 | All transports use [JSON-RPC](https://www.jsonrpc.org/) 2.0 to exchange messages. See the [specification](https://spec.modelcontextprotocol.io) for detailed information about the Model Context Protocol message format.
677 |
678 | ### Message types
679 |
680 | MCP has these main types of messages:
681 |
682 | 1. **Requests** expect a response from the other side:
683 | ```typescript
684 | interface Request {
685 | method: string;
686 | params?: { ... };
687 | }
688 | ```
689 |
690 | 2. **Results** are successful responses to requests:
691 | ```typescript
692 | interface Result {
693 | [key: string]: unknown;
694 | }
695 | ```
696 |
697 | 3. **Errors** indicate that a request failed:
698 | ```typescript
699 | interface Error {
700 | code: number;
701 | message: string;
702 | data?: unknown;
703 | }
704 | ```
705 |
706 | 4. **Notifications** are one-way messages that don't expect a response:
707 | ```typescript
708 | interface Notification {
709 | method: string;
710 | params?: { ... };
711 | }
712 | ```
713 |
714 | ## Connection lifecycle
715 |
716 | ### 1. Initialization
717 |
718 | ```mermaid
719 | sequenceDiagram
720 | participant Client
721 | participant Server
722 |
723 | Client->>Server: initialize request
724 | Server->>Client: initialize response
725 | Client->>Server: initialized notification
726 |
727 | Note over Client,Server: Connection ready for use
728 | ```
729 |
730 | 1. Client sends `initialize` request with protocol version and capabilities
731 | 2. Server responds with its protocol version and capabilities
732 | 3. Client sends `initialized` notification as acknowledgment
733 | 4. Normal message exchange begins
734 |
735 | ### 2. Message exchange
736 |
737 | After initialization, the following patterns are supported:
738 |
739 | * **Request-Response**: Client or server sends requests, the other responds
740 | * **Notifications**: Either party sends one-way messages
741 |
742 | ### 3. Termination
743 |
744 | Either party can terminate the connection:
745 |
746 | * Clean shutdown via `close()`
747 | * Transport disconnection
748 | * Error conditions
749 |
750 | ## Error handling
751 |
752 | MCP defines these standard error codes:
753 |
754 | ```typescript
755 | enum ErrorCode {
756 | // Standard JSON-RPC error codes
757 | ParseError = -32700,
758 | InvalidRequest = -32600,
759 | MethodNotFound = -32601,
760 | InvalidParams = -32602,
761 | InternalError = -32603
762 | }
763 | ```
764 |
765 | SDKs and applications can define their own error codes above -32000.
766 |
767 | Errors are propagated through:
768 |
769 | * Error responses to requests
770 | * Error events on transports
771 | * Protocol-level error handlers
772 |
773 | ## Implementation example
774 |
775 | Here's a basic example of implementing an MCP server:
776 |
777 | <Tabs>
778 | <Tab title="TypeScript">
779 | ```typescript
780 | import { Server } from "@modelcontextprotocol/sdk/server/index.js";
781 | import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
782 |
783 | const server = new Server({
784 | name: "example-server",
785 | version: "1.0.0"
786 | }, {
787 | capabilities: {
788 | resources: {}
789 | }
790 | });
791 |
792 | // Handle requests
793 | server.setRequestHandler(ListResourcesRequestSchema, async () => {
794 | return {
795 | resources: [
796 | {
797 | uri: "example://resource",
798 | name: "Example Resource"
799 | }
800 | ]
801 | };
802 | });
803 |
804 | // Connect transport
805 | const transport = new StdioServerTransport();
806 | await server.connect(transport);
807 | ```
808 | </Tab>
809 |
810 | <Tab title="Python">
811 | ```python
812 | import asyncio
813 | import mcp.types as types
814 | from mcp.server import Server
815 | from mcp.server.stdio import stdio_server
816 |
817 | app = Server("example-server")
818 |
819 | @app.list_resources()
820 | async def list_resources() -> list[types.Resource]:
821 | return [
822 | types.Resource(
823 | uri="example://resource",
824 | name="Example Resource"
825 | )
826 | ]
827 |
828 | async def main():
829 | async with stdio_server() as streams:
830 | await app.run(
831 | streams[0],
832 | streams[1],
833 | app.create_initialization_options()
834 | )
835 |
836 | if __name__ == "__main__":
837 | asyncio.run(main())
838 | ```
839 | </Tab>
840 | </Tabs>
841 |
842 | ## Best practices
843 |
844 | ### Transport selection
845 |
846 | 1. **Local communication**
847 | * Use stdio transport for local processes
848 | * Efficient for same-machine communication
849 | * Simple process management
850 |
851 | 2. **Remote communication**
852 | * Use SSE for scenarios requiring HTTP compatibility
853 | * Consider security implications including authentication and authorization
854 |
855 | ### Message handling
856 |
857 | 1. **Request processing**
858 | * Validate inputs thoroughly
859 | * Use type-safe schemas
860 | * Handle errors gracefully
861 | * Implement timeouts
862 |
863 | 2. **Progress reporting**
864 | * Use progress tokens for long operations
865 | * Report progress incrementally
866 | * Include total progress when known
867 |
868 | 3. **Error management**
869 | * Use appropriate error codes
870 | * Include helpful error messages
871 | * Clean up resources on errors
872 |
873 | ## Security considerations
874 |
875 | 1. **Transport security**
876 | * Use TLS for remote connections
877 | * Validate connection origins
878 | * Implement authentication when needed
879 |
880 | 2. **Message validation**
881 | * Validate all incoming messages
882 | * Sanitize inputs
883 | * Check message size limits
884 | * Verify JSON-RPC format
885 |
886 | 3. **Resource protection**
887 | * Implement access controls
888 | * Validate resource paths
889 | * Monitor resource usage
890 | * Rate limit requests
891 |
892 | 4. **Error handling**
893 | * Don't leak sensitive information
894 | * Log security-relevant errors
895 | * Implement proper cleanup
896 | * Handle DoS scenarios
897 |
898 | ## Debugging and monitoring
899 |
900 | 1. **Logging**
901 | * Log protocol events
902 | * Track message flow
903 | * Monitor performance
904 | * Record errors
905 |
906 | 2. **Diagnostics**
907 | * Implement health checks
908 | * Monitor connection state
909 | * Track resource usage
910 | * Profile performance
911 |
912 | 3. **Testing**
913 | * Test different transports
914 | * Verify error handling
915 | * Check edge cases
916 | * Load test servers
917 |
918 |
919 | # Prompts
920 | Source: https://modelcontextprotocol.io/docs/concepts/prompts
921 |
922 | Create reusable prompt templates and workflows
923 |
924 | Prompts enable servers to define reusable prompt templates and workflows that clients can easily surface to users and LLMs. They provide a powerful way to standardize and share common LLM interactions.
925 |
926 | <Note>
927 | Prompts are designed to be **user-controlled**, meaning they are exposed from servers to clients with the intention of the user being able to explicitly select them for use.
928 | </Note>
929 |
930 | ## Overview
931 |
932 | Prompts in MCP are predefined templates that can:
933 |
934 | * Accept dynamic arguments
935 | * Include context from resources
936 | * Chain multiple interactions
937 | * Guide specific workflows
938 | * Surface as UI elements (like slash commands)
939 |
940 | ## Prompt structure
941 |
942 | Each prompt is defined with:
943 |
944 | ```typescript
945 | {
946 | name: string; // Unique identifier for the prompt
947 | description?: string; // Human-readable description
948 | arguments?: [ // Optional list of arguments
949 | {
950 | name: string; // Argument identifier
951 | description?: string; // Argument description
952 | required?: boolean; // Whether argument is required
953 | }
954 | ]
955 | }
956 | ```
957 |
958 | ## Discovering prompts
959 |
960 | Clients can discover available prompts through the `prompts/list` endpoint:
961 |
962 | ```typescript
963 | // Request
964 | {
965 | method: "prompts/list"
966 | }
967 |
968 | // Response
969 | {
970 | prompts: [
971 | {
972 | name: "analyze-code",
973 | description: "Analyze code for potential improvements",
974 | arguments: [
975 | {
976 | name: "language",
977 | description: "Programming language",
978 | required: true
979 | }
980 | ]
981 | }
982 | ]
983 | }
984 | ```
985 |
986 | ## Using prompts
987 |
988 | To use a prompt, clients make a `prompts/get` request:
989 |
990 | ````typescript
991 | // Request
992 | {
993 | method: "prompts/get",
994 | params: {
995 | name: "analyze-code",
996 | arguments: {
997 | language: "python"
998 | }
999 | }
1000 | }
1001 |
1002 | // Response
1003 | {
1004 | description: "Analyze Python code for potential improvements",
1005 | messages: [
1006 | {
1007 | role: "user",
1008 | content: {
1009 | type: "text",
1010 | text: "Please analyze the following Python code for potential improvements:\n\n```python\ndef calculate_sum(numbers):\n total = 0\n for num in numbers:\n total = total + num\n return total\n\nresult = calculate_sum([1, 2, 3, 4, 5])\nprint(result)\n```"
1011 | }
1012 | }
1013 | ]
1014 | }
1015 | ````
1016 |
1017 | ## Dynamic prompts
1018 |
1019 | Prompts can be dynamic and include:
1020 |
1021 | ### Embedded resource context
1022 |
1023 | ```json
1024 | {
1025 | "name": "analyze-project",
1026 | "description": "Analyze project logs and code",
1027 | "arguments": [
1028 | {
1029 | "name": "timeframe",
1030 | "description": "Time period to analyze logs",
1031 | "required": true
1032 | },
1033 | {
1034 | "name": "fileUri",
1035 | "description": "URI of code file to review",
1036 | "required": true
1037 | }
1038 | ]
1039 | }
1040 | ```
1041 |
1042 | When handling the `prompts/get` request:
1043 |
1044 | ```json
1045 | {
1046 | "messages": [
1047 | {
1048 | "role": "user",
1049 | "content": {
1050 | "type": "text",
1051 | "text": "Analyze these system logs and the code file for any issues:"
1052 | }
1053 | },
1054 | {
1055 | "role": "user",
1056 | "content": {
1057 | "type": "resource",
1058 | "resource": {
1059 | "uri": "logs://recent?timeframe=1h",
1060 | "text": "[2024-03-14 15:32:11] ERROR: Connection timeout in network.py:127\n[2024-03-14 15:32:15] WARN: Retrying connection (attempt 2/3)\n[2024-03-14 15:32:20] ERROR: Max retries exceeded",
1061 | "mimeType": "text/plain"
1062 | }
1063 | }
1064 | },
1065 | {
1066 | "role": "user",
1067 | "content": {
1068 | "type": "resource",
1069 | "resource": {
1070 | "uri": "file:///path/to/code.py",
1071 | "text": "def connect_to_service(timeout=30):\n retries = 3\n for attempt in range(retries):\n try:\n return establish_connection(timeout)\n except TimeoutError:\n if attempt == retries - 1:\n raise\n time.sleep(5)\n\ndef establish_connection(timeout):\n # Connection implementation\n pass",
1072 | "mimeType": "text/x-python"
1073 | }
1074 | }
1075 | }
1076 | ]
1077 | }
1078 | ```
1079 |
1080 | ### Multi-step workflows
1081 |
1082 | ```typescript
1083 | const debugWorkflow = {
1084 | name: "debug-error",
1085 | async getMessages(error: string) {
1086 | return [
1087 | {
1088 | role: "user",
1089 | content: {
1090 | type: "text",
1091 | text: `Here's an error I'm seeing: ${error}`
1092 | }
1093 | },
1094 | {
1095 | role: "assistant",
1096 | content: {
1097 | type: "text",
1098 | text: "I'll help analyze this error. What have you tried so far?"
1099 | }
1100 | },
1101 | {
1102 | role: "user",
1103 | content: {
1104 | type: "text",
1105 | text: "I've tried restarting the service, but the error persists."
1106 | }
1107 | }
1108 | ];
1109 | }
1110 | };
1111 | ```
1112 |
1113 | ## Example implementation
1114 |
1115 | Here's a complete example of implementing prompts in an MCP server:
1116 |
1117 | <Tabs>
1118 | <Tab title="TypeScript">
1119 | ```typescript
1120 | import { Server } from "@modelcontextprotocol/sdk/server";
1121 | import {
1122 | ListPromptsRequestSchema,
1123 | GetPromptRequestSchema
1124 | } from "@modelcontextprotocol/sdk/types";
1125 |
1126 | const PROMPTS = {
1127 | "git-commit": {
1128 | name: "git-commit",
1129 | description: "Generate a Git commit message",
1130 | arguments: [
1131 | {
1132 | name: "changes",
1133 | description: "Git diff or description of changes",
1134 | required: true
1135 | }
1136 | ]
1137 | },
1138 | "explain-code": {
1139 | name: "explain-code",
1140 | description: "Explain how code works",
1141 | arguments: [
1142 | {
1143 | name: "code",
1144 | description: "Code to explain",
1145 | required: true
1146 | },
1147 | {
1148 | name: "language",
1149 | description: "Programming language",
1150 | required: false
1151 | }
1152 | ]
1153 | }
1154 | };
1155 |
1156 | const server = new Server({
1157 | name: "example-prompts-server",
1158 | version: "1.0.0"
1159 | }, {
1160 | capabilities: {
1161 | prompts: {}
1162 | }
1163 | });
1164 |
1165 | // List available prompts
1166 | server.setRequestHandler(ListPromptsRequestSchema, async () => {
1167 | return {
1168 | prompts: Object.values(PROMPTS)
1169 | };
1170 | });
1171 |
1172 | // Get specific prompt
1173 | server.setRequestHandler(GetPromptRequestSchema, async (request) => {
1174 | const prompt = PROMPTS[request.params.name];
1175 | if (!prompt) {
1176 | throw new Error(`Prompt not found: ${request.params.name}`);
1177 | }
1178 |
1179 | if (request.params.name === "git-commit") {
1180 | return {
1181 | messages: [
1182 | {
1183 | role: "user",
1184 | content: {
1185 | type: "text",
1186 | text: `Generate a concise but descriptive commit message for these changes:\n\n${request.params.arguments?.changes}`
1187 | }
1188 | }
1189 | ]
1190 | };
1191 | }
1192 |
1193 | if (request.params.name === "explain-code") {
1194 | const language = request.params.arguments?.language || "Unknown";
1195 | return {
1196 | messages: [
1197 | {
1198 | role: "user",
1199 | content: {
1200 | type: "text",
1201 | text: `Explain how this ${language} code works:\n\n${request.params.arguments?.code}`
1202 | }
1203 | }
1204 | ]
1205 | };
1206 | }
1207 |
1208 | throw new Error("Prompt implementation not found");
1209 | });
1210 | ```
1211 | </Tab>
1212 |
1213 | <Tab title="Python">
1214 | ```python
1215 | from mcp.server import Server
1216 | import mcp.types as types
1217 |
1218 | # Define available prompts
1219 | PROMPTS = {
1220 | "git-commit": types.Prompt(
1221 | name="git-commit",
1222 | description="Generate a Git commit message",
1223 | arguments=[
1224 | types.PromptArgument(
1225 | name="changes",
1226 | description="Git diff or description of changes",
1227 | required=True
1228 | )
1229 | ],
1230 | ),
1231 | "explain-code": types.Prompt(
1232 | name="explain-code",
1233 | description="Explain how code works",
1234 | arguments=[
1235 | types.PromptArgument(
1236 | name="code",
1237 | description="Code to explain",
1238 | required=True
1239 | ),
1240 | types.PromptArgument(
1241 | name="language",
1242 | description="Programming language",
1243 | required=False
1244 | )
1245 | ],
1246 | )
1247 | }
1248 |
1249 | # Initialize server
1250 | app = Server("example-prompts-server")
1251 |
1252 | @app.list_prompts()
1253 | async def list_prompts() -> list[types.Prompt]:
1254 | return list(PROMPTS.values())
1255 |
1256 | @app.get_prompt()
1257 | async def get_prompt(
1258 | name: str, arguments: dict[str, str] | None = None
1259 | ) -> types.GetPromptResult:
1260 | if name not in PROMPTS:
1261 | raise ValueError(f"Prompt not found: {name}")
1262 |
1263 | if name == "git-commit":
1264 | changes = arguments.get("changes") if arguments else ""
1265 | return types.GetPromptResult(
1266 | messages=[
1267 | types.PromptMessage(
1268 | role="user",
1269 | content=types.TextContent(
1270 | type="text",
1271 | text=f"Generate a concise but descriptive commit message "
1272 | f"for these changes:\n\n{changes}"
1273 | )
1274 | )
1275 | ]
1276 | )
1277 |
1278 | if name == "explain-code":
1279 | code = arguments.get("code") if arguments else ""
1280 | language = arguments.get("language", "Unknown") if arguments else "Unknown"
1281 | return types.GetPromptResult(
1282 | messages=[
1283 | types.PromptMessage(
1284 | role="user",
1285 | content=types.TextContent(
1286 | type="text",
1287 | text=f"Explain how this {language} code works:\n\n{code}"
1288 | )
1289 | )
1290 | ]
1291 | )
1292 |
1293 | raise ValueError("Prompt implementation not found")
1294 | ```
1295 | </Tab>
1296 | </Tabs>
1297 |
1298 | ## Best practices
1299 |
1300 | When implementing prompts:
1301 |
1302 | 1. Use clear, descriptive prompt names
1303 | 2. Provide detailed descriptions for prompts and arguments
1304 | 3. Validate all required arguments
1305 | 4. Handle missing arguments gracefully
1306 | 5. Consider versioning for prompt templates
1307 | 6. Cache dynamic content when appropriate
1308 | 7. Implement error handling
1309 | 8. Document expected argument formats
1310 | 9. Consider prompt composability
1311 | 10. Test prompts with various inputs
1312 |
1313 | ## UI integration
1314 |
1315 | Prompts can be surfaced in client UIs as:
1316 |
1317 | * Slash commands
1318 | * Quick actions
1319 | * Context menu items
1320 | * Command palette entries
1321 | * Guided workflows
1322 | * Interactive forms
1323 |
1324 | ## Updates and changes
1325 |
1326 | Servers can notify clients about prompt changes:
1327 |
1328 | 1. Server capability: `prompts.listChanged`
1329 | 2. Notification: `notifications/prompts/list_changed`
1330 | 3. Client re-fetches prompt list
1331 |
1332 | ## Security considerations
1333 |
1334 | When implementing prompts:
1335 |
1336 | * Validate all arguments
1337 | * Sanitize user input
1338 | * Consider rate limiting
1339 | * Implement access controls
1340 | * Audit prompt usage
1341 | * Handle sensitive data appropriately
1342 | * Validate generated content
1343 | * Implement timeouts
1344 | * Consider prompt injection risks
1345 | * Document security requirements
1346 |
1347 |
1348 | # Resources
1349 | Source: https://modelcontextprotocol.io/docs/concepts/resources
1350 |
1351 | Expose data and content from your servers to LLMs
1352 |
1353 | Resources are a core primitive in the Model Context Protocol (MCP) that allow servers to expose data and content that can be read by clients and used as context for LLM interactions.
1354 |
1355 | <Note>
1356 | Resources are designed to be **application-controlled**, meaning that the client application can decide how and when they should be used.
1357 | Different MCP clients may handle resources differently. For example:
1358 |
1359 | * Claude Desktop currently requires users to explicitly select resources before they can be used
1360 | * Other clients might automatically select resources based on heuristics
1361 | * Some implementations may even allow the AI model itself to determine which resources to use
1362 |
1363 | Server authors should be prepared to handle any of these interaction patterns when implementing resource support. In order to expose data to models automatically, server authors should use a **model-controlled** primitive such as [Tools](./tools).
1364 | </Note>
1365 |
1366 | ## Overview
1367 |
1368 | Resources represent any kind of data that an MCP server wants to make available to clients. This can include:
1369 |
1370 | * File contents
1371 | * Database records
1372 | * API responses
1373 | * Live system data
1374 | * Screenshots and images
1375 | * Log files
1376 | * And more
1377 |
1378 | Each resource is identified by a unique URI and can contain either text or binary data.
1379 |
1380 | ## Resource URIs
1381 |
1382 | Resources are identified using URIs that follow this format:
1383 |
1384 | ```
1385 | [protocol]://[host]/[path]
1386 | ```
1387 |
1388 | For example:
1389 |
1390 | * `file:///home/user/documents/report.pdf`
1391 | * `postgres://database/customers/schema`
1392 | * `screen://localhost/display1`
1393 |
1394 | The protocol and path structure is defined by the MCP server implementation. Servers can define their own custom URI schemes.
1395 |
1396 | ## Resource types
1397 |
1398 | Resources can contain two types of content:
1399 |
1400 | ### Text resources
1401 |
1402 | Text resources contain UTF-8 encoded text data. These are suitable for:
1403 |
1404 | * Source code
1405 | * Configuration files
1406 | * Log files
1407 | * JSON/XML data
1408 | * Plain text
1409 |
1410 | ### Binary resources
1411 |
1412 | Binary resources contain raw binary data encoded in base64. These are suitable for:
1413 |
1414 | * Images
1415 | * PDFs
1416 | * Audio files
1417 | * Video files
1418 | * Other non-text formats
1419 |
1420 | ## Resource discovery
1421 |
1422 | Clients can discover available resources through two main methods:
1423 |
1424 | ### Direct resources
1425 |
1426 | Servers expose a list of concrete resources via the `resources/list` endpoint. Each resource includes:
1427 |
1428 | ```typescript
1429 | {
1430 | uri: string; // Unique identifier for the resource
1431 | name: string; // Human-readable name
1432 | description?: string; // Optional description
1433 | mimeType?: string; // Optional MIME type
1434 | }
1435 | ```
1436 |
1437 | ### Resource templates
1438 |
1439 | For dynamic resources, servers can expose [URI templates](https://datatracker.ietf.org/doc/html/rfc6570) that clients can use to construct valid resource URIs:
1440 |
1441 | ```typescript
1442 | {
1443 | uriTemplate: string; // URI template following RFC 6570
1444 | name: string; // Human-readable name for this type
1445 | description?: string; // Optional description
1446 | mimeType?: string; // Optional MIME type for all matching resources
1447 | }
1448 | ```
1449 |
1450 | ## Reading resources
1451 |
1452 | To read a resource, clients make a `resources/read` request with the resource URI.
1453 |
1454 | The server responds with a list of resource contents:
1455 |
1456 | ```typescript
1457 | {
1458 | contents: [
1459 | {
1460 | uri: string; // The URI of the resource
1461 | mimeType?: string; // Optional MIME type
1462 |
1463 | // One of:
1464 | text?: string; // For text resources
1465 | blob?: string; // For binary resources (base64 encoded)
1466 | }
1467 | ]
1468 | }
1469 | ```
1470 |
1471 | <Tip>
1472 | Servers may return multiple resources in response to one `resources/read` request. This could be used, for example, to return a list of files inside a directory when the directory is read.
1473 | </Tip>
1474 |
1475 | ## Resource updates
1476 |
1477 | MCP supports real-time updates for resources through two mechanisms:
1478 |
1479 | ### List changes
1480 |
1481 | Servers can notify clients when their list of available resources changes via the `notifications/resources/list_changed` notification.
1482 |
1483 | ### Content changes
1484 |
1485 | Clients can subscribe to updates for specific resources:
1486 |
1487 | 1. Client sends `resources/subscribe` with resource URI
1488 | 2. Server sends `notifications/resources/updated` when the resource changes
1489 | 3. Client can fetch latest content with `resources/read`
1490 | 4. Client can unsubscribe with `resources/unsubscribe`
1491 |
1492 | ## Example implementation
1493 |
1494 | Here's a simple example of implementing resource support in an MCP server:
1495 |
1496 | <Tabs>
1497 | <Tab title="TypeScript">
1498 | ```typescript
1499 | const server = new Server({
1500 | name: "example-server",
1501 | version: "1.0.0"
1502 | }, {
1503 | capabilities: {
1504 | resources: {}
1505 | }
1506 | });
1507 |
1508 | // List available resources
1509 | server.setRequestHandler(ListResourcesRequestSchema, async () => {
1510 | return {
1511 | resources: [
1512 | {
1513 | uri: "file:///logs/app.log",
1514 | name: "Application Logs",
1515 | mimeType: "text/plain"
1516 | }
1517 | ]
1518 | };
1519 | });
1520 |
1521 | // Read resource contents
1522 | server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
1523 | const uri = request.params.uri;
1524 |
1525 | if (uri === "file:///logs/app.log") {
1526 | const logContents = await readLogFile();
1527 | return {
1528 | contents: [
1529 | {
1530 | uri,
1531 | mimeType: "text/plain",
1532 | text: logContents
1533 | }
1534 | ]
1535 | };
1536 | }
1537 |
1538 | throw new Error("Resource not found");
1539 | });
1540 | ```
1541 | </Tab>
1542 |
1543 | <Tab title="Python">
1544 | ```python
1545 | app = Server("example-server")
1546 |
1547 | @app.list_resources()
1548 | async def list_resources() -> list[types.Resource]:
1549 | return [
1550 | types.Resource(
1551 | uri="file:///logs/app.log",
1552 | name="Application Logs",
1553 | mimeType="text/plain"
1554 | )
1555 | ]
1556 |
1557 | @app.read_resource()
1558 | async def read_resource(uri: AnyUrl) -> str:
1559 | if str(uri) == "file:///logs/app.log":
1560 | log_contents = await read_log_file()
1561 | return log_contents
1562 |
1563 | raise ValueError("Resource not found")
1564 |
1565 | # Start server
1566 | async with stdio_server() as streams:
1567 | await app.run(
1568 | streams[0],
1569 | streams[1],
1570 | app.create_initialization_options()
1571 | )
1572 | ```
1573 | </Tab>
1574 | </Tabs>
1575 |
1576 | ## Best practices
1577 |
1578 | When implementing resource support:
1579 |
1580 | 1. Use clear, descriptive resource names and URIs
1581 | 2. Include helpful descriptions to guide LLM understanding
1582 | 3. Set appropriate MIME types when known
1583 | 4. Implement resource templates for dynamic content
1584 | 5. Use subscriptions for frequently changing resources
1585 | 6. Handle errors gracefully with clear error messages
1586 | 7. Consider pagination for large resource lists
1587 | 8. Cache resource contents when appropriate
1588 | 9. Validate URIs before processing
1589 | 10. Document your custom URI schemes
1590 |
1591 | ## Security considerations
1592 |
1593 | When exposing resources:
1594 |
1595 | * Validate all resource URIs
1596 | * Implement appropriate access controls
1597 | * Sanitize file paths to prevent directory traversal
1598 | * Be cautious with binary data handling
1599 | * Consider rate limiting for resource reads
1600 | * Audit resource access
1601 | * Encrypt sensitive data in transit
1602 | * Validate MIME types
1603 | * Implement timeouts for long-running reads
1604 | * Handle resource cleanup appropriately
1605 |
1606 |
1607 | # Roots
1608 | Source: https://modelcontextprotocol.io/docs/concepts/roots
1609 |
1610 | Understanding roots in MCP
1611 |
1612 | Roots are a concept in MCP that define the boundaries where servers can operate. They provide a way for clients to inform servers about relevant resources and their locations.
1613 |
1614 | ## What are Roots?
1615 |
1616 | A root is a URI that a client suggests a server should focus on. When a client connects to a server, it declares which roots the server should work with. While primarily used for filesystem paths, roots can be any valid URI including HTTP URLs.
1617 |
1618 | For example, roots could be:
1619 |
1620 | ```
1621 | file:///home/user/projects/myapp
1622 | https://api.example.com/v1
1623 | ```
1624 |
1625 | ## Why Use Roots?
1626 |
1627 | Roots serve several important purposes:
1628 |
1629 | 1. **Guidance**: They inform servers about relevant resources and locations
1630 | 2. **Clarity**: Roots make it clear which resources are part of your workspace
1631 | 3. **Organization**: Multiple roots let you work with different resources simultaneously
1632 |
1633 | ## How Roots Work
1634 |
1635 | When a client supports roots, it:
1636 |
1637 | 1. Declares the `roots` capability during connection
1638 | 2. Provides a list of suggested roots to the server
1639 | 3. Notifies the server when roots change (if supported)
1640 |
1641 | While roots are informational and not strictly enforcing, servers should:
1642 |
1643 | 1. Respect the provided roots
1644 | 2. Use root URIs to locate and access resources
1645 | 3. Prioritize operations within root boundaries
1646 |
1647 | ## Common Use Cases
1648 |
1649 | Roots are commonly used to define:
1650 |
1651 | * Project directories
1652 | * Repository locations
1653 | * API endpoints
1654 | * Configuration locations
1655 | * Resource boundaries
1656 |
1657 | ## Best Practices
1658 |
1659 | When working with roots:
1660 |
1661 | 1. Only suggest necessary resources
1662 | 2. Use clear, descriptive names for roots
1663 | 3. Monitor root accessibility
1664 | 4. Handle root changes gracefully
1665 |
1666 | ## Example
1667 |
1668 | Here's how a typical MCP client might expose roots:
1669 |
1670 | ```json
1671 | {
1672 | "roots": [
1673 | {
1674 | "uri": "file:///home/user/projects/frontend",
1675 | "name": "Frontend Repository"
1676 | },
1677 | {
1678 | "uri": "https://api.example.com/v1",
1679 | "name": "API Endpoint"
1680 | }
1681 | ]
1682 | }
1683 | ```
1684 |
1685 | This configuration suggests the server focus on both a local repository and an API endpoint while keeping them logically separated.
1686 |
1687 |
1688 | # Sampling
1689 | Source: https://modelcontextprotocol.io/docs/concepts/sampling
1690 |
1691 | Let your servers request completions from LLMs
1692 |
1693 | Sampling is a powerful MCP feature that allows servers to request LLM completions through the client, enabling sophisticated agentic behaviors while maintaining security and privacy.
1694 |
1695 | <Info>
1696 | This feature of MCP is not yet supported in the Claude Desktop client.
1697 | </Info>
1698 |
1699 | ## How sampling works
1700 |
1701 | The sampling flow follows these steps:
1702 |
1703 | 1. Server sends a `sampling/createMessage` request to the client
1704 | 2. Client reviews the request and can modify it
1705 | 3. Client samples from an LLM
1706 | 4. Client reviews the completion
1707 | 5. Client returns the result to the server
1708 |
1709 | This human-in-the-loop design ensures users maintain control over what the LLM sees and generates.
1710 |
1711 | ## Message format
1712 |
1713 | Sampling requests use a standardized message format:
1714 |
1715 | ```typescript
1716 | {
1717 | messages: [
1718 | {
1719 | role: "user" | "assistant",
1720 | content: {
1721 | type: "text" | "image",
1722 |
1723 | // For text:
1724 | text?: string,
1725 |
1726 | // For images:
1727 | data?: string, // base64 encoded
1728 | mimeType?: string
1729 | }
1730 | }
1731 | ],
1732 | modelPreferences?: {
1733 | hints?: [{
1734 | name?: string // Suggested model name/family
1735 | }],
1736 | costPriority?: number, // 0-1, importance of minimizing cost
1737 | speedPriority?: number, // 0-1, importance of low latency
1738 | intelligencePriority?: number // 0-1, importance of capabilities
1739 | },
1740 | systemPrompt?: string,
1741 | includeContext?: "none" | "thisServer" | "allServers",
1742 | temperature?: number,
1743 | maxTokens: number,
1744 | stopSequences?: string[],
1745 | metadata?: Record<string, unknown>
1746 | }
1747 | ```
1748 |
1749 | ## Request parameters
1750 |
1751 | ### Messages
1752 |
1753 | The `messages` array contains the conversation history to send to the LLM. Each message has:
1754 |
1755 | * `role`: Either "user" or "assistant"
1756 | * `content`: The message content, which can be:
1757 | * Text content with a `text` field
1758 | * Image content with `data` (base64) and `mimeType` fields
1759 |
1760 | ### Model preferences
1761 |
1762 | The `modelPreferences` object allows servers to specify their model selection preferences:
1763 |
1764 | * `hints`: Array of model name suggestions that clients can use to select an appropriate model:
1765 | * `name`: String that can match full or partial model names (e.g. "claude-3", "sonnet")
1766 | * Clients may map hints to equivalent models from different providers
1767 | * Multiple hints are evaluated in preference order
1768 |
1769 | * Priority values (0-1 normalized):
1770 | * `costPriority`: Importance of minimizing costs
1771 | * `speedPriority`: Importance of low latency response
1772 | * `intelligencePriority`: Importance of advanced model capabilities
1773 |
1774 | Clients make the final model selection based on these preferences and their available models.
1775 |
1776 | ### System prompt
1777 |
1778 | An optional `systemPrompt` field allows servers to request a specific system prompt. The client may modify or ignore this.
1779 |
1780 | ### Context inclusion
1781 |
1782 | The `includeContext` parameter specifies what MCP context to include:
1783 |
1784 | * `"none"`: No additional context
1785 | * `"thisServer"`: Include context from the requesting server
1786 | * `"allServers"`: Include context from all connected MCP servers
1787 |
1788 | The client controls what context is actually included.
1789 |
1790 | ### Sampling parameters
1791 |
1792 | Fine-tune the LLM sampling with:
1793 |
1794 | * `temperature`: Controls randomness (0.0 to 1.0)
1795 | * `maxTokens`: Maximum tokens to generate
1796 | * `stopSequences`: Array of sequences that stop generation
1797 | * `metadata`: Additional provider-specific parameters
1798 |
1799 | ## Response format
1800 |
1801 | The client returns a completion result:
1802 |
1803 | ```typescript
1804 | {
1805 | model: string, // Name of the model used
1806 | stopReason?: "endTurn" | "stopSequence" | "maxTokens" | string,
1807 | role: "user" | "assistant",
1808 | content: {
1809 | type: "text" | "image",
1810 | text?: string,
1811 | data?: string,
1812 | mimeType?: string
1813 | }
1814 | }
1815 | ```
1816 |
1817 | ## Example request
1818 |
1819 | Here's an example of requesting sampling from a client:
1820 |
1821 | ```json
1822 | {
1823 | "method": "sampling/createMessage",
1824 | "params": {
1825 | "messages": [
1826 | {
1827 | "role": "user",
1828 | "content": {
1829 | "type": "text",
1830 | "text": "What files are in the current directory?"
1831 | }
1832 | }
1833 | ],
1834 | "systemPrompt": "You are a helpful file system assistant.",
1835 | "includeContext": "thisServer",
1836 | "maxTokens": 100
1837 | }
1838 | }
1839 | ```
1840 |
1841 | ## Best practices
1842 |
1843 | When implementing sampling:
1844 |
1845 | 1. Always provide clear, well-structured prompts
1846 | 2. Handle both text and image content appropriately
1847 | 3. Set reasonable token limits
1848 | 4. Include relevant context through `includeContext`
1849 | 5. Validate responses before using them
1850 | 6. Handle errors gracefully
1851 | 7. Consider rate limiting sampling requests
1852 | 8. Document expected sampling behavior
1853 | 9. Test with various model parameters
1854 | 10. Monitor sampling costs
1855 |
1856 | ## Human in the loop controls
1857 |
1858 | Sampling is designed with human oversight in mind:
1859 |
1860 | ### For prompts
1861 |
1862 | * Clients should show users the proposed prompt
1863 | * Users should be able to modify or reject prompts
1864 | * System prompts can be filtered or modified
1865 | * Context inclusion is controlled by the client
1866 |
1867 | ### For completions
1868 |
1869 | * Clients should show users the completion
1870 | * Users should be able to modify or reject completions
1871 | * Clients can filter or modify completions
1872 | * Users control which model is used
1873 |
1874 | ## Security considerations
1875 |
1876 | When implementing sampling:
1877 |
1878 | * Validate all message content
1879 | * Sanitize sensitive information
1880 | * Implement appropriate rate limits
1881 | * Monitor sampling usage
1882 | * Encrypt data in transit
1883 | * Handle user data privacy
1884 | * Audit sampling requests
1885 | * Control cost exposure
1886 | * Implement timeouts
1887 | * Handle model errors gracefully
1888 |
1889 | ## Common patterns
1890 |
1891 | ### Agentic workflows
1892 |
1893 | Sampling enables agentic patterns like:
1894 |
1895 | * Reading and analyzing resources
1896 | * Making decisions based on context
1897 | * Generating structured data
1898 | * Handling multi-step tasks
1899 | * Providing interactive assistance
1900 |
1901 | ### Context management
1902 |
1903 | Best practices for context:
1904 |
1905 | * Request minimal necessary context
1906 | * Structure context clearly
1907 | * Handle context size limits
1908 | * Update context as needed
1909 | * Clean up stale context
1910 |
1911 | ### Error handling
1912 |
1913 | Robust error handling should:
1914 |
1915 | * Catch sampling failures
1916 | * Handle timeout errors
1917 | * Manage rate limits
1918 | * Validate responses
1919 | * Provide fallback behaviors
1920 | * Log errors appropriately
1921 |
1922 | ## Limitations
1923 |
1924 | Be aware of these limitations:
1925 |
1926 | * Sampling depends on client capabilities
1927 | * Users control sampling behavior
1928 | * Context size has limits
1929 | * Rate limits may apply
1930 | * Costs should be considered
1931 | * Model availability varies
1932 | * Response times vary
1933 | * Not all content types supported
1934 |
1935 |
1936 | # Tools
1937 | Source: https://modelcontextprotocol.io/docs/concepts/tools
1938 |
1939 | Enable LLMs to perform actions through your server
1940 |
1941 | Tools are a powerful primitive in the Model Context Protocol (MCP) that enable servers to expose executable functionality to clients. Through tools, LLMs can interact with external systems, perform computations, and take actions in the real world.
1942 |
1943 | <Note>
1944 | Tools are designed to be **model-controlled**, meaning that tools are exposed from servers to clients with the intention of the AI model being able to automatically invoke them (with a human in the loop to grant approval).
1945 | </Note>
1946 |
1947 | ## Overview
1948 |
1949 | Tools in MCP allow servers to expose executable functions that can be invoked by clients and used by LLMs to perform actions. Key aspects of tools include:
1950 |
1951 | * **Discovery**: Clients can list available tools through the `tools/list` endpoint
1952 | * **Invocation**: Tools are called using the `tools/call` endpoint, where servers perform the requested operation and return results
1953 | * **Flexibility**: Tools can range from simple calculations to complex API interactions
1954 |
1955 | Like [resources](/docs/concepts/resources), tools are identified by unique names and can include descriptions to guide their usage. However, unlike resources, tools represent dynamic operations that can modify state or interact with external systems.
1956 |
1957 | ## Tool definition structure
1958 |
1959 | Each tool is defined with the following structure:
1960 |
1961 | ```typescript
1962 | {
1963 | name: string; // Unique identifier for the tool
1964 | description?: string; // Human-readable description
1965 | inputSchema: { // JSON Schema for the tool's parameters
1966 | type: "object",
1967 | properties: { ... } // Tool-specific parameters
1968 | }
1969 | }
1970 | ```
1971 |
1972 | ## Implementing tools
1973 |
1974 | Here's an example of implementing a basic tool in an MCP server:
1975 |
1976 | <Tabs>
1977 | <Tab title="TypeScript">
1978 | ```typescript
1979 | const server = new Server({
1980 | name: "example-server",
1981 | version: "1.0.0"
1982 | }, {
1983 | capabilities: {
1984 | tools: {}
1985 | }
1986 | });
1987 |
1988 | // Define available tools
1989 | server.setRequestHandler(ListToolsRequestSchema, async () => {
1990 | return {
1991 | tools: [{
1992 | name: "calculate_sum",
1993 | description: "Add two numbers together",
1994 | inputSchema: {
1995 | type: "object",
1996 | properties: {
1997 | a: { type: "number" },
1998 | b: { type: "number" }
1999 | },
2000 | required: ["a", "b"]
2001 | }
2002 | }]
2003 | };
2004 | });
2005 |
2006 | // Handle tool execution
2007 | server.setRequestHandler(CallToolRequestSchema, async (request) => {
2008 | if (request.params.name === "calculate_sum") {
2009 | const { a, b } = request.params.arguments;
2010 | return {
2011 | content: [
2012 | {
2013 | type: "text",
2014 | text: String(a + b)
2015 | }
2016 | ]
2017 | };
2018 | }
2019 | throw new Error("Tool not found");
2020 | });
2021 | ```
2022 | </Tab>
2023 |
2024 | <Tab title="Python">
2025 | ```python
2026 | app = Server("example-server")
2027 |
2028 | @app.list_tools()
2029 | async def list_tools() -> list[types.Tool]:
2030 | return [
2031 | types.Tool(
2032 | name="calculate_sum",
2033 | description="Add two numbers together",
2034 | inputSchema={
2035 | "type": "object",
2036 | "properties": {
2037 | "a": {"type": "number"},
2038 | "b": {"type": "number"}
2039 | },
2040 | "required": ["a", "b"]
2041 | }
2042 | )
2043 | ]
2044 |
2045 | @app.call_tool()
2046 | async def call_tool(
2047 | name: str,
2048 | arguments: dict
2049 | ) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
2050 | if name == "calculate_sum":
2051 | a = arguments["a"]
2052 | b = arguments["b"]
2053 | result = a + b
2054 | return [types.TextContent(type="text", text=str(result))]
2055 | raise ValueError(f"Tool not found: {name}")
2056 | ```
2057 | </Tab>
2058 | </Tabs>
2059 |
2060 | ## Example tool patterns
2061 |
2062 | Here are some examples of types of tools that a server could provide:
2063 |
2064 | ### System operations
2065 |
2066 | Tools that interact with the local system:
2067 |
2068 | ```typescript
2069 | {
2070 | name: "execute_command",
2071 | description: "Run a shell command",
2072 | inputSchema: {
2073 | type: "object",
2074 | properties: {
2075 | command: { type: "string" },
2076 | args: { type: "array", items: { type: "string" } }
2077 | }
2078 | }
2079 | }
2080 | ```
2081 |
2082 | ### API integrations
2083 |
2084 | Tools that wrap external APIs:
2085 |
2086 | ```typescript
2087 | {
2088 | name: "github_create_issue",
2089 | description: "Create a GitHub issue",
2090 | inputSchema: {
2091 | type: "object",
2092 | properties: {
2093 | title: { type: "string" },
2094 | body: { type: "string" },
2095 | labels: { type: "array", items: { type: "string" } }
2096 | }
2097 | }
2098 | }
2099 | ```
2100 |
2101 | ### Data processing
2102 |
2103 | Tools that transform or analyze data:
2104 |
2105 | ```typescript
2106 | {
2107 | name: "analyze_csv",
2108 | description: "Analyze a CSV file",
2109 | inputSchema: {
2110 | type: "object",
2111 | properties: {
2112 | filepath: { type: "string" },
2113 | operations: {
2114 | type: "array",
2115 | items: {
2116 | enum: ["sum", "average", "count"]
2117 | }
2118 | }
2119 | }
2120 | }
2121 | }
2122 | ```
2123 |
2124 | ## Best practices
2125 |
2126 | When implementing tools:
2127 |
2128 | 1. Provide clear, descriptive names and descriptions
2129 | 2. Use detailed JSON Schema definitions for parameters
2130 | 3. Include examples in tool descriptions to demonstrate how the model should use them
2131 | 4. Implement proper error handling and validation
2132 | 5. Use progress reporting for long operations
2133 | 6. Keep tool operations focused and atomic
2134 | 7. Document expected return value structures
2135 | 8. Implement proper timeouts
2136 | 9. Consider rate limiting for resource-intensive operations
2137 | 10. Log tool usage for debugging and monitoring
2138 |
2139 | ## Security considerations
2140 |
2141 | When exposing tools:
2142 |
2143 | ### Input validation
2144 |
2145 | * Validate all parameters against the schema
2146 | * Sanitize file paths and system commands
2147 | * Validate URLs and external identifiers
2148 | * Check parameter sizes and ranges
2149 | * Prevent command injection
2150 |
2151 | ### Access control
2152 |
2153 | * Implement authentication where needed
2154 | * Use appropriate authorization checks
2155 | * Audit tool usage
2156 | * Rate limit requests
2157 | * Monitor for abuse
2158 |
2159 | ### Error handling
2160 |
2161 | * Don't expose internal errors to clients
2162 | * Log security-relevant errors
2163 | * Handle timeouts appropriately
2164 | * Clean up resources after errors
2165 | * Validate return values
2166 |
2167 | ## Tool discovery and updates
2168 |
2169 | MCP supports dynamic tool discovery:
2170 |
2171 | 1. Clients can list available tools at any time
2172 | 2. Servers can notify clients when tools change using `notifications/tools/list_changed`
2173 | 3. Tools can be added or removed during runtime
2174 | 4. Tool definitions can be updated (though this should be done carefully)
2175 |
2176 | ## Error handling
2177 |
2178 | Tool errors should be reported within the result object, not as MCP protocol-level errors. This allows the LLM to see and potentially handle the error. When a tool encounters an error:
2179 |
2180 | 1. Set `isError` to `true` in the result
2181 | 2. Include error details in the `content` array
2182 |
2183 | Here's an example of proper error handling for tools:
2184 |
2185 | <Tabs>
2186 | <Tab title="TypeScript">
2187 | ```typescript
2188 | try {
2189 | // Tool operation
2190 | const result = performOperation();
2191 | return {
2192 | content: [
2193 | {
2194 | type: "text",
2195 | text: `Operation successful: ${result}`
2196 | }
2197 | ]
2198 | };
2199 | } catch (error) {
2200 | return {
2201 | isError: true,
2202 | content: [
2203 | {
2204 | type: "text",
2205 | text: `Error: ${error.message}`
2206 | }
2207 | ]
2208 | };
2209 | }
2210 | ```
2211 | </Tab>
2212 |
2213 | <Tab title="Python">
2214 | ```python
2215 | try:
2216 | # Tool operation
2217 | result = perform_operation()
2218 | return types.CallToolResult(
2219 | content=[
2220 | types.TextContent(
2221 | type="text",
2222 | text=f"Operation successful: {result}"
2223 | )
2224 | ]
2225 | )
2226 | except Exception as error:
2227 | return types.CallToolResult(
2228 | isError=True,
2229 | content=[
2230 | types.TextContent(
2231 | type="text",
2232 | text=f"Error: {str(error)}"
2233 | )
2234 | ]
2235 | )
2236 | ```
2237 | </Tab>
2238 | </Tabs>
2239 |
2240 | This approach allows the LLM to see that an error occurred and potentially take corrective action or request human intervention.
2241 |
2242 | ## Testing tools
2243 |
2244 | A comprehensive testing strategy for MCP tools should cover:
2245 |
2246 | * **Functional testing**: Verify tools execute correctly with valid inputs and handle invalid inputs appropriately
2247 | * **Integration testing**: Test tool interaction with external systems using both real and mocked dependencies
2248 | * **Security testing**: Validate authentication, authorization, input sanitization, and rate limiting
2249 | * **Performance testing**: Check behavior under load, timeout handling, and resource cleanup
2250 | * **Error handling**: Ensure tools properly report errors through the MCP protocol and clean up resources
2251 |
2252 |
2253 | # Transports
2254 | Source: https://modelcontextprotocol.io/docs/concepts/transports
2255 |
2256 | Learn about MCP's communication mechanisms
2257 |
2258 | Transports in the Model Context Protocol (MCP) provide the foundation for communication between clients and servers. A transport handles the underlying mechanics of how messages are sent and received.
2259 |
2260 | ## Message Format
2261 |
2262 | MCP uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 as its wire format. The transport layer is responsible for converting MCP protocol messages into JSON-RPC format for transmission and converting received JSON-RPC messages back into MCP protocol messages.
2263 |
2264 | There are three types of JSON-RPC messages used:
2265 |
2266 | ### Requests
2267 |
2268 | ```typescript
2269 | {
2270 | jsonrpc: "2.0",
2271 | id: number | string,
2272 | method: string,
2273 | params?: object
2274 | }
2275 | ```
2276 |
2277 | ### Responses
2278 |
2279 | ```typescript
2280 | {
2281 | jsonrpc: "2.0",
2282 | id: number | string,
2283 | result?: object,
2284 | error?: {
2285 | code: number,
2286 | message: string,
2287 | data?: unknown
2288 | }
2289 | }
2290 | ```
2291 |
2292 | ### Notifications
2293 |
2294 | ```typescript
2295 | {
2296 | jsonrpc: "2.0",
2297 | method: string,
2298 | params?: object
2299 | }
2300 | ```
2301 |
2302 | ## Built-in Transport Types
2303 |
2304 | MCP includes two standard transport implementations:
2305 |
2306 | ### Standard Input/Output (stdio)
2307 |
2308 | The stdio transport enables communication through standard input and output streams. This is particularly useful for local integrations and command-line tools.
2309 |
2310 | Use stdio when:
2311 |
2312 | * Building command-line tools
2313 | * Implementing local integrations
2314 | * Needing simple process communication
2315 | * Working with shell scripts
2316 |
2317 | <Tabs>
2318 | <Tab title="TypeScript (Server)">
2319 | ```typescript
2320 | const server = new Server({
2321 | name: "example-server",
2322 | version: "1.0.0"
2323 | }, {
2324 | capabilities: {}
2325 | });
2326 |
2327 | const transport = new StdioServerTransport();
2328 | await server.connect(transport);
2329 | ```
2330 | </Tab>
2331 |
2332 | <Tab title="TypeScript (Client)">
2333 | ```typescript
2334 | const client = new Client({
2335 | name: "example-client",
2336 | version: "1.0.0"
2337 | }, {
2338 | capabilities: {}
2339 | });
2340 |
2341 | const transport = new StdioClientTransport({
2342 | command: "./server",
2343 | args: ["--option", "value"]
2344 | });
2345 | await client.connect(transport);
2346 | ```
2347 | </Tab>
2348 |
2349 | <Tab title="Python (Server)">
2350 | ```python
2351 | app = Server("example-server")
2352 |
2353 | async with stdio_server() as streams:
2354 | await app.run(
2355 | streams[0],
2356 | streams[1],
2357 | app.create_initialization_options()
2358 | )
2359 | ```
2360 | </Tab>
2361 |
2362 | <Tab title="Python (Client)">
2363 | ```python
2364 | params = StdioServerParameters(
2365 | command="./server",
2366 | args=["--option", "value"]
2367 | )
2368 |
2369 | async with stdio_client(params) as streams:
2370 | async with ClientSession(streams[0], streams[1]) as session:
2371 | await session.initialize()
2372 | ```
2373 | </Tab>
2374 | </Tabs>
2375 |
2376 | ### Server-Sent Events (SSE)
2377 |
2378 | SSE transport enables server-to-client streaming with HTTP POST requests for client-to-server communication.
2379 |
2380 | Use SSE when:
2381 |
2382 | * Only server-to-client streaming is needed
2383 | * Working with restricted networks
2384 | * Implementing simple updates
2385 |
2386 | <Tabs>
2387 | <Tab title="TypeScript (Server)">
2388 | ```typescript
2389 | import express from "express";
2390 |
2391 | const app = express();
2392 |
2393 | const server = new Server({
2394 | name: "example-server",
2395 | version: "1.0.0"
2396 | }, {
2397 | capabilities: {}
2398 | });
2399 |
2400 | let transport: SSEServerTransport | null = null;
2401 |
2402 | app.get("/sse", (req, res) => {
2403 | transport = new SSEServerTransport("/messages", res);
2404 | server.connect(transport);
2405 | });
2406 |
2407 | app.post("/messages", (req, res) => {
2408 | if (transport) {
2409 | transport.handlePostMessage(req, res);
2410 | }
2411 | });
2412 |
2413 | app.listen(3000);
2414 | ```
2415 | </Tab>
2416 |
2417 | <Tab title="TypeScript (Client)">
2418 | ```typescript
2419 | const client = new Client({
2420 | name: "example-client",
2421 | version: "1.0.0"
2422 | }, {
2423 | capabilities: {}
2424 | });
2425 |
2426 | const transport = new SSEClientTransport(
2427 | new URL("http://localhost:3000/sse")
2428 | );
2429 | await client.connect(transport);
2430 | ```
2431 | </Tab>
2432 |
2433 | <Tab title="Python (Server)">
2434 | ```python
2435 | from mcp.server.sse import SseServerTransport
2436 | from starlette.applications import Starlette
2437 | from starlette.routing import Route
2438 |
2439 | app = Server("example-server")
2440 | sse = SseServerTransport("/messages")
2441 |
2442 | async def handle_sse(scope, receive, send):
2443 | async with sse.connect_sse(scope, receive, send) as streams:
2444 | await app.run(streams[0], streams[1], app.create_initialization_options())
2445 |
2446 | async def handle_messages(scope, receive, send):
2447 | await sse.handle_post_message(scope, receive, send)
2448 |
2449 | starlette_app = Starlette(
2450 | routes=[
2451 | Route("/sse", endpoint=handle_sse),
2452 | Route("/messages", endpoint=handle_messages, methods=["POST"]),
2453 | ]
2454 | )
2455 | ```
2456 | </Tab>
2457 |
2458 | <Tab title="Python (Client)">
2459 | ```python
2460 | async with sse_client("http://localhost:8000/sse") as streams:
2461 | async with ClientSession(streams[0], streams[1]) as session:
2462 | await session.initialize()
2463 | ```
2464 | </Tab>
2465 | </Tabs>
2466 |
2467 | ## Custom Transports
2468 |
2469 | MCP makes it easy to implement custom transports for specific needs. Any transport implementation just needs to conform to the Transport interface:
2470 |
2471 | You can implement custom transports for:
2472 |
2473 | * Custom network protocols
2474 | * Specialized communication channels
2475 | * Integration with existing systems
2476 | * Performance optimization
2477 |
2478 | <Tabs>
2479 | <Tab title="TypeScript">
2480 | ```typescript
2481 | interface Transport {
2482 | // Start processing messages
2483 | start(): Promise<void>;
2484 |
2485 | // Send a JSON-RPC message
2486 | send(message: JSONRPCMessage): Promise<void>;
2487 |
2488 | // Close the connection
2489 | close(): Promise<void>;
2490 |
2491 | // Callbacks
2492 | onclose?: () => void;
2493 | onerror?: (error: Error) => void;
2494 | onmessage?: (message: JSONRPCMessage) => void;
2495 | }
2496 | ```
2497 | </Tab>
2498 |
2499 | <Tab title="Python">
2500 | Note that while MCP Servers are often implemented with asyncio, we recommend
2501 | implementing low-level interfaces like transports with `anyio` for wider compatibility.
2502 |
2503 | ```python
2504 | @contextmanager
2505 | async def create_transport(
2506 | read_stream: MemoryObjectReceiveStream[JSONRPCMessage | Exception],
2507 | write_stream: MemoryObjectSendStream[JSONRPCMessage]
2508 | ):
2509 | """
2510 | Transport interface for MCP.
2511 |
2512 | Args:
2513 | read_stream: Stream to read incoming messages from
2514 | write_stream: Stream to write outgoing messages to
2515 | """
2516 | async with anyio.create_task_group() as tg:
2517 | try:
2518 | # Start processing messages
2519 | tg.start_soon(lambda: process_messages(read_stream))
2520 |
2521 | # Send messages
2522 | async with write_stream:
2523 | yield write_stream
2524 |
2525 | except Exception as exc:
2526 | # Handle errors
2527 | raise exc
2528 | finally:
2529 | # Clean up
2530 | tg.cancel_scope.cancel()
2531 | await write_stream.aclose()
2532 | await read_stream.aclose()
2533 | ```
2534 | </Tab>
2535 | </Tabs>
2536 |
2537 | ## Error Handling
2538 |
2539 | Transport implementations should handle various error scenarios:
2540 |
2541 | 1. Connection errors
2542 | 2. Message parsing errors
2543 | 3. Protocol errors
2544 | 4. Network timeouts
2545 | 5. Resource cleanup
2546 |
2547 | Example error handling:
2548 |
2549 | <Tabs>
2550 | <Tab title="TypeScript">
2551 | ```typescript
2552 | class ExampleTransport implements Transport {
2553 | async start() {
2554 | try {
2555 | // Connection logic
2556 | } catch (error) {
2557 | this.onerror?.(new Error(`Failed to connect: ${error}`));
2558 | throw error;
2559 | }
2560 | }
2561 |
2562 | async send(message: JSONRPCMessage) {
2563 | try {
2564 | // Sending logic
2565 | } catch (error) {
2566 | this.onerror?.(new Error(`Failed to send message: ${error}`));
2567 | throw error;
2568 | }
2569 | }
2570 | }
2571 | ```
2572 | </Tab>
2573 |
2574 | <Tab title="Python">
2575 | Note that while MCP Servers are often implemented with asyncio, we recommend
2576 | implementing low-level interfaces like transports with `anyio` for wider compatibility.
2577 |
2578 | ```python
2579 | @contextmanager
2580 | async def example_transport(scope: Scope, receive: Receive, send: Send):
2581 | try:
2582 | # Create streams for bidirectional communication
2583 | read_stream_writer, read_stream = anyio.create_memory_object_stream(0)
2584 | write_stream, write_stream_reader = anyio.create_memory_object_stream(0)
2585 |
2586 | async def message_handler():
2587 | try:
2588 | async with read_stream_writer:
2589 | # Message handling logic
2590 | pass
2591 | except Exception as exc:
2592 | logger.error(f"Failed to handle message: {exc}")
2593 | raise exc
2594 |
2595 | async with anyio.create_task_group() as tg:
2596 | tg.start_soon(message_handler)
2597 | try:
2598 | # Yield streams for communication
2599 | yield read_stream, write_stream
2600 | except Exception as exc:
2601 | logger.error(f"Transport error: {exc}")
2602 | raise exc
2603 | finally:
2604 | tg.cancel_scope.cancel()
2605 | await write_stream.aclose()
2606 | await read_stream.aclose()
2607 | except Exception as exc:
2608 | logger.error(f"Failed to initialize transport: {exc}")
2609 | raise exc
2610 | ```
2611 | </Tab>
2612 | </Tabs>
2613 |
2614 | ## Best Practices
2615 |
2616 | When implementing or using MCP transport:
2617 |
2618 | 1. Handle connection lifecycle properly
2619 | 2. Implement proper error handling
2620 | 3. Clean up resources on connection close
2621 | 4. Use appropriate timeouts
2622 | 5. Validate messages before sending
2623 | 6. Log transport events for debugging
2624 | 7. Implement reconnection logic when appropriate
2625 | 8. Handle backpressure in message queues
2626 | 9. Monitor connection health
2627 | 10. Implement proper security measures
2628 |
2629 | ## Security Considerations
2630 |
2631 | When implementing transport:
2632 |
2633 | ### Authentication and Authorization
2634 |
2635 | * Implement proper authentication mechanisms
2636 | * Validate client credentials
2637 | * Use secure token handling
2638 | * Implement authorization checks
2639 |
2640 | ### Data Security
2641 |
2642 | * Use TLS for network transport
2643 | * Encrypt sensitive data
2644 | * Validate message integrity
2645 | * Implement message size limits
2646 | * Sanitize input data
2647 |
2648 | ### Network Security
2649 |
2650 | * Implement rate limiting
2651 | * Use appropriate timeouts
2652 | * Handle denial of service scenarios
2653 | * Monitor for unusual patterns
2654 | * Implement proper firewall rules
2655 |
2656 | ## Debugging Transport
2657 |
2658 | Tips for debugging transport issues:
2659 |
2660 | 1. Enable debug logging
2661 | 2. Monitor message flow
2662 | 3. Check connection states
2663 | 4. Validate message formats
2664 | 5. Test error scenarios
2665 | 6. Use network analysis tools
2666 | 7. Implement health checks
2667 | 8. Monitor resource usage
2668 | 9. Test edge cases
2669 | 10. Use proper error tracking
2670 |
2671 |
2672 | # Debugging
2673 | Source: https://modelcontextprotocol.io/docs/tools/debugging
2674 |
2675 | A comprehensive guide to debugging Model Context Protocol (MCP) integrations
2676 |
2677 | Effective debugging is essential when developing MCP servers or integrating them with applications. This guide covers the debugging tools and approaches available in the MCP ecosystem.
2678 |
2679 | <Info>
2680 | This guide is for macOS. Guides for other platforms are coming soon.
2681 | </Info>
2682 |
2683 | ## Debugging tools overview
2684 |
2685 | MCP provides several tools for debugging at different levels:
2686 |
2687 | 1. **MCP Inspector**
2688 | * Interactive debugging interface
2689 | * Direct server testing
2690 | * See the [Inspector guide](/docs/tools/inspector) for details
2691 |
2692 | 2. **Claude Desktop Developer Tools**
2693 | * Integration testing
2694 | * Log collection
2695 | * Chrome DevTools integration
2696 |
2697 | 3. **Server Logging**
2698 | * Custom logging implementations
2699 | * Error tracking
2700 | * Performance monitoring
2701 |
2702 | ## Debugging in Claude Desktop
2703 |
2704 | ### Checking server status
2705 |
2706 | The Claude.app interface provides basic server status information:
2707 |
2708 | 1. Click the <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-plug-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> icon to view:
2709 | * Connected servers
2710 | * Available prompts and resources
2711 |
2712 | 2. Click the <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> icon to view:
2713 | * Tools made available to the model
2714 |
2715 | ### Viewing logs
2716 |
2717 | Review detailed MCP logs from Claude Desktop:
2718 |
2719 | ```bash
2720 | # Follow logs in real-time
2721 | tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
2722 | ```
2723 |
2724 | The logs capture:
2725 |
2726 | * Server connection events
2727 | * Configuration issues
2728 | * Runtime errors
2729 | * Message exchanges
2730 |
2731 | ### Using Chrome DevTools
2732 |
2733 | Access Chrome's developer tools inside Claude Desktop to investigate client-side errors:
2734 |
2735 | 1. Create a `developer_settings.json` file with `allowDevTools` set to true:
2736 |
2737 | ```bash
2738 | echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
2739 | ```
2740 |
2741 | 2. Open DevTools: `Command-Option-Shift-i`
2742 |
2743 | Note: You'll see two DevTools windows:
2744 |
2745 | * Main content window
2746 | * App title bar window
2747 |
2748 | Use the Console panel to inspect client-side errors.
2749 |
2750 | Use the Network panel to inspect:
2751 |
2752 | * Message payloads
2753 | * Connection timing
2754 |
2755 | ## Common issues
2756 |
2757 | ### Working directory
2758 |
2759 | When using MCP servers with Claude Desktop:
2760 |
2761 | * The working directory for servers launched via `claude_desktop_config.json` may be undefined (like `/` on macOS) since Claude Desktop could be started from anywhere
2762 | * Always use absolute paths in your configuration and `.env` files to ensure reliable operation
2763 | * For testing servers directly via command line, the working directory will be where you run the command
2764 |
2765 | For example in `claude_desktop_config.json`, use:
2766 |
2767 | ```json
2768 | {
2769 | "command": "npx",
2770 | "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
2771 | }
2772 | ```
2773 |
2774 | Instead of relative paths like `./data`
2775 |
2776 | ### Environment variables
2777 |
2778 | MCP servers inherit only a subset of environment variables automatically, like `USER`, `HOME`, and `PATH`.
2779 |
2780 | To override the default variables or provide your own, you can specify an `env` key in `claude_desktop_config.json`:
2781 |
2782 | ```json
2783 | {
2784 | "myserver": {
2785 | "command": "mcp-server-myapp",
2786 | "env": {
2787 | "MYAPP_API_KEY": "some_key",
2788 | }
2789 | }
2790 | }
2791 | ```
2792 |
2793 | ### Server initialization
2794 |
2795 | Common initialization problems:
2796 |
2797 | 1. **Path Issues**
2798 | * Incorrect server executable path
2799 | * Missing required files
2800 | * Permission problems
2801 | * Try using an absolute path for `command`
2802 |
2803 | 2. **Configuration Errors**
2804 | * Invalid JSON syntax
2805 | * Missing required fields
2806 | * Type mismatches
2807 |
2808 | 3. **Environment Problems**
2809 | * Missing environment variables
2810 | * Incorrect variable values
2811 | * Permission restrictions
2812 |
2813 | ### Connection problems
2814 |
2815 | When servers fail to connect:
2816 |
2817 | 1. Check Claude Desktop logs
2818 | 2. Verify server process is running
2819 | 3. Test standalone with [Inspector](/docs/tools/inspector)
2820 | 4. Verify protocol compatibility
2821 |
2822 | ## Implementing logging
2823 |
2824 | ### Server-side logging
2825 |
2826 | When building a server that uses the local stdio [transport](/docs/concepts/transports), all messages logged to stderr (standard error) will be captured by the host application (e.g., Claude Desktop) automatically.
2827 |
2828 | <Warning>
2829 | Local MCP servers should not log messages to stdout (standard out), as this will interfere with protocol operation.
2830 | </Warning>
2831 |
2832 | For all [transports](/docs/concepts/transports), you can also provide logging to the client by sending a log message notification:
2833 |
2834 | <Tabs>
2835 | <Tab title="Python">
2836 | ```python
2837 | server.request_context.session.send_log_message(
2838 | level="info",
2839 | data="Server started successfully",
2840 | )
2841 | ```
2842 | </Tab>
2843 |
2844 | <Tab title="TypeScript">
2845 | ```typescript
2846 | server.sendLoggingMessage({
2847 | level: "info",
2848 | data: "Server started successfully",
2849 | });
2850 | ```
2851 | </Tab>
2852 | </Tabs>
2853 |
2854 | Important events to log:
2855 |
2856 | * Initialization steps
2857 | * Resource access
2858 | * Tool execution
2859 | * Error conditions
2860 | * Performance metrics
2861 |
2862 | ### Client-side logging
2863 |
2864 | In client applications:
2865 |
2866 | 1. Enable debug logging
2867 | 2. Monitor network traffic
2868 | 3. Track message exchanges
2869 | 4. Record error states
2870 |
2871 | ## Debugging workflow
2872 |
2873 | ### Development cycle
2874 |
2875 | 1. Initial Development
2876 | * Use [Inspector](/docs/tools/inspector) for basic testing
2877 | * Implement core functionality
2878 | * Add logging points
2879 |
2880 | 2. Integration Testing
2881 | * Test in Claude Desktop
2882 | * Monitor logs
2883 | * Check error handling
2884 |
2885 | ### Testing changes
2886 |
2887 | To test changes efficiently:
2888 |
2889 | * **Configuration changes**: Restart Claude Desktop
2890 | * **Server code changes**: Use Command-R to reload
2891 | * **Quick iteration**: Use [Inspector](/docs/tools/inspector) during development
2892 |
2893 | ## Best practices
2894 |
2895 | ### Logging strategy
2896 |
2897 | 1. **Structured Logging**
2898 | * Use consistent formats
2899 | * Include context
2900 | * Add timestamps
2901 | * Track request IDs
2902 |
2903 | 2. **Error Handling**
2904 | * Log stack traces
2905 | * Include error context
2906 | * Track error patterns
2907 | * Monitor recovery
2908 |
2909 | 3. **Performance Tracking**
2910 | * Log operation timing
2911 | * Monitor resource usage
2912 | * Track message sizes
2913 | * Measure latency
2914 |
2915 | ### Security considerations
2916 |
2917 | When debugging:
2918 |
2919 | 1. **Sensitive Data**
2920 | * Sanitize logs
2921 | * Protect credentials
2922 | * Mask personal information
2923 |
2924 | 2. **Access Control**
2925 | * Verify permissions
2926 | * Check authentication
2927 | * Monitor access patterns
2928 |
2929 | ## Getting help
2930 |
2931 | When encountering issues:
2932 |
2933 | 1. **First Steps**
2934 | * Check server logs
2935 | * Test with [Inspector](/docs/tools/inspector)
2936 | * Review configuration
2937 | * Verify environment
2938 |
2939 | 2. **Support Channels**
2940 | * GitHub issues
2941 | * GitHub discussions
2942 |
2943 | 3. **Providing Information**
2944 | * Log excerpts
2945 | * Configuration files
2946 | * Steps to reproduce
2947 | * Environment details
2948 |
2949 | ## Next steps
2950 |
2951 | <CardGroup cols={2}>
2952 | <Card title="MCP Inspector" icon="magnifying-glass" href="/docs/tools/inspector">
2953 | Learn to use the MCP Inspector
2954 | </Card>
2955 | </CardGroup>
2956 |
2957 |
2958 | # Inspector
2959 | Source: https://modelcontextprotocol.io/docs/tools/inspector
2960 |
2961 | In-depth guide to using the MCP Inspector for testing and debugging Model Context Protocol servers
2962 |
2963 | The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an interactive developer tool for testing and debugging MCP servers. While the [Debugging Guide](/docs/tools/debugging) covers the Inspector as part of the overall debugging toolkit, this document provides a detailed exploration of the Inspector's features and capabilities.
2964 |
2965 | ## Getting started
2966 |
2967 | ### Installation and basic usage
2968 |
2969 | The Inspector runs directly through `npx` without requiring installation:
2970 |
2971 | ```bash
2972 | npx @modelcontextprotocol/inspector <command>
2973 | ```
2974 |
2975 | ```bash
2976 | npx @modelcontextprotocol/inspector <command> <arg1> <arg2>
2977 | ```
2978 |
2979 | #### Inspecting servers from NPM or PyPi
2980 |
2981 | A common way to start server packages from [NPM](https://npmjs.com) or [PyPi](https://pypi.com).
2982 |
2983 | <Tabs>
2984 | <Tab title="NPM package">
2985 | ```bash
2986 | npx -y @modelcontextprotocol/inspector npx <package-name> <args>
2987 | # For example
2988 | npx -y @modelcontextprotocol/inspector npx server-postgres postgres://127.0.0.1/testdb
2989 | ```
2990 | </Tab>
2991 |
2992 | <Tab title="PyPi package">
2993 | ```bash
2994 | npx @modelcontextprotocol/inspector uvx <package-name> <args>
2995 | # For example
2996 | npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git
2997 | ```
2998 | </Tab>
2999 | </Tabs>
3000 |
3001 | #### Inspecting locally developed servers
3002 |
3003 | To inspect servers locally developed or downloaded as a repository, the most common
3004 | way is:
3005 |
3006 | <Tabs>
3007 | <Tab title="TypeScript">
3008 | ```bash
3009 | npx @modelcontextprotocol/inspector node path/to/server/index.js args...
3010 | ```
3011 | </Tab>
3012 |
3013 | <Tab title="Python">
3014 | ```bash
3015 | npx @modelcontextprotocol/inspector \
3016 | uv \
3017 | --directory path/to/server \
3018 | run \
3019 | package-name \
3020 | args...
3021 | ```
3022 | </Tab>
3023 | </Tabs>
3024 |
3025 | Please carefully read any attached README for the most accurate instructions.
3026 |
3027 | ## Feature overview
3028 |
3029 | <Frame caption="The MCP Inspector interface">
3030 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/mcp-inspector.png" />
3031 | </Frame>
3032 |
3033 | The Inspector provides several features for interacting with your MCP server:
3034 |
3035 | ### Server connection pane
3036 |
3037 | * Allows selecting the [transport](/docs/concepts/transports) for connecting to the server
3038 | * For local servers, supports customizing the command-line arguments and environment
3039 |
3040 | ### Resources tab
3041 |
3042 | * Lists all available resources
3043 | * Shows resource metadata (MIME types, descriptions)
3044 | * Allows resource content inspection
3045 | * Supports subscription testing
3046 |
3047 | ### Prompts tab
3048 |
3049 | * Displays available prompt templates
3050 | * Shows prompt arguments and descriptions
3051 | * Enables prompt testing with custom arguments
3052 | * Previews generated messages
3053 |
3054 | ### Tools tab
3055 |
3056 | * Lists available tools
3057 | * Shows tool schemas and descriptions
3058 | * Enables tool testing with custom inputs
3059 | * Displays tool execution results
3060 |
3061 | ### Notifications pane
3062 |
3063 | * Presents all logs recorded from the server
3064 | * Shows notifications received from the server
3065 |
3066 | ## Best practices
3067 |
3068 | ### Development workflow
3069 |
3070 | 1. Start Development
3071 | * Launch Inspector with your server
3072 | * Verify basic connectivity
3073 | * Check capability negotiation
3074 |
3075 | 2. Iterative testing
3076 | * Make server changes
3077 | * Rebuild the server
3078 | * Reconnect the Inspector
3079 | * Test affected features
3080 | * Monitor messages
3081 |
3082 | 3. Test edge cases
3083 | * Invalid inputs
3084 | * Missing prompt arguments
3085 | * Concurrent operations
3086 | * Verify error handling and error responses
3087 |
3088 | ## Next steps
3089 |
3090 | <CardGroup cols={2}>
3091 | <Card title="Inspector Repository" icon="github" href="https://github.com/modelcontextprotocol/inspector">
3092 | Check out the MCP Inspector source code
3093 | </Card>
3094 |
3095 | <Card title="Debugging Guide" icon="bug" href="/docs/tools/debugging">
3096 | Learn about broader debugging strategies
3097 | </Card>
3098 | </CardGroup>
3099 |
3100 |
3101 | # Example Servers
3102 | Source: https://modelcontextprotocol.io/examples
3103 |
3104 | A list of example servers and implementations
3105 |
3106 | This page showcases various Model Context Protocol (MCP) servers that demonstrate the protocol's capabilities and versatility. These servers enable Large Language Models (LLMs) to securely access tools and data sources.
3107 |
3108 | ## Reference implementations
3109 |
3110 | These official reference servers demonstrate core MCP features and SDK usage:
3111 |
3112 | ### Data and file systems
3113 |
3114 | * **[Filesystem](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem)** - Secure file operations with configurable access controls
3115 | * **[PostgreSQL](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres)** - Read-only database access with schema inspection capabilities
3116 | * **[SQLite](https://github.com/modelcontextprotocol/servers/tree/main/src/sqlite)** - Database interaction and business intelligence features
3117 | * **[Google Drive](https://github.com/modelcontextprotocol/servers/tree/main/src/gdrive)** - File access and search capabilities for Google Drive
3118 |
3119 | ### Development tools
3120 |
3121 | * **[Git](https://github.com/modelcontextprotocol/servers/tree/main/src/git)** - Tools to read, search, and manipulate Git repositories
3122 | * **[GitHub](https://github.com/modelcontextprotocol/servers/tree/main/src/github)** - Repository management, file operations, and GitHub API integration
3123 | * **[GitLab](https://github.com/modelcontextprotocol/servers/tree/main/src/gitlab)** - GitLab API integration enabling project management
3124 | * **[Sentry](https://github.com/modelcontextprotocol/servers/tree/main/src/sentry)** - Retrieving and analyzing issues from Sentry.io
3125 |
3126 | ### Web and browser automation
3127 |
3128 | * **[Brave Search](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search)** - Web and local search using Brave's Search API
3129 | * **[Fetch](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch)** - Web content fetching and conversion optimized for LLM usage
3130 | * **[Puppeteer](https://github.com/modelcontextprotocol/servers/tree/main/src/puppeteer)** - Browser automation and web scraping capabilities
3131 |
3132 | ### Productivity and communication
3133 |
3134 | * **[Slack](https://github.com/modelcontextprotocol/servers/tree/main/src/slack)** - Channel management and messaging capabilities
3135 | * **[Google Maps](https://github.com/modelcontextprotocol/servers/tree/main/src/google-maps)** - Location services, directions, and place details
3136 | * **[Memory](https://github.com/modelcontextprotocol/servers/tree/main/src/memory)** - Knowledge graph-based persistent memory system
3137 |
3138 | ### AI and specialized tools
3139 |
3140 | * **[EverArt](https://github.com/modelcontextprotocol/servers/tree/main/src/everart)** - AI image generation using various models
3141 | * **[Sequential Thinking](https://github.com/modelcontextprotocol/servers/tree/main/src/sequentialthinking)** - Dynamic problem-solving through thought sequences
3142 | * **[AWS KB Retrieval](https://github.com/modelcontextprotocol/servers/tree/main/src/aws-kb-retrieval-server)** - Retrieval from AWS Knowledge Base using Bedrock Agent Runtime
3143 |
3144 | ## Official integrations
3145 |
3146 | These MCP servers are maintained by companies for their platforms:
3147 |
3148 | * **[Axiom](https://github.com/axiomhq/mcp-server-axiom)** - Query and analyze logs, traces, and event data using natural language
3149 | * **[Browserbase](https://github.com/browserbase/mcp-server-browserbase)** - Automate browser interactions in the cloud
3150 | * **[Cloudflare](https://github.com/cloudflare/mcp-server-cloudflare)** - Deploy and manage resources on the Cloudflare developer platform
3151 | * **[E2B](https://github.com/e2b-dev/mcp-server)** - Execute code in secure cloud sandboxes
3152 | * **[Neon](https://github.com/neondatabase/mcp-server-neon)** - Interact with the Neon serverless Postgres platform
3153 | * **[Obsidian Markdown Notes](https://github.com/calclavia/mcp-obsidian)** - Read and search through Markdown notes in Obsidian vaults
3154 | * **[Qdrant](https://github.com/qdrant/mcp-server-qdrant/)** - Implement semantic memory using the Qdrant vector search engine
3155 | * **[Raygun](https://github.com/MindscapeHQ/mcp-server-raygun)** - Access crash reporting and monitoring data
3156 | * **[Search1API](https://github.com/fatwang2/search1api-mcp)** - Unified API for search, crawling, and sitemaps
3157 | * **[Stripe](https://github.com/stripe/agent-toolkit)** - Interact with the Stripe API
3158 | * **[Tinybird](https://github.com/tinybirdco/mcp-tinybird)** - Interface with the Tinybird serverless ClickHouse platform
3159 | * **[Weaviate](https://github.com/weaviate/mcp-server-weaviate)** - Enable Agentic RAG through your Weaviate collection(s)
3160 |
3161 | ## Community highlights
3162 |
3163 | A growing ecosystem of community-developed servers extends MCP's capabilities:
3164 |
3165 | * **[Docker](https://github.com/ckreiling/mcp-server-docker)** - Manage containers, images, volumes, and networks
3166 | * **[Kubernetes](https://github.com/Flux159/mcp-server-kubernetes)** - Manage pods, deployments, and services
3167 | * **[Linear](https://github.com/jerhadf/linear-mcp-server)** - Project management and issue tracking
3168 | * **[Snowflake](https://github.com/datawiz168/mcp-snowflake-service)** - Interact with Snowflake databases
3169 | * **[Spotify](https://github.com/varunneal/spotify-mcp)** - Control Spotify playback and manage playlists
3170 | * **[Todoist](https://github.com/abhiz123/todoist-mcp-server)** - Task management integration
3171 |
3172 | > **Note:** Community servers are untested and should be used at your own risk. They are not affiliated with or endorsed by Anthropic.
3173 |
3174 | For a complete list of community servers, visit the [MCP Servers Repository](https://github.com/modelcontextprotocol/servers).
3175 |
3176 | ## Getting started
3177 |
3178 | ### Using reference servers
3179 |
3180 | TypeScript-based servers can be used directly with `npx`:
3181 |
3182 | ```bash
3183 | npx -y @modelcontextprotocol/server-memory
3184 | ```
3185 |
3186 | Python-based servers can be used with `uvx` (recommended) or `pip`:
3187 |
3188 | ```bash
3189 | # Using uvx
3190 | uvx mcp-server-git
3191 |
3192 | # Using pip
3193 | pip install mcp-server-git
3194 | python -m mcp_server_git
3195 | ```
3196 |
3197 | ### Configuring with Claude
3198 |
3199 | To use an MCP server with Claude, add it to your configuration:
3200 |
3201 | ```json
3202 | {
3203 | "mcpServers": {
3204 | "memory": {
3205 | "command": "npx",
3206 | "args": ["-y", "@modelcontextprotocol/server-memory"]
3207 | },
3208 | "filesystem": {
3209 | "command": "npx",
3210 | "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
3211 | },
3212 | "github": {
3213 | "command": "npx",
3214 | "args": ["-y", "@modelcontextprotocol/server-github"],
3215 | "env": {
3216 | "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
3217 | }
3218 | }
3219 | }
3220 | }
3221 | ```
3222 |
3223 | ## Additional resources
3224 |
3225 | * [MCP Servers Repository](https://github.com/modelcontextprotocol/servers) - Complete collection of reference implementations and community servers
3226 | * [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers) - Curated list of MCP servers
3227 | * [MCP CLI](https://github.com/wong2/mcp-cli) - Command-line inspector for testing MCP servers
3228 | * [MCP Get](https://mcp-get.com) - Tool for installing and managing MCP servers
3229 | * [Supergateway](https://github.com/supercorp-ai/supergateway) - Run MCP stdio servers over SSE
3230 | * [Zapier MCP](https://zapier.com/mcp) - MCP Server with over 7,000+ apps and 30,000+ actions
3231 |
3232 | Visit our [GitHub Discussions](https://github.com/orgs/modelcontextprotocol/discussions) to engage with the MCP community.
3233 |
3234 |
3235 | # Introduction
3236 | Source: https://modelcontextprotocol.io/introduction
3237 |
3238 | Get started with the Model Context Protocol (MCP)
3239 |
3240 | <Note>C# SDK released! Check out [what else is new.](/development/updates)</Note>
3241 |
3242 | MCP is an open protocol that standardizes how applications provide context to LLMs. Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect your devices to various peripherals and accessories, MCP provides a standardized way to connect AI models to different data sources and tools.
3243 |
3244 | ## Why MCP?
3245 |
3246 | MCP helps you build agents and complex workflows on top of LLMs. LLMs frequently need to integrate with data and tools, and MCP provides:
3247 |
3248 | * A growing list of pre-built integrations that your LLM can directly plug into
3249 | * The flexibility to switch between LLM providers and vendors
3250 | * Best practices for securing your data within your infrastructure
3251 |
3252 | ### General architecture
3253 |
3254 | At its core, MCP follows a client-server architecture where a host application can connect to multiple servers:
3255 |
3256 | ```mermaid
3257 | flowchart LR
3258 | subgraph "Your Computer"
3259 | Host["Host with MCP Client\n(Claude, IDEs, Tools)"]
3260 | S1["MCP Server A"]
3261 | S2["MCP Server B"]
3262 | S3["MCP Server C"]
3263 | Host <-->|"MCP Protocol"| S1
3264 | Host <-->|"MCP Protocol"| S2
3265 | Host <-->|"MCP Protocol"| S3
3266 | S1 <--> D1[("Local\nData Source A")]
3267 | S2 <--> D2[("Local\nData Source B")]
3268 | end
3269 | subgraph "Internet"
3270 | S3 <-->|"Web APIs"| D3[("Remote\nService C")]
3271 | end
3272 | ```
3273 |
3274 | * **MCP Hosts**: Programs like Claude Desktop, IDEs, or AI tools that want to access data through MCP
3275 | * **MCP Clients**: Protocol clients that maintain 1:1 connections with servers
3276 | * **MCP Servers**: Lightweight programs that each expose specific capabilities through the standardized Model Context Protocol
3277 | * **Local Data Sources**: Your computer's files, databases, and services that MCP servers can securely access
3278 | * **Remote Services**: External systems available over the internet (e.g., through APIs) that MCP servers can connect to
3279 |
3280 | ## Get started
3281 |
3282 | Choose the path that best fits your needs:
3283 |
3284 | #### Quick Starts
3285 |
3286 | <CardGroup cols={2}>
3287 | <Card title="For Server Developers" icon="bolt" href="/quickstart/server">
3288 | Get started building your own server to use in Claude for Desktop and other clients
3289 | </Card>
3290 |
3291 | <Card title="For Client Developers" icon="bolt" href="/quickstart/client">
3292 | Get started building your own client that can integrate with all MCP servers
3293 | </Card>
3294 |
3295 | <Card title="For Claude Desktop Users" icon="bolt" href="/quickstart/user">
3296 | Get started using pre-built servers in Claude for Desktop
3297 | </Card>
3298 | </CardGroup>
3299 |
3300 | #### Examples
3301 |
3302 | <CardGroup cols={2}>
3303 | <Card title="Example Servers" icon="grid" href="/examples">
3304 | Check out our gallery of official MCP servers and implementations
3305 | </Card>
3306 |
3307 | <Card title="Example Clients" icon="cubes" href="/clients">
3308 | View the list of clients that support MCP integrations
3309 | </Card>
3310 | </CardGroup>
3311 |
3312 | ## Tutorials
3313 |
3314 | <CardGroup cols={2}>
3315 | <Card title="Building MCP with LLMs" icon="comments" href="/tutorials/building-mcp-with-llms">
3316 | Learn how to use LLMs like Claude to speed up your MCP development
3317 | </Card>
3318 |
3319 | <Card title="Debugging Guide" icon="bug" href="/docs/tools/debugging">
3320 | Learn how to effectively debug MCP servers and integrations
3321 | </Card>
3322 |
3323 | <Card title="MCP Inspector" icon="magnifying-glass" href="/docs/tools/inspector">
3324 | Test and inspect your MCP servers with our interactive debugging tool
3325 | </Card>
3326 |
3327 | <Card title="MCP Workshop (Video, 2hr)" icon="person-chalkboard" href="https://www.youtube.com/watch?v=kQmXtrmQ5Zg">
3328 | <iframe src="https://www.youtube.com/embed/kQmXtrmQ5Zg" />
3329 | </Card>
3330 | </CardGroup>
3331 |
3332 | ## Explore MCP
3333 |
3334 | Dive deeper into MCP's core concepts and capabilities:
3335 |
3336 | <CardGroup cols={2}>
3337 | <Card title="Core architecture" icon="sitemap" href="/docs/concepts/architecture">
3338 | Understand how MCP connects clients, servers, and LLMs
3339 | </Card>
3340 |
3341 | <Card title="Resources" icon="database" href="/docs/concepts/resources">
3342 | Expose data and content from your servers to LLMs
3343 | </Card>
3344 |
3345 | <Card title="Prompts" icon="message" href="/docs/concepts/prompts">
3346 | Create reusable prompt templates and workflows
3347 | </Card>
3348 |
3349 | <Card title="Tools" icon="wrench" href="/docs/concepts/tools">
3350 | Enable LLMs to perform actions through your server
3351 | </Card>
3352 |
3353 | <Card title="Sampling" icon="robot" href="/docs/concepts/sampling">
3354 | Let your servers request completions from LLMs
3355 | </Card>
3356 |
3357 | <Card title="Transports" icon="network-wired" href="/docs/concepts/transports">
3358 | Learn about MCP's communication mechanism
3359 | </Card>
3360 | </CardGroup>
3361 |
3362 | ## Contributing
3363 |
3364 | Want to contribute? Check out our [Contributing Guide](/development/contributing) to learn how you can help improve MCP.
3365 |
3366 | ## Support and Feedback
3367 |
3368 | Here's how to get help or provide feedback:
3369 |
3370 | * For bug reports and feature requests related to the MCP specification, SDKs, or documentation (open source), please [create a GitHub issue](https://github.com/modelcontextprotocol)
3371 | * For discussions or Q\&A about the MCP specification, use the [specification discussions](https://github.com/modelcontextprotocol/specification/discussions)
3372 | * For discussions or Q\&A about other MCP open source components, use the [organization discussions](https://github.com/orgs/modelcontextprotocol/discussions)
3373 | * For bug reports, feature requests, and questions related to Claude.app and claude.ai's MCP integration, please see Anthropic's guide on [How to Get Support](https://support.anthropic.com/en/articles/9015913-how-to-get-support)
3374 |
3375 |
3376 | # For Client Developers
3377 | Source: https://modelcontextprotocol.io/quickstart/client
3378 |
3379 | Get started building your own client that can integrate with all MCP servers.
3380 |
3381 | In this tutorial, you'll learn how to build a LLM-powered chatbot client that connects to MCP servers. It helps to have gone through the [Server quickstart](/quickstart/server) that guides you through the basic of building your first server.
3382 |
3383 | <Tabs>
3384 | <Tab title="Python">
3385 | [You can find the complete code for this tutorial here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/mcp-client-python)
3386 |
3387 | ## System Requirements
3388 |
3389 | Before starting, ensure your system meets these requirements:
3390 |
3391 | * Mac or Windows computer
3392 | * Latest Python version installed
3393 | * Latest version of `uv` installed
3394 |
3395 | ## Setting Up Your Environment
3396 |
3397 | First, create a new Python project with `uv`:
3398 |
3399 | ```bash
3400 | # Create project directory
3401 | uv init mcp-client
3402 | cd mcp-client
3403 |
3404 | # Create virtual environment
3405 | uv venv
3406 |
3407 | # Activate virtual environment
3408 | # On Windows:
3409 | .venv\Scripts\activate
3410 | # On Unix or MacOS:
3411 | source .venv/bin/activate
3412 |
3413 | # Install required packages
3414 | uv add mcp anthropic python-dotenv
3415 |
3416 | # Remove boilerplate files
3417 | rm main.py
3418 |
3419 | # Create our main file
3420 | touch client.py
3421 | ```
3422 |
3423 | ## Setting Up Your API Key
3424 |
3425 | You'll need an Anthropic API key from the [Anthropic Console](https://console.anthropic.com/settings/keys).
3426 |
3427 | Create a `.env` file to store it:
3428 |
3429 | ```bash
3430 | # Create .env file
3431 | touch .env
3432 | ```
3433 |
3434 | Add your key to the `.env` file:
3435 |
3436 | ```bash
3437 | ANTHROPIC_API_KEY=<your key here>
3438 | ```
3439 |
3440 | Add `.env` to your `.gitignore`:
3441 |
3442 | ```bash
3443 | echo ".env" >> .gitignore
3444 | ```
3445 |
3446 | <Warning>
3447 | Make sure you keep your `ANTHROPIC_API_KEY` secure!
3448 | </Warning>
3449 |
3450 | ## Creating the Client
3451 |
3452 | ### Basic Client Structure
3453 |
3454 | First, let's set up our imports and create the basic client class:
3455 |
3456 | ```python
3457 | import asyncio
3458 | from typing import Optional
3459 | from contextlib import AsyncExitStack
3460 |
3461 | from mcp import ClientSession, StdioServerParameters
3462 | from mcp.client.stdio import stdio_client
3463 |
3464 | from anthropic import Anthropic
3465 | from dotenv import load_dotenv
3466 |
3467 | load_dotenv() # load environment variables from .env
3468 |
3469 | class MCPClient:
3470 | def __init__(self):
3471 | # Initialize session and client objects
3472 | self.session: Optional[ClientSession] = None
3473 | self.exit_stack = AsyncExitStack()
3474 | self.anthropic = Anthropic()
3475 | # methods will go here
3476 | ```
3477 |
3478 | ### Server Connection Management
3479 |
3480 | Next, we'll implement the method to connect to an MCP server:
3481 |
3482 | ```python
3483 | async def connect_to_server(self, server_script_path: str):
3484 | """Connect to an MCP server
3485 |
3486 | Args:
3487 | server_script_path: Path to the server script (.py or .js)
3488 | """
3489 | is_python = server_script_path.endswith('.py')
3490 | is_js = server_script_path.endswith('.js')
3491 | if not (is_python or is_js):
3492 | raise ValueError("Server script must be a .py or .js file")
3493 |
3494 | command = "python" if is_python else "node"
3495 | server_params = StdioServerParameters(
3496 | command=command,
3497 | args=[server_script_path],
3498 | env=None
3499 | )
3500 |
3501 | stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
3502 | self.stdio, self.write = stdio_transport
3503 | self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))
3504 |
3505 | await self.session.initialize()
3506 |
3507 | # List available tools
3508 | response = await self.session.list_tools()
3509 | tools = response.tools
3510 | print("\nConnected to server with tools:", [tool.name for tool in tools])
3511 | ```
3512 |
3513 | ### Query Processing Logic
3514 |
3515 | Now let's add the core functionality for processing queries and handling tool calls:
3516 |
3517 | ```python
3518 | async def process_query(self, query: str) -> str:
3519 | """Process a query using Claude and available tools"""
3520 | messages = [
3521 | {
3522 | "role": "user",
3523 | "content": query
3524 | }
3525 | ]
3526 |
3527 | response = await self.session.list_tools()
3528 | available_tools = [{
3529 | "name": tool.name,
3530 | "description": tool.description,
3531 | "input_schema": tool.inputSchema
3532 | } for tool in response.tools]
3533 |
3534 | # Initial Claude API call
3535 | response = self.anthropic.messages.create(
3536 | model="claude-3-5-sonnet-20241022",
3537 | max_tokens=1000,
3538 | messages=messages,
3539 | tools=available_tools
3540 | )
3541 |
3542 | # Process response and handle tool calls
3543 | final_text = []
3544 |
3545 | assistant_message_content = []
3546 | for content in response.content:
3547 | if content.type == 'text':
3548 | final_text.append(content.text)
3549 | assistant_message_content.append(content)
3550 | elif content.type == 'tool_use':
3551 | tool_name = content.name
3552 | tool_args = content.input
3553 |
3554 | # Execute tool call
3555 | result = await self.session.call_tool(tool_name, tool_args)
3556 | final_text.append(f"[Calling tool {tool_name} with args {tool_args}]")
3557 |
3558 | assistant_message_content.append(content)
3559 | messages.append({
3560 | "role": "assistant",
3561 | "content": assistant_message_content
3562 | })
3563 | messages.append({
3564 | "role": "user",
3565 | "content": [
3566 | {
3567 | "type": "tool_result",
3568 | "tool_use_id": content.id,
3569 | "content": result.content
3570 | }
3571 | ]
3572 | })
3573 |
3574 | # Get next response from Claude
3575 | response = self.anthropic.messages.create(
3576 | model="claude-3-5-sonnet-20241022",
3577 | max_tokens=1000,
3578 | messages=messages,
3579 | tools=available_tools
3580 | )
3581 |
3582 | final_text.append(response.content[0].text)
3583 |
3584 | return "\n".join(final_text)
3585 | ```
3586 |
3587 | ### Interactive Chat Interface
3588 |
3589 | Now we'll add the chat loop and cleanup functionality:
3590 |
3591 | ```python
3592 | async def chat_loop(self):
3593 | """Run an interactive chat loop"""
3594 | print("\nMCP Client Started!")
3595 | print("Type your queries or 'quit' to exit.")
3596 |
3597 | while True:
3598 | try:
3599 | query = input("\nQuery: ").strip()
3600 |
3601 | if query.lower() == 'quit':
3602 | break
3603 |
3604 | response = await self.process_query(query)
3605 | print("\n" + response)
3606 |
3607 | except Exception as e:
3608 | print(f"\nError: {str(e)}")
3609 |
3610 | async def cleanup(self):
3611 | """Clean up resources"""
3612 | await self.exit_stack.aclose()
3613 | ```
3614 |
3615 | ### Main Entry Point
3616 |
3617 | Finally, we'll add the main execution logic:
3618 |
3619 | ```python
3620 | async def main():
3621 | if len(sys.argv) < 2:
3622 | print("Usage: python client.py <path_to_server_script>")
3623 | sys.exit(1)
3624 |
3625 | client = MCPClient()
3626 | try:
3627 | await client.connect_to_server(sys.argv[1])
3628 | await client.chat_loop()
3629 | finally:
3630 | await client.cleanup()
3631 |
3632 | if __name__ == "__main__":
3633 | import sys
3634 | asyncio.run(main())
3635 | ```
3636 |
3637 | You can find the complete `client.py` file [here.](https://gist.github.com/zckly/f3f28ea731e096e53b39b47bf0a2d4b1)
3638 |
3639 | ## Key Components Explained
3640 |
3641 | ### 1. Client Initialization
3642 |
3643 | * The `MCPClient` class initializes with session management and API clients
3644 | * Uses `AsyncExitStack` for proper resource management
3645 | * Configures the Anthropic client for Claude interactions
3646 |
3647 | ### 2. Server Connection
3648 |
3649 | * Supports both Python and Node.js servers
3650 | * Validates server script type
3651 | * Sets up proper communication channels
3652 | * Initializes the session and lists available tools
3653 |
3654 | ### 3. Query Processing
3655 |
3656 | * Maintains conversation context
3657 | * Handles Claude's responses and tool calls
3658 | * Manages the message flow between Claude and tools
3659 | * Combines results into a coherent response
3660 |
3661 | ### 4. Interactive Interface
3662 |
3663 | * Provides a simple command-line interface
3664 | * Handles user input and displays responses
3665 | * Includes basic error handling
3666 | * Allows graceful exit
3667 |
3668 | ### 5. Resource Management
3669 |
3670 | * Proper cleanup of resources
3671 | * Error handling for connection issues
3672 | * Graceful shutdown procedures
3673 |
3674 | ## Common Customization Points
3675 |
3676 | 1. **Tool Handling**
3677 | * Modify `process_query()` to handle specific tool types
3678 | * Add custom error handling for tool calls
3679 | * Implement tool-specific response formatting
3680 |
3681 | 2. **Response Processing**
3682 | * Customize how tool results are formatted
3683 | * Add response filtering or transformation
3684 | * Implement custom logging
3685 |
3686 | 3. **User Interface**
3687 | * Add a GUI or web interface
3688 | * Implement rich console output
3689 | * Add command history or auto-completion
3690 |
3691 | ## Running the Client
3692 |
3693 | To run your client with any MCP server:
3694 |
3695 | ```bash
3696 | uv run client.py path/to/server.py # python server
3697 | uv run client.py path/to/build/index.js # node server
3698 | ```
3699 |
3700 | <Note>
3701 | If you're continuing the weather tutorial from the server quickstart, your command might look something like this: `python client.py .../quickstart-resources/weather-server-python/weather.py`
3702 | </Note>
3703 |
3704 | The client will:
3705 |
3706 | 1. Connect to the specified server
3707 | 2. List available tools
3708 | 3. Start an interactive chat session where you can:
3709 | * Enter queries
3710 | * See tool executions
3711 | * Get responses from Claude
3712 |
3713 | Here's an example of what it should look like if connected to the weather server from the server quickstart:
3714 |
3715 | <Frame>
3716 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/client-claude-cli-python.png" />
3717 | </Frame>
3718 |
3719 | ## How It Works
3720 |
3721 | When you submit a query:
3722 |
3723 | 1. The client gets the list of available tools from the server
3724 | 2. Your query is sent to Claude along with tool descriptions
3725 | 3. Claude decides which tools (if any) to use
3726 | 4. The client executes any requested tool calls through the server
3727 | 5. Results are sent back to Claude
3728 | 6. Claude provides a natural language response
3729 | 7. The response is displayed to you
3730 |
3731 | ## Best practices
3732 |
3733 | 1. **Error Handling**
3734 | * Always wrap tool calls in try-catch blocks
3735 | * Provide meaningful error messages
3736 | * Gracefully handle connection issues
3737 |
3738 | 2. **Resource Management**
3739 | * Use `AsyncExitStack` for proper cleanup
3740 | * Close connections when done
3741 | * Handle server disconnections
3742 |
3743 | 3. **Security**
3744 | * Store API keys securely in `.env`
3745 | * Validate server responses
3746 | * Be cautious with tool permissions
3747 |
3748 | ## Troubleshooting
3749 |
3750 | ### Server Path Issues
3751 |
3752 | * Double-check the path to your server script is correct
3753 | * Use the absolute path if the relative path isn't working
3754 | * For Windows users, make sure to use forward slashes (/) or escaped backslashes (\\) in the path
3755 | * Verify the server file has the correct extension (.py for Python or .js for Node.js)
3756 |
3757 | Example of correct path usage:
3758 |
3759 | ```bash
3760 | # Relative path
3761 | uv run client.py ./server/weather.py
3762 |
3763 | # Absolute path
3764 | uv run client.py /Users/username/projects/mcp-server/weather.py
3765 |
3766 | # Windows path (either format works)
3767 | uv run client.py C:/projects/mcp-server/weather.py
3768 | uv run client.py C:\\projects\\mcp-server\\weather.py
3769 | ```
3770 |
3771 | ### Response Timing
3772 |
3773 | * The first response might take up to 30 seconds to return
3774 | * This is normal and happens while:
3775 | * The server initializes
3776 | * Claude processes the query
3777 | * Tools are being executed
3778 | * Subsequent responses are typically faster
3779 | * Don't interrupt the process during this initial waiting period
3780 |
3781 | ### Common Error Messages
3782 |
3783 | If you see:
3784 |
3785 | * `FileNotFoundError`: Check your server path
3786 | * `Connection refused`: Ensure the server is running and the path is correct
3787 | * `Tool execution failed`: Verify the tool's required environment variables are set
3788 | * `Timeout error`: Consider increasing the timeout in your client configuration
3789 | </Tab>
3790 |
3791 | <Tab title="Node">
3792 | [You can find the complete code for this tutorial here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/mcp-client-typescript)
3793 |
3794 | ## System Requirements
3795 |
3796 | Before starting, ensure your system meets these requirements:
3797 |
3798 | * Mac or Windows computer
3799 | * Node.js 17 or higher installed
3800 | * Latest version of `npm` installed
3801 | * Anthropic API key (Claude)
3802 |
3803 | ## Setting Up Your Environment
3804 |
3805 | First, let's create and set up our project:
3806 |
3807 | <CodeGroup>
3808 | ```bash MacOS/Linux
3809 | # Create project directory
3810 | mkdir mcp-client-typescript
3811 | cd mcp-client-typescript
3812 |
3813 | # Initialize npm project
3814 | npm init -y
3815 |
3816 | # Install dependencies
3817 | npm install @anthropic-ai/sdk @modelcontextprotocol/sdk dotenv
3818 |
3819 | # Install dev dependencies
3820 | npm install -D @types/node typescript
3821 |
3822 | # Create source file
3823 | touch index.ts
3824 | ```
3825 |
3826 | ```powershell Windows
3827 | # Create project directory
3828 | md mcp-client-typescript
3829 | cd mcp-client-typescript
3830 |
3831 | # Initialize npm project
3832 | npm init -y
3833 |
3834 | # Install dependencies
3835 | npm install @anthropic-ai/sdk @modelcontextprotocol/sdk dotenv
3836 |
3837 | # Install dev dependencies
3838 | npm install -D @types/node typescript
3839 |
3840 | # Create source file
3841 | new-item index.ts
3842 | ```
3843 | </CodeGroup>
3844 |
3845 | Update your `package.json` to set `type: "module"` and a build script:
3846 |
3847 | ```json package.json
3848 | {
3849 | "type": "module",
3850 | "scripts": {
3851 | "build": "tsc && chmod 755 build/index.js"
3852 | }
3853 | }
3854 | ```
3855 |
3856 | Create a `tsconfig.json` in the root of your project:
3857 |
3858 | ```json tsconfig.json
3859 | {
3860 | "compilerOptions": {
3861 | "target": "ES2022",
3862 | "module": "Node16",
3863 | "moduleResolution": "Node16",
3864 | "outDir": "./build",
3865 | "rootDir": "./",
3866 | "strict": true,
3867 | "esModuleInterop": true,
3868 | "skipLibCheck": true,
3869 | "forceConsistentCasingInFileNames": true
3870 | },
3871 | "include": ["index.ts"],
3872 | "exclude": ["node_modules"]
3873 | }
3874 | ```
3875 |
3876 | ## Setting Up Your API Key
3877 |
3878 | You'll need an Anthropic API key from the [Anthropic Console](https://console.anthropic.com/settings/keys).
3879 |
3880 | Create a `.env` file to store it:
3881 |
3882 | ```bash
3883 | echo "ANTHROPIC_API_KEY=<your key here>" > .env
3884 | ```
3885 |
3886 | Add `.env` to your `.gitignore`:
3887 |
3888 | ```bash
3889 | echo ".env" >> .gitignore
3890 | ```
3891 |
3892 | <Warning>
3893 | Make sure you keep your `ANTHROPIC_API_KEY` secure!
3894 | </Warning>
3895 |
3896 | ## Creating the Client
3897 |
3898 | ### Basic Client Structure
3899 |
3900 | First, let's set up our imports and create the basic client class in `index.ts`:
3901 |
3902 | ```typescript
3903 | import { Anthropic } from "@anthropic-ai/sdk";
3904 | import {
3905 | MessageParam,
3906 | Tool,
3907 | } from "@anthropic-ai/sdk/resources/messages/messages.mjs";
3908 | import { Client } from "@modelcontextprotocol/sdk/client/index.js";
3909 | import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
3910 | import readline from "readline/promises";
3911 | import dotenv from "dotenv";
3912 |
3913 | dotenv.config();
3914 |
3915 | const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
3916 | if (!ANTHROPIC_API_KEY) {
3917 | throw new Error("ANTHROPIC_API_KEY is not set");
3918 | }
3919 |
3920 | class MCPClient {
3921 | private mcp: Client;
3922 | private anthropic: Anthropic;
3923 | private transport: StdioClientTransport | null = null;
3924 | private tools: Tool[] = [];
3925 |
3926 | constructor() {
3927 | this.anthropic = new Anthropic({
3928 | apiKey: ANTHROPIC_API_KEY,
3929 | });
3930 | this.mcp = new Client({ name: "mcp-client-cli", version: "1.0.0" });
3931 | }
3932 | // methods will go here
3933 | }
3934 | ```
3935 |
3936 | ### Server Connection Management
3937 |
3938 | Next, we'll implement the method to connect to an MCP server:
3939 |
3940 | ```typescript
3941 | async connectToServer(serverScriptPath: string) {
3942 | try {
3943 | const isJs = serverScriptPath.endsWith(".js");
3944 | const isPy = serverScriptPath.endsWith(".py");
3945 | if (!isJs && !isPy) {
3946 | throw new Error("Server script must be a .js or .py file");
3947 | }
3948 | const command = isPy
3949 | ? process.platform === "win32"
3950 | ? "python"
3951 | : "python3"
3952 | : process.execPath;
3953 |
3954 | this.transport = new StdioClientTransport({
3955 | command,
3956 | args: [serverScriptPath],
3957 | });
3958 | this.mcp.connect(this.transport);
3959 |
3960 | const toolsResult = await this.mcp.listTools();
3961 | this.tools = toolsResult.tools.map((tool) => {
3962 | return {
3963 | name: tool.name,
3964 | description: tool.description,
3965 | input_schema: tool.inputSchema,
3966 | };
3967 | });
3968 | console.log(
3969 | "Connected to server with tools:",
3970 | this.tools.map(({ name }) => name)
3971 | );
3972 | } catch (e) {
3973 | console.log("Failed to connect to MCP server: ", e);
3974 | throw e;
3975 | }
3976 | }
3977 | ```
3978 |
3979 | ### Query Processing Logic
3980 |
3981 | Now let's add the core functionality for processing queries and handling tool calls:
3982 |
3983 | ```typescript
3984 | async processQuery(query: string) {
3985 | const messages: MessageParam[] = [
3986 | {
3987 | role: "user",
3988 | content: query,
3989 | },
3990 | ];
3991 |
3992 | const response = await this.anthropic.messages.create({
3993 | model: "claude-3-5-sonnet-20241022",
3994 | max_tokens: 1000,
3995 | messages,
3996 | tools: this.tools,
3997 | });
3998 |
3999 | const finalText = [];
4000 | const toolResults = [];
4001 |
4002 | for (const content of response.content) {
4003 | if (content.type === "text") {
4004 | finalText.push(content.text);
4005 | } else if (content.type === "tool_use") {
4006 | const toolName = content.name;
4007 | const toolArgs = content.input as { [x: string]: unknown } | undefined;
4008 |
4009 | const result = await this.mcp.callTool({
4010 | name: toolName,
4011 | arguments: toolArgs,
4012 | });
4013 | toolResults.push(result);
4014 | finalText.push(
4015 | `[Calling tool ${toolName} with args ${JSON.stringify(toolArgs)}]`
4016 | );
4017 |
4018 | messages.push({
4019 | role: "user",
4020 | content: result.content as string,
4021 | });
4022 |
4023 | const response = await this.anthropic.messages.create({
4024 | model: "claude-3-5-sonnet-20241022",
4025 | max_tokens: 1000,
4026 | messages,
4027 | });
4028 |
4029 | finalText.push(
4030 | response.content[0].type === "text" ? response.content[0].text : ""
4031 | );
4032 | }
4033 | }
4034 |
4035 | return finalText.join("\n");
4036 | }
4037 | ```
4038 |
4039 | ### Interactive Chat Interface
4040 |
4041 | Now we'll add the chat loop and cleanup functionality:
4042 |
4043 | ```typescript
4044 | async chatLoop() {
4045 | const rl = readline.createInterface({
4046 | input: process.stdin,
4047 | output: process.stdout,
4048 | });
4049 |
4050 | try {
4051 | console.log("\nMCP Client Started!");
4052 | console.log("Type your queries or 'quit' to exit.");
4053 |
4054 | while (true) {
4055 | const message = await rl.question("\nQuery: ");
4056 | if (message.toLowerCase() === "quit") {
4057 | break;
4058 | }
4059 | const response = await this.processQuery(message);
4060 | console.log("\n" + response);
4061 | }
4062 | } finally {
4063 | rl.close();
4064 | }
4065 | }
4066 |
4067 | async cleanup() {
4068 | await this.mcp.close();
4069 | }
4070 | ```
4071 |
4072 | ### Main Entry Point
4073 |
4074 | Finally, we'll add the main execution logic:
4075 |
4076 | ```typescript
4077 | async function main() {
4078 | if (process.argv.length < 3) {
4079 | console.log("Usage: node index.ts <path_to_server_script>");
4080 | return;
4081 | }
4082 | const mcpClient = new MCPClient();
4083 | try {
4084 | await mcpClient.connectToServer(process.argv[2]);
4085 | await mcpClient.chatLoop();
4086 | } finally {
4087 | await mcpClient.cleanup();
4088 | process.exit(0);
4089 | }
4090 | }
4091 |
4092 | main();
4093 | ```
4094 |
4095 | ## Running the Client
4096 |
4097 | To run your client with any MCP server:
4098 |
4099 | ```bash
4100 | # Build TypeScript
4101 | npm run build
4102 |
4103 | # Run the client
4104 | node build/index.js path/to/server.py # python server
4105 | node build/index.js path/to/build/index.js # node server
4106 | ```
4107 |
4108 | <Note>
4109 | If you're continuing the weather tutorial from the server quickstart, your command might look something like this: `node build/index.js .../quickstart-resources/weather-server-typescript/build/index.js`
4110 | </Note>
4111 |
4112 | **The client will:**
4113 |
4114 | 1. Connect to the specified server
4115 | 2. List available tools
4116 | 3. Start an interactive chat session where you can:
4117 | * Enter queries
4118 | * See tool executions
4119 | * Get responses from Claude
4120 |
4121 | ## How It Works
4122 |
4123 | When you submit a query:
4124 |
4125 | 1. The client gets the list of available tools from the server
4126 | 2. Your query is sent to Claude along with tool descriptions
4127 | 3. Claude decides which tools (if any) to use
4128 | 4. The client executes any requested tool calls through the server
4129 | 5. Results are sent back to Claude
4130 | 6. Claude provides a natural language response
4131 | 7. The response is displayed to you
4132 |
4133 | ## Best practices
4134 |
4135 | 1. **Error Handling**
4136 | * Use TypeScript's type system for better error detection
4137 | * Wrap tool calls in try-catch blocks
4138 | * Provide meaningful error messages
4139 | * Gracefully handle connection issues
4140 |
4141 | 2. **Security**
4142 | * Store API keys securely in `.env`
4143 | * Validate server responses
4144 | * Be cautious with tool permissions
4145 |
4146 | ## Troubleshooting
4147 |
4148 | ### Server Path Issues
4149 |
4150 | * Double-check the path to your server script is correct
4151 | * Use the absolute path if the relative path isn't working
4152 | * For Windows users, make sure to use forward slashes (/) or escaped backslashes (\\) in the path
4153 | * Verify the server file has the correct extension (.js for Node.js or .py for Python)
4154 |
4155 | Example of correct path usage:
4156 |
4157 | ```bash
4158 | # Relative path
4159 | node build/index.js ./server/build/index.js
4160 |
4161 | # Absolute path
4162 | node build/index.js /Users/username/projects/mcp-server/build/index.js
4163 |
4164 | # Windows path (either format works)
4165 | node build/index.js C:/projects/mcp-server/build/index.js
4166 | node build/index.js C:\\projects\\mcp-server\\build\\index.js
4167 | ```
4168 |
4169 | ### Response Timing
4170 |
4171 | * The first response might take up to 30 seconds to return
4172 | * This is normal and happens while:
4173 | * The server initializes
4174 | * Claude processes the query
4175 | * Tools are being executed
4176 | * Subsequent responses are typically faster
4177 | * Don't interrupt the process during this initial waiting period
4178 |
4179 | ### Common Error Messages
4180 |
4181 | If you see:
4182 |
4183 | * `Error: Cannot find module`: Check your build folder and ensure TypeScript compilation succeeded
4184 | * `Connection refused`: Ensure the server is running and the path is correct
4185 | * `Tool execution failed`: Verify the tool's required environment variables are set
4186 | * `ANTHROPIC_API_KEY is not set`: Check your .env file and environment variables
4187 | * `TypeError`: Ensure you're using the correct types for tool arguments
4188 | </Tab>
4189 |
4190 | <Tab title="Java">
4191 | <Note>
4192 | This is a quickstart demo based on Spring AI MCP auto-configuration and boot starters.
4193 | To learn how to create sync and async MCP Clients manually, consult the [Java SDK Client](/sdk/java/mcp-client) documentation
4194 | </Note>
4195 |
4196 | This example demonstrates how to build an interactive chatbot that combines Spring AI's Model Context Protocol (MCP) with the [Brave Search MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/brave-search). The application creates a conversational interface powered by Anthropic's Claude AI model that can perform internet searches through Brave Search, enabling natural language interactions with real-time web data.
4197 | [You can find the complete code for this tutorial here.](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/web-search/brave-chatbot)
4198 |
4199 | ## System Requirements
4200 |
4201 | Before starting, ensure your system meets these requirements:
4202 |
4203 | * Java 17 or higher
4204 | * Maven 3.6+
4205 | * npx package manager
4206 | * Anthropic API key (Claude)
4207 | * Brave Search API key
4208 |
4209 | ## Setting Up Your Environment
4210 |
4211 | 1. Install npx (Node Package eXecute):
4212 | First, make sure to install [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
4213 | and then run:
4214 | ```bash
4215 | npm install -g npx
4216 | ```
4217 |
4218 | 2. Clone the repository:
4219 | ```bash
4220 | git clone https://github.com/spring-projects/spring-ai-examples.git
4221 | cd model-context-protocol/brave-chatbot
4222 | ```
4223 |
4224 | 3. Set up your API keys:
4225 | ```bash
4226 | export ANTHROPIC_API_KEY='your-anthropic-api-key-here'
4227 | export BRAVE_API_KEY='your-brave-api-key-here'
4228 | ```
4229 |
4230 | 4. Build the application:
4231 | ```bash
4232 | ./mvnw clean install
4233 | ```
4234 |
4235 | 5. Run the application using Maven:
4236 | ```bash
4237 | ./mvnw spring-boot:run
4238 | ```
4239 |
4240 | <Warning>
4241 | Make sure you keep your `ANTHROPIC_API_KEY` and `BRAVE_API_KEY` keys secure!
4242 | </Warning>
4243 |
4244 | ## How it Works
4245 |
4246 | The application integrates Spring AI with the Brave Search MCP server through several components:
4247 |
4248 | ### MCP Client Configuration
4249 |
4250 | 1. Required dependencies in pom.xml:
4251 |
4252 | ```xml
4253 | <dependency>
4254 | <groupId>org.springframework.ai</groupId>
4255 | <artifactId>spring-ai-starter-mcp-client</artifactId>
4256 | </dependency>
4257 | <dependency>
4258 | <groupId>org.springframework.ai</groupId>
4259 | <artifactId>spring-ai-starter-model-anthropic</artifactId>
4260 | </dependency>
4261 | ```
4262 |
4263 | 2. Application properties (application.yml):
4264 |
4265 | ```yml
4266 | spring:
4267 | ai:
4268 | mcp:
4269 | client:
4270 | enabled: true
4271 | name: brave-search-client
4272 | version: 1.0.0
4273 | type: SYNC
4274 | request-timeout: 20s
4275 | stdio:
4276 | root-change-notification: true
4277 | servers-configuration: classpath:/mcp-servers-config.json
4278 | anthropic:
4279 | api-key: ${ANTHROPIC_API_KEY}
4280 | ```
4281 |
4282 | This activates the `spring-ai-starter-mcp-client` to create one or more `McpClient`s based on the provided server configuration.
4283 |
4284 | 3. MCP Server Configuration (`mcp-servers-config.json`):
4285 |
4286 | ```json
4287 | {
4288 | "mcpServers": {
4289 | "brave-search": {
4290 | "command": "npx",
4291 | "args": [
4292 | "-y",
4293 | "@modelcontextprotocol/server-brave-search"
4294 | ],
4295 | "env": {
4296 | "BRAVE_API_KEY": "<PUT YOUR BRAVE API KEY>"
4297 | }
4298 | }
4299 | }
4300 | }
4301 | ```
4302 |
4303 | ### Chat Implementation
4304 |
4305 | The chatbot is implemented using Spring AI's ChatClient with MCP tool integration:
4306 |
4307 | ```java
4308 | var chatClient = chatClientBuilder
4309 | .defaultSystem("You are useful assistant, expert in AI and Java.")
4310 | .defaultTools((Object[]) mcpToolAdapter.toolCallbacks())
4311 | .defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))
4312 | .build();
4313 | ```
4314 |
4315 | Key features:
4316 |
4317 | * Uses Claude AI model for natural language understanding
4318 | * Integrates Brave Search through MCP for real-time web search capabilities
4319 | * Maintains conversation memory using InMemoryChatMemory
4320 | * Runs as an interactive command-line application
4321 |
4322 | ### Build and run
4323 |
4324 | ```bash
4325 | ./mvnw clean install
4326 | java -jar ./target/ai-mcp-brave-chatbot-0.0.1-SNAPSHOT.jar
4327 | ```
4328 |
4329 | or
4330 |
4331 | ```bash
4332 | ./mvnw spring-boot:run
4333 | ```
4334 |
4335 | The application will start an interactive chat session where you can ask questions. The chatbot will use Brave Search when it needs to find information from the internet to answer your queries.
4336 |
4337 | The chatbot can:
4338 |
4339 | * Answer questions using its built-in knowledge
4340 | * Perform web searches when needed using Brave Search
4341 | * Remember context from previous messages in the conversation
4342 | * Combine information from multiple sources to provide comprehensive answers
4343 |
4344 | ### Advanced Configuration
4345 |
4346 | The MCP client supports additional configuration options:
4347 |
4348 | * Client customization through `McpSyncClientCustomizer` or `McpAsyncClientCustomizer`
4349 | * Multiple clients with multiple transport types: `STDIO` and `SSE` (Server-Sent Events)
4350 | * Integration with Spring AI's tool execution framework
4351 | * Automatic client initialization and lifecycle management
4352 |
4353 | For WebFlux-based applications, you can use the WebFlux starter instead:
4354 |
4355 | ```xml
4356 | <dependency>
4357 | <groupId>org.springframework.ai</groupId>
4358 | <artifactId>spring-ai-mcp-client-webflux-spring-boot-starter</artifactId>
4359 | </dependency>
4360 | ```
4361 |
4362 | This provides similar functionality but uses a WebFlux-based SSE transport implementation, recommended for production deployments.
4363 | </Tab>
4364 |
4365 | <Tab title="Kotlin">
4366 | [You can find the complete code for this tutorial here.](https://github.com/modelcontextprotocol/kotlin-sdk/tree/main/samples/kotlin-mcp-client)
4367 |
4368 | ## System Requirements
4369 |
4370 | Before starting, ensure your system meets these requirements:
4371 |
4372 | * Java 17 or higher
4373 | * Anthropic API key (Claude)
4374 |
4375 | ## Setting up your environment
4376 |
4377 | First, let's install `java` and `gradle` if you haven't already.
4378 | You can download `java` from [official Oracle JDK website](https://www.oracle.com/java/technologies/downloads/).
4379 | Verify your `java` installation:
4380 |
4381 | ```bash
4382 | java --version
4383 | ```
4384 |
4385 | Now, let's create and set up your project:
4386 |
4387 | <CodeGroup>
4388 | ```bash MacOS/Linux
4389 | # Create a new directory for our project
4390 | mkdir kotlin-mcp-client
4391 | cd kotlin-mcp-client
4392 |
4393 | # Initialize a new kotlin project
4394 | gradle init
4395 | ```
4396 |
4397 | ```powershell Windows
4398 | # Create a new directory for our project
4399 | md kotlin-mcp-client
4400 | cd kotlin-mcp-client
4401 | # Initialize a new kotlin project
4402 | gradle init
4403 | ```
4404 | </CodeGroup>
4405 |
4406 | After running `gradle init`, you will be presented with options for creating your project.
4407 | Select **Application** as the project type, **Kotlin** as the programming language, and **Java 17** as the Java version.
4408 |
4409 | Alternatively, you can create a Kotlin application using the [IntelliJ IDEA project wizard](https://kotlinlang.org/docs/jvm-get-started.html).
4410 |
4411 | After creating the project, add the following dependencies:
4412 |
4413 | <CodeGroup>
4414 | ```kotlin build.gradle.kts
4415 | val mcpVersion = "0.4.0"
4416 | val slf4jVersion = "2.0.9"
4417 | val anthropicVersion = "0.8.0"
4418 |
4419 | dependencies {
4420 | implementation("io.modelcontextprotocol:kotlin-sdk:$mcpVersion")
4421 | implementation("org.slf4j:slf4j-nop:$slf4jVersion")
4422 | implementation("com.anthropic:anthropic-java:$anthropicVersion")
4423 | }
4424 | ```
4425 |
4426 | ```groovy build.gradle
4427 | def mcpVersion = '0.3.0'
4428 | def slf4jVersion = '2.0.9'
4429 | def anthropicVersion = '0.8.0'
4430 | dependencies {
4431 | implementation "io.modelcontextprotocol:kotlin-sdk:$mcpVersion"
4432 | implementation "org.slf4j:slf4j-nop:$slf4jVersion"
4433 | implementation "com.anthropic:anthropic-java:$anthropicVersion"
4434 | }
4435 | ```
4436 | </CodeGroup>
4437 |
4438 | Also, add the following plugins to your build script:
4439 |
4440 | <CodeGroup>
4441 | ```kotlin build.gradle.kts
4442 | plugins {
4443 | id("com.github.johnrengelman.shadow") version "8.1.1"
4444 | }
4445 | ```
4446 |
4447 | ```groovy build.gradle
4448 | plugins {
4449 | id 'com.github.johnrengelman.shadow' version '8.1.1'
4450 | }
4451 | ```
4452 | </CodeGroup>
4453 |
4454 | ## Setting up your API key
4455 |
4456 | You'll need an Anthropic API key from the [Anthropic Console](https://console.anthropic.com/settings/keys).
4457 |
4458 | Set up your API key:
4459 |
4460 | ```bash
4461 | export ANTHROPIC_API_KEY='your-anthropic-api-key-here'
4462 | ```
4463 |
4464 | <Warning>
4465 | Make sure your keep your `ANTHROPIC_API_KEY` secure!
4466 | </Warning>
4467 |
4468 | ## Creating the Client
4469 |
4470 | ### Basic Client Structure
4471 |
4472 | First, let's create the basic client class:
4473 |
4474 | ```kotlin
4475 | class MCPClient : AutoCloseable {
4476 | private val anthropic = AnthropicOkHttpClient.fromEnv()
4477 | private val mcp: Client = Client(clientInfo = Implementation(name = "mcp-client-cli", version = "1.0.0"))
4478 | private lateinit var tools: List<ToolUnion>
4479 |
4480 | // methods will go here
4481 |
4482 | override fun close() {
4483 | runBlocking {
4484 | mcp.close()
4485 | anthropic.close()
4486 | }
4487 | }
4488 | ```
4489 |
4490 | ### Server connection management
4491 |
4492 | Next, we'll implement the method to connect to an MCP server:
4493 |
4494 | ```kotlin
4495 | suspend fun connectToServer(serverScriptPath: String) {
4496 | try {
4497 | val command = buildList {
4498 | when (serverScriptPath.substringAfterLast(".")) {
4499 | "js" -> add("node")
4500 | "py" -> add(if (System.getProperty("os.name").lowercase().contains("win")) "python" else "python3")
4501 | "jar" -> addAll(listOf("java", "-jar"))
4502 | else -> throw IllegalArgumentException("Server script must be a .js, .py or .jar file")
4503 | }
4504 | add(serverScriptPath)
4505 | }
4506 |
4507 | val process = ProcessBuilder(command).start()
4508 | val transport = StdioClientTransport(
4509 | input = process.inputStream.asSource().buffered(),
4510 | output = process.outputStream.asSink().buffered()
4511 | )
4512 |
4513 | mcp.connect(transport)
4514 |
4515 | val toolsResult = mcp.listTools()
4516 | tools = toolsResult?.tools?.map { tool ->
4517 | ToolUnion.ofTool(
4518 | Tool.builder()
4519 | .name(tool.name)
4520 | .description(tool.description ?: "")
4521 | .inputSchema(
4522 | Tool.InputSchema.builder()
4523 | .type(JsonValue.from(tool.inputSchema.type))
4524 | .properties(tool.inputSchema.properties.toJsonValue())
4525 | .putAdditionalProperty("required", JsonValue.from(tool.inputSchema.required))
4526 | .build()
4527 | )
4528 | .build()
4529 | )
4530 | } ?: emptyList()
4531 | println("Connected to server with tools: ${tools.joinToString(", ") { it.tool().get().name() }}")
4532 | } catch (e: Exception) {
4533 | println("Failed to connect to MCP server: $e")
4534 | throw e
4535 | }
4536 | }
4537 | ```
4538 |
4539 | Also create a helper function to convert from `JsonObject` to `JsonValue` for Anthropic:
4540 |
4541 | ```kotlin
4542 | private fun JsonObject.toJsonValue(): JsonValue {
4543 | val mapper = ObjectMapper()
4544 | val node = mapper.readTree(this.toString())
4545 | return JsonValue.fromJsonNode(node)
4546 | }
4547 | ```
4548 |
4549 | ### Query processing logic
4550 |
4551 | Now let's add the core functionality for processing queries and handling tool calls:
4552 |
4553 | ```kotlin
4554 | private val messageParamsBuilder: MessageCreateParams.Builder = MessageCreateParams.builder()
4555 | .model(Model.CLAUDE_3_5_SONNET_20241022)
4556 | .maxTokens(1024)
4557 |
4558 | suspend fun processQuery(query: String): String {
4559 | val messages = mutableListOf(
4560 | MessageParam.builder()
4561 | .role(MessageParam.Role.USER)
4562 | .content(query)
4563 | .build()
4564 | )
4565 |
4566 | val response = anthropic.messages().create(
4567 | messageParamsBuilder
4568 | .messages(messages)
4569 | .tools(tools)
4570 | .build()
4571 | )
4572 |
4573 | val finalText = mutableListOf<String>()
4574 | response.content().forEach { content ->
4575 | when {
4576 | content.isText() -> finalText.add(content.text().getOrNull()?.text() ?: "")
4577 |
4578 | content.isToolUse() -> {
4579 | val toolName = content.toolUse().get().name()
4580 | val toolArgs =
4581 | content.toolUse().get()._input().convert(object : TypeReference<Map<String, JsonValue>>() {})
4582 |
4583 | val result = mcp.callTool(
4584 | name = toolName,
4585 | arguments = toolArgs ?: emptyMap()
4586 | )
4587 | finalText.add("[Calling tool $toolName with args $toolArgs]")
4588 |
4589 | messages.add(
4590 | MessageParam.builder()
4591 | .role(MessageParam.Role.USER)
4592 | .content(
4593 | """
4594 | "type": "tool_result",
4595 | "tool_name": $toolName,
4596 | "result": ${result?.content?.joinToString("\n") { (it as TextContent).text ?: "" }}
4597 | """.trimIndent()
4598 | )
4599 | .build()
4600 | )
4601 |
4602 | val aiResponse = anthropic.messages().create(
4603 | messageParamsBuilder
4604 | .messages(messages)
4605 | .build()
4606 | )
4607 |
4608 | finalText.add(aiResponse.content().first().text().getOrNull()?.text() ?: "")
4609 | }
4610 | }
4611 | }
4612 |
4613 | return finalText.joinToString("\n", prefix = "", postfix = "")
4614 | }
4615 | ```
4616 |
4617 | ### Interactive chat
4618 |
4619 | We'll add the chat loop:
4620 |
4621 | ```kotlin
4622 | suspend fun chatLoop() {
4623 | println("\nMCP Client Started!")
4624 | println("Type your queries or 'quit' to exit.")
4625 |
4626 | while (true) {
4627 | print("\nQuery: ")
4628 | val message = readLine() ?: break
4629 | if (message.lowercase() == "quit") break
4630 | val response = processQuery(message)
4631 | println("\n$response")
4632 | }
4633 | }
4634 | ```
4635 |
4636 | ### Main entry point
4637 |
4638 | Finally, we'll add the main execution function:
4639 |
4640 | ```kotlin
4641 | fun main(args: Array<String>) = runBlocking {
4642 | if (args.isEmpty()) throw IllegalArgumentException("Usage: java -jar <your_path>/build/libs/kotlin-mcp-client-0.1.0-all.jar <path_to_server_script>")
4643 | val serverPath = args.first()
4644 | val client = MCPClient()
4645 | client.use {
4646 | client.connectToServer(serverPath)
4647 | client.chatLoop()
4648 | }
4649 | }
4650 | ```
4651 |
4652 | ## Running the client
4653 |
4654 | To run your client with any MCP server:
4655 |
4656 | ```bash
4657 | ./gradlew build
4658 |
4659 | # Run the client
4660 | java -jar build/libs/<your-jar-name>.jar path/to/server.jar # jvm server
4661 | java -jar build/libs/<your-jar-name>.jar path/to/server.py # python server
4662 | java -jar build/libs/<your-jar-name>.jar path/to/build/index.js # node server
4663 | ```
4664 |
4665 | <Note>
4666 | If you're continuing the weather tutorial from the server quickstart, your command might look something like this: `java -jar build/libs/kotlin-mcp-client-0.1.0-all.jar .../samples/weather-stdio-server/build/libs/weather-stdio-server-0.1.0-all.jar`
4667 | </Note>
4668 |
4669 | **The client will:**
4670 |
4671 | 1. Connect to the specified server
4672 | 2. List available tools
4673 | 3. Start an interactive chat session where you can:
4674 | * Enter queries
4675 | * See tool executions
4676 | * Get responses from Claude
4677 |
4678 | ## How it works
4679 |
4680 | Here's a high-level workflow schema:
4681 |
4682 | ```mermaid
4683 | ---
4684 | config:
4685 | theme: neutral
4686 | ---
4687 | sequenceDiagram
4688 | actor User
4689 | participant Client
4690 | participant Claude
4691 | participant MCP_Server as MCP Server
4692 | participant Tools
4693 |
4694 | User->>Client: Send query
4695 | Client<<->>MCP_Server: Get available tools
4696 | Client->>Claude: Send query with tool descriptions
4697 | Claude-->>Client: Decide tool execution
4698 | Client->>MCP_Server: Request tool execution
4699 | MCP_Server->>Tools: Execute chosen tools
4700 | Tools-->>MCP_Server: Return results
4701 | MCP_Server-->>Client: Send results
4702 | Client->>Claude: Send tool results
4703 | Claude-->>Client: Provide final response
4704 | Client-->>User: Display response
4705 | ```
4706 |
4707 | When you submit a query:
4708 |
4709 | 1. The client gets the list of available tools from the server
4710 | 2. Your query is sent to Claude along with tool descriptions
4711 | 3. Claude decides which tools (if any) to use
4712 | 4. The client executes any requested tool calls through the server
4713 | 5. Results are sent back to Claude
4714 | 6. Claude provides a natural language response
4715 | 7. The response is displayed to you
4716 |
4717 | ## Best practices
4718 |
4719 | 1. **Error Handling**
4720 | * Leverage Kotlin's type system to model errors explicitly
4721 | * Wrap external tool and API calls in `try-catch` blocks when exceptions are possible
4722 | * Provide clear and meaningful error messages
4723 | * Handle network timeouts and connection issues gracefully
4724 |
4725 | 2. **Security**
4726 | * Store API keys and secrets securely in `local.properties`, environment variables, or secret managers
4727 | * Validate all external responses to avoid unexpected or unsafe data usage
4728 | * Be cautious with permissions and trust boundaries when using tools
4729 |
4730 | ## Troubleshooting
4731 |
4732 | ### Server Path Issues
4733 |
4734 | * Double-check the path to your server script is correct
4735 | * Use the absolute path if the relative path isn't working
4736 | * For Windows users, make sure to use forward slashes (/) or escaped backslashes (\\) in the path
4737 | * Make sure that the required runtime is installed (java for Java, npm for Node.js, or uv for Python)
4738 | * Verify the server file has the correct extension (.jar for Java, .js for Node.js or .py for Python)
4739 |
4740 | Example of correct path usage:
4741 |
4742 | ```bash
4743 | # Relative path
4744 | java -jar build/libs/client.jar ./server/build/libs/server.jar
4745 |
4746 | # Absolute path
4747 | java -jar build/libs/client.jar /Users/username/projects/mcp-server/build/libs/server.jar
4748 |
4749 | # Windows path (either format works)
4750 | java -jar build/libs/client.jar C:/projects/mcp-server/build/libs/server.jar
4751 | java -jar build/libs/client.jar C:\\projects\\mcp-server\\build\\libs\\server.jar
4752 | ```
4753 |
4754 | ### Response Timing
4755 |
4756 | * The first response might take up to 30 seconds to return
4757 | * This is normal and happens while:
4758 | * The server initializes
4759 | * Claude processes the query
4760 | * Tools are being executed
4761 | * Subsequent responses are typically faster
4762 | * Don't interrupt the process during this initial waiting period
4763 |
4764 | ### Common Error Messages
4765 |
4766 | If you see:
4767 |
4768 | * `Connection refused`: Ensure the server is running and the path is correct
4769 | * `Tool execution failed`: Verify the tool's required environment variables are set
4770 | * `ANTHROPIC_API_KEY is not set`: Check your environment variables
4771 | </Tab>
4772 |
4773 | <Tab title="C#">
4774 | [You can find the complete code for this tutorial here.](https://github.io/modelcontextprotocol/csharp-sdk/tree/main/samples/QuickstartClient)
4775 |
4776 | ## System Requirements
4777 |
4778 | Before starting, ensure your system meets these requirements:
4779 |
4780 | * .NET 8.0 or higher
4781 | * Anthropic API key (Claude)
4782 | * Windows, Linux, or MacOS
4783 |
4784 | ## Setting up your environment
4785 |
4786 | First, create a new .NET project:
4787 |
4788 | ```bash
4789 | dotnet new console -n QuickstartClient
4790 | cd QuickstartClient
4791 | ```
4792 |
4793 | Then, add the required dependencies to your project:
4794 |
4795 | ```bash
4796 | dotnet add package ModelContextProtocol --prerelease
4797 | dotnet add package Anthropic.SDK
4798 | dotnet add package Microsoft.Extensions.Hosting
4799 | ```
4800 |
4801 | ## Setting up your API key
4802 |
4803 | You'll need an Anthropic API key from the [Anthropic Console](https://console.anthropic.com/settings/keys).
4804 |
4805 | ```bash
4806 | dotnet user-secrets init
4807 | dotnet user-secrets set "ANTHROPIC_API_KEY" "<your key here>"
4808 | ```
4809 |
4810 | ## Creating the Client
4811 |
4812 | ### Basic Client Structure
4813 |
4814 | First, let's setup the basic client class:
4815 |
4816 | ```csharp
4817 | using Microsoft.Extensions.Configuration;
4818 | using Microsoft.Extensions.Hosting;
4819 |
4820 | var builder = Host.CreateEmptyApplicationBuilder(settings: null);
4821 |
4822 | builder.Configuration
4823 | .AddUserSecrets<Program>();
4824 | ```
4825 |
4826 | This creates the beginnings of a .NET console application that can read the API key from user secrets.
4827 |
4828 | Next, we'll setup the MCP Client:
4829 |
4830 | ```csharp
4831 | var (command, arguments) = args switch
4832 | {
4833 | [var script] when script.EndsWith(".py") => ("python", script),
4834 | [var script] when script.EndsWith(".js") => ("node", script),
4835 | [var script] when Directory.Exists(script) || (File.Exists(script) && script.EndsWith(".csproj")) => ("dotnet", $"run --project {script} --no-build"),
4836 | _ => throw new NotSupportedException("An unsupported server script was provided. Supported scripts are .py, .js, or .csproj")
4837 | };
4838 |
4839 | await using var mcpClient = await McpClientFactory.CreateAsync(new()
4840 | {
4841 | Id = "demo-server",
4842 | Name = "Demo Server",
4843 | TransportType = TransportTypes.StdIo,
4844 | TransportOptions = new()
4845 | {
4846 | ["command"] = command,
4847 | ["arguments"] = arguments,
4848 | }
4849 | });
4850 |
4851 | var tools = await mcpClient.ListToolsAsync();
4852 | foreach (var tool in tools)
4853 | {
4854 | Console.WriteLine($"Connected to server with tools: {tool.Name}");
4855 | }
4856 | ```
4857 |
4858 | <Note>
4859 | Be sure to add the `using` statements for the namespaces:
4860 |
4861 | ```csharp
4862 | using ModelContextProtocol.Client;
4863 | using ModelContextProtocol.Protocol.Transport;
4864 | ```
4865 | </Note>
4866 |
4867 | This configures a MCP client that will connect to a server that is provided as a command line argument. It then lists the available tools from the connected server.
4868 |
4869 | ### Query processing logic
4870 |
4871 | Now let's add the core functionality for processing queries and handling tool calls:
4872 |
4873 | ```csharp
4874 | using IChatClient anthropicClient = new AnthropicClient(new APIAuthentication(builder.Configuration["ANTHROPIC_API_KEY"]))
4875 | .Messages
4876 | .AsBuilder()
4877 | .UseFunctionInvocation()
4878 | .Build();
4879 |
4880 | var options = new ChatOptions
4881 | {
4882 | MaxOutputTokens = 1000,
4883 | ModelId = "claude-3-5-sonnet-20241022",
4884 | Tools = [.. tools]
4885 | };
4886 |
4887 | while (true)
4888 | {
4889 | Console.WriteLine("MCP Client Started!");
4890 | Console.WriteLine("Type your queries or 'quit' to exit.");
4891 |
4892 | string? query = Console.ReadLine();
4893 |
4894 | if (string.IsNullOrWhiteSpace(query))
4895 | {
4896 | continue;
4897 | }
4898 | if (string.Equals(query, "quit", StringComparison.OrdinalIgnoreCase))
4899 | {
4900 | break;
4901 | }
4902 |
4903 | var response = anthropicClient.GetStreamingResponseAsync(query, options);
4904 |
4905 | await foreach (var message in response)
4906 | {
4907 | Console.Write(message.Text);
4908 | }
4909 | Console.WriteLine();
4910 | }
4911 | ```
4912 |
4913 | ## Key Components Explained
4914 |
4915 | ### 1. Client Initialization
4916 |
4917 | * The client is initialized using `McpClientFactory.CreateAsync()`, which sets up the transport type and command to run the server.
4918 |
4919 | ### 2. Server Connection
4920 |
4921 | * Supports Python, Node.js, and .NET servers.
4922 | * The server is started using the command specified in the arguments.
4923 | * Configures to use stdio for communication with the server.
4924 | * Initializes the session and available tools.
4925 |
4926 | ### 3. Query Processing
4927 |
4928 | * Leverages [Microsoft.Extensions.AI](https://learn.microsoft.com/dotnet/ai/ai-extensions) for the chat client.
4929 | * Configures the `IChatClient` to use automatic tool (function) invocation.
4930 | * The client reads user input and sends it to the server.
4931 | * The server processes the query and returns a response.
4932 | * The response is displayed to the user.
4933 |
4934 | ### Running the Client
4935 |
4936 | To run your client with any MCP server:
4937 |
4938 | ```bash
4939 | dotnet run -- path/to/server.csproj # dotnet server
4940 | dotnet run -- path/to/server.py # python server
4941 | dotnet run -- path/to/server.js # node server
4942 | ```
4943 |
4944 | <Note>
4945 | If you're continuing the weather tutorial from the server quickstart, your command might look something like this: `dotnet run -- path/to/QuickstartWeatherServer`.
4946 | </Note>
4947 |
4948 | The client will:
4949 |
4950 | 1. Connect to the specified server
4951 | 2. List available tools
4952 | 3. Start an interactive chat session where you can:
4953 | * Enter queries
4954 | * See tool executions
4955 | * Get responses from Claude
4956 | 4. Exit the session when done
4957 |
4958 | Here's an example of what it should look like it connected to a weather server quickstart:
4959 |
4960 | <Frame>
4961 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-dotnet-client.png" />
4962 | </Frame>
4963 | </Tab>
4964 | </Tabs>
4965 |
4966 | ## Next steps
4967 |
4968 | <CardGroup cols={2}>
4969 | <Card title="Example servers" icon="grid" href="/examples">
4970 | Check out our gallery of official MCP servers and implementations
4971 | </Card>
4972 |
4973 | <Card title="Clients" icon="cubes" href="/clients">
4974 | View the list of clients that support MCP integrations
4975 | </Card>
4976 |
4977 | <Card title="Building MCP with LLMs" icon="comments" href="/tutorials/building-mcp-with-llms">
4978 | Learn how to use LLMs like Claude to speed up your MCP development
4979 | </Card>
4980 |
4981 | <Card title="Core architecture" icon="sitemap" href="/docs/concepts/architecture">
4982 | Understand how MCP connects clients, servers, and LLMs
4983 | </Card>
4984 | </CardGroup>
4985 |
4986 |
4987 | # For Server Developers
4988 | Source: https://modelcontextprotocol.io/quickstart/server
4989 |
4990 | Get started building your own server to use in Claude for Desktop and other clients.
4991 |
4992 | In this tutorial, we'll build a simple MCP weather server and connect it to a host, Claude for Desktop. We'll start with a basic setup, and then progress to more complex use cases.
4993 |
4994 | ### What we'll be building
4995 |
4996 | Many LLMs do not currently have the ability to fetch the forecast and severe weather alerts. Let's use MCP to solve that!
4997 |
4998 | 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):
4999 |
5000 | <Frame>
5001 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/weather-alerts.png" />
5002 | </Frame>
5003 |
5004 | <Frame>
5005 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/current-weather.png" />
5006 | </Frame>
5007 |
5008 | <Note>
5009 | Servers can connect to any client. We've chosen Claude for Desktop here for simplicity, but we also have guides on [building your own client](/quickstart/client) as well as a [list of other clients here](/clients).
5010 | </Note>
5011 |
5012 | <Accordion title="Why Claude for Desktop and not Claude.ai?">
5013 | Because servers are locally run, MCP currently only supports desktop hosts. Remote hosts are in active development.
5014 | </Accordion>
5015 |
5016 | ### Core MCP Concepts
5017 |
5018 | MCP servers can provide three main types of capabilities:
5019 |
5020 | 1. **Resources**: File-like data that can be read by clients (like API responses or file contents)
5021 | 2. **Tools**: Functions that can be called by the LLM (with user approval)
5022 | 3. **Prompts**: Pre-written templates that help users accomplish specific tasks
5023 |
5024 | This tutorial will primarily focus on tools.
5025 |
5026 | <Tabs>
5027 | <Tab title="Python">
5028 | Let's get started with building our weather server! [You can find the complete code for what we'll be building here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weather-server-python)
5029 |
5030 | ### Prerequisite knowledge
5031 |
5032 | This quickstart assumes you have familiarity with:
5033 |
5034 | * Python
5035 | * LLMs like Claude
5036 |
5037 | ### System requirements
5038 |
5039 | * Python 3.10 or higher installed.
5040 | * You must use the Python MCP SDK 1.2.0 or higher.
5041 |
5042 | ### Set up your environment
5043 |
5044 | First, let's install `uv` and set up our Python project and environment:
5045 |
5046 | <CodeGroup>
5047 | ```bash MacOS/Linux
5048 | curl -LsSf https://astral.sh/uv/install.sh | sh
5049 | ```
5050 |
5051 | ```powershell Windows
5052 | powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
5053 | ```
5054 | </CodeGroup>
5055 |
5056 | Make sure to restart your terminal afterwards to ensure that the `uv` command gets picked up.
5057 |
5058 | Now, let's create and set up our project:
5059 |
5060 | <CodeGroup>
5061 | ```bash MacOS/Linux
5062 | # Create a new directory for our project
5063 | uv init weather
5064 | cd weather
5065 |
5066 | # Create virtual environment and activate it
5067 | uv venv
5068 | source .venv/bin/activate
5069 |
5070 | # Install dependencies
5071 | uv add "mcp[cli]" httpx
5072 |
5073 | # Create our server file
5074 | touch weather.py
5075 | ```
5076 |
5077 | ```powershell Windows
5078 | # Create a new directory for our project
5079 | uv init weather
5080 | cd weather
5081 |
5082 | # Create virtual environment and activate it
5083 | uv venv
5084 | .venv\Scripts\activate
5085 |
5086 | # Install dependencies
5087 | uv add mcp[cli] httpx
5088 |
5089 | # Create our server file
5090 | new-item weather.py
5091 | ```
5092 | </CodeGroup>
5093 |
5094 | Now let's dive into building your server.
5095 |
5096 | ## Building your server
5097 |
5098 | ### Importing packages and setting up the instance
5099 |
5100 | Add these to the top of your `weather.py`:
5101 |
5102 | ```python
5103 | from typing import Any
5104 | import httpx
5105 | from mcp.server.fastmcp import FastMCP
5106 |
5107 | # Initialize FastMCP server
5108 | mcp = FastMCP("weather")
5109 |
5110 | # Constants
5111 | NWS_API_BASE = "https://api.weather.gov"
5112 | USER_AGENT = "weather-app/1.0"
5113 | ```
5114 |
5115 | The FastMCP class uses Python type hints and docstrings to automatically generate tool definitions, making it easy to create and maintain MCP tools.
5116 |
5117 | ### Helper functions
5118 |
5119 | Next, let's add our helper functions for querying and formatting the data from the National Weather Service API:
5120 |
5121 | ```python
5122 | async def make_nws_request(url: str) -> dict[str, Any] | None:
5123 | """Make a request to the NWS API with proper error handling."""
5124 | headers = {
5125 | "User-Agent": USER_AGENT,
5126 | "Accept": "application/geo+json"
5127 | }
5128 | async with httpx.AsyncClient() as client:
5129 | try:
5130 | response = await client.get(url, headers=headers, timeout=30.0)
5131 | response.raise_for_status()
5132 | return response.json()
5133 | except Exception:
5134 | return None
5135 |
5136 | def format_alert(feature: dict) -> str:
5137 | """Format an alert feature into a readable string."""
5138 | props = feature["properties"]
5139 | return f"""
5140 | Event: {props.get('event', 'Unknown')}
5141 | Area: {props.get('areaDesc', 'Unknown')}
5142 | Severity: {props.get('severity', 'Unknown')}
5143 | Description: {props.get('description', 'No description available')}
5144 | Instructions: {props.get('instruction', 'No specific instructions provided')}
5145 | """
5146 | ```
5147 |
5148 | ### Implementing tool execution
5149 |
5150 | The tool execution handler is responsible for actually executing the logic of each tool. Let's add it:
5151 |
5152 | ```python
5153 | @mcp.tool()
5154 | async def get_alerts(state: str) -> str:
5155 | """Get weather alerts for a US state.
5156 |
5157 | Args:
5158 | state: Two-letter US state code (e.g. CA, NY)
5159 | """
5160 | url = f"{NWS_API_BASE}/alerts/active/area/{state}"
5161 | data = await make_nws_request(url)
5162 |
5163 | if not data or "features" not in data:
5164 | return "Unable to fetch alerts or no alerts found."
5165 |
5166 | if not data["features"]:
5167 | return "No active alerts for this state."
5168 |
5169 | alerts = [format_alert(feature) for feature in data["features"]]
5170 | return "\n---\n".join(alerts)
5171 |
5172 | @mcp.tool()
5173 | async def get_forecast(latitude: float, longitude: float) -> str:
5174 | """Get weather forecast for a location.
5175 |
5176 | Args:
5177 | latitude: Latitude of the location
5178 | longitude: Longitude of the location
5179 | """
5180 | # First get the forecast grid endpoint
5181 | points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
5182 | points_data = await make_nws_request(points_url)
5183 |
5184 | if not points_data:
5185 | return "Unable to fetch forecast data for this location."
5186 |
5187 | # Get the forecast URL from the points response
5188 | forecast_url = points_data["properties"]["forecast"]
5189 | forecast_data = await make_nws_request(forecast_url)
5190 |
5191 | if not forecast_data:
5192 | return "Unable to fetch detailed forecast."
5193 |
5194 | # Format the periods into a readable forecast
5195 | periods = forecast_data["properties"]["periods"]
5196 | forecasts = []
5197 | for period in periods[:5]: # Only show next 5 periods
5198 | forecast = f"""
5199 | {period['name']}:
5200 | Temperature: {period['temperature']}°{period['temperatureUnit']}
5201 | Wind: {period['windSpeed']} {period['windDirection']}
5202 | Forecast: {period['detailedForecast']}
5203 | """
5204 | forecasts.append(forecast)
5205 |
5206 | return "\n---\n".join(forecasts)
5207 | ```
5208 |
5209 | ### Running the server
5210 |
5211 | Finally, let's initialize and run the server:
5212 |
5213 | ```python
5214 | if __name__ == "__main__":
5215 | # Initialize and run the server
5216 | mcp.run(transport='stdio')
5217 | ```
5218 |
5219 | Your server is complete! Run `uv run weather.py` to confirm that everything's working.
5220 |
5221 | Let's now test your server from an existing MCP host, Claude for Desktop.
5222 |
5223 | ## Testing your server with Claude for Desktop
5224 |
5225 | <Note>
5226 | Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/quickstart/client) tutorial to build an MCP client that connects to the server we just built.
5227 | </Note>
5228 |
5229 | First, make sure you have Claude for Desktop installed. [You can install the latest version
5230 | here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
5231 |
5232 | 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.
5233 |
5234 | For example, if you have [VS Code](https://code.visualstudio.com/) installed:
5235 |
5236 | <Tabs>
5237 | <Tab title="MacOS/Linux">
5238 | ```bash
5239 | code ~/Library/Application\ Support/Claude/claude_desktop_config.json
5240 | ```
5241 | </Tab>
5242 |
5243 | <Tab title="Windows">
5244 | ```powershell
5245 | code $env:AppData\Claude\claude_desktop_config.json
5246 | ```
5247 | </Tab>
5248 | </Tabs>
5249 |
5250 | 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.
5251 |
5252 | In this case, we'll add our single weather server like so:
5253 |
5254 | <Tabs>
5255 | <Tab title="MacOS/Linux">
5256 | ```json Python
5257 | {
5258 | "mcpServers": {
5259 | "weather": {
5260 | "command": "uv",
5261 | "args": [
5262 | "--directory",
5263 | "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
5264 | "run",
5265 | "weather.py"
5266 | ]
5267 | }
5268 | }
5269 | }
5270 | ```
5271 | </Tab>
5272 |
5273 | <Tab title="Windows">
5274 | ```json Python
5275 | {
5276 | "mcpServers": {
5277 | "weather": {
5278 | "command": "uv",
5279 | "args": [
5280 | "--directory",
5281 | "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\weather",
5282 | "run",
5283 | "weather.py"
5284 | ]
5285 | }
5286 | }
5287 | }
5288 | ```
5289 | </Tab>
5290 | </Tabs>
5291 |
5292 | <Warning>
5293 | You may need to put the full path to the `uv` executable in the `command` field. You can get this by running `which uv` on MacOS/Linux or `where uv` on Windows.
5294 | </Warning>
5295 |
5296 | <Note>
5297 | Make sure you pass in the absolute path to your server.
5298 | </Note>
5299 |
5300 | This tells Claude for Desktop:
5301 |
5302 | 1. There's an MCP server named "weather"
5303 | 2. To launch it by running `uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather run weather.py`
5304 |
5305 | Save the file, and restart **Claude for Desktop**.
5306 | </Tab>
5307 |
5308 | <Tab title="Node">
5309 | Let's get started with building our weather server! [You can find the complete code for what we'll be building here.](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weather-server-typescript)
5310 |
5311 | ### Prerequisite knowledge
5312 |
5313 | This quickstart assumes you have familiarity with:
5314 |
5315 | * TypeScript
5316 | * LLMs like Claude
5317 |
5318 | ### System requirements
5319 |
5320 | For TypeScript, make sure you have the latest version of Node installed.
5321 |
5322 | ### Set up your environment
5323 |
5324 | First, let's install Node.js and npm if you haven't already. You can download them from [nodejs.org](https://nodejs.org/).
5325 | Verify your Node.js installation:
5326 |
5327 | ```bash
5328 | node --version
5329 | npm --version
5330 | ```
5331 |
5332 | For this tutorial, you'll need Node.js version 16 or higher.
5333 |
5334 | Now, let's create and set up our project:
5335 |
5336 | <CodeGroup>
5337 | ```bash MacOS/Linux
5338 | # Create a new directory for our project
5339 | mkdir weather
5340 | cd weather
5341 |
5342 | # Initialize a new npm project
5343 | npm init -y
5344 |
5345 | # Install dependencies
5346 | npm install @modelcontextprotocol/sdk zod
5347 | npm install -D @types/node typescript
5348 |
5349 | # Create our files
5350 | mkdir src
5351 | touch src/index.ts
5352 | ```
5353 |
5354 | ```powershell Windows
5355 | # Create a new directory for our project
5356 | md weather
5357 | cd weather
5358 |
5359 | # Initialize a new npm project
5360 | npm init -y
5361 |
5362 | # Install dependencies
5363 | npm install @modelcontextprotocol/sdk zod
5364 | npm install -D @types/node typescript
5365 |
5366 | # Create our files
5367 | md src
5368 | new-item src\index.ts
5369 | ```
5370 | </CodeGroup>
5371 |
5372 | Update your package.json to add type: "module" and a build script:
5373 |
5374 | ```json package.json
5375 | {
5376 | "type": "module",
5377 | "bin": {
5378 | "weather": "./build/index.js"
5379 | },
5380 | "scripts": {
5381 | "build": "tsc && chmod 755 build/index.js"
5382 | },
5383 | "files": [
5384 | "build"
5385 | ],
5386 | }
5387 | ```
5388 |
5389 | Create a `tsconfig.json` in the root of your project:
5390 |
5391 | ```json tsconfig.json
5392 | {
5393 | "compilerOptions": {
5394 | "target": "ES2022",
5395 | "module": "Node16",
5396 | "moduleResolution": "Node16",
5397 | "outDir": "./build",
5398 | "rootDir": "./src",
5399 | "strict": true,
5400 | "esModuleInterop": true,
5401 | "skipLibCheck": true,
5402 | "forceConsistentCasingInFileNames": true
5403 | },
5404 | "include": ["src/**/*"],
5405 | "exclude": ["node_modules"]
5406 | }
5407 | ```
5408 |
5409 | Now let's dive into building your server.
5410 |
5411 | ## Building your server
5412 |
5413 | ### Importing packages and setting up the instance
5414 |
5415 | Add these to the top of your `src/index.ts`:
5416 |
5417 | ```typescript
5418 | import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
5419 | import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
5420 | import { z } from "zod";
5421 |
5422 | const NWS_API_BASE = "https://api.weather.gov";
5423 | const USER_AGENT = "weather-app/1.0";
5424 |
5425 | // Create server instance
5426 | const server = new McpServer({
5427 | name: "weather",
5428 | version: "1.0.0",
5429 | capabilities: {
5430 | resources: {},
5431 | tools: {},
5432 | },
5433 | });
5434 | ```
5435 |
5436 | ### Helper functions
5437 |
5438 | Next, let's add our helper functions for querying and formatting the data from the National Weather Service API:
5439 |
5440 | ```typescript
5441 | // Helper function for making NWS API requests
5442 | async function makeNWSRequest<T>(url: string): Promise<T | null> {
5443 | const headers = {
5444 | "User-Agent": USER_AGENT,
5445 | Accept: "application/geo+json",
5446 | };
5447 |
5448 | try {
5449 | const response = await fetch(url, { headers });
5450 | if (!response.ok) {
5451 | throw new Error(`HTTP error! status: ${response.status}`);
5452 | }
5453 | return (await response.json()) as T;
5454 | } catch (error) {
5455 | console.error("Error making NWS request:", error);
5456 | return null;
5457 | }
5458 | }
5459 |
5460 | interface AlertFeature {
5461 | properties: {
5462 | event?: string;
5463 | areaDesc?: string;
5464 | severity?: string;
5465 | status?: string;
5466 | headline?: string;
5467 | };
5468 | }
5469 |
5470 | // Format alert data
5471 | function formatAlert(feature: AlertFeature): string {
5472 | const props = feature.properties;
5473 | return [
5474 | `Event: ${props.event || "Unknown"}`,
5475 | `Area: ${props.areaDesc || "Unknown"}`,
5476 | `Severity: ${props.severity || "Unknown"}`,
5477 | `Status: ${props.status || "Unknown"}`,
5478 | `Headline: ${props.headline || "No headline"}`,
5479 | "---",
5480 | ].join("\n");
5481 | }
5482 |
5483 | interface ForecastPeriod {
5484 | name?: string;
5485 | temperature?: number;
5486 | temperatureUnit?: string;
5487 | windSpeed?: string;
5488 | windDirection?: string;
5489 | shortForecast?: string;
5490 | }
5491 |
5492 | interface AlertsResponse {
5493 | features: AlertFeature[];
5494 | }
5495 |
5496 | interface PointsResponse {
5497 | properties: {
5498 | forecast?: string;
5499 | };
5500 | }
5501 |
5502 | interface ForecastResponse {
5503 | properties: {
5504 | periods: ForecastPeriod[];
5505 | };
5506 | }
5507 | ```
5508 |
5509 | ### Implementing tool execution
5510 |
5511 | The tool execution handler is responsible for actually executing the logic of each tool. Let's add it:
5512 |
5513 | ```typescript
5514 | // Register weather tools
5515 | server.tool(
5516 | "get-alerts",
5517 | "Get weather alerts for a state",
5518 | {
5519 | state: z.string().length(2).describe("Two-letter state code (e.g. CA, NY)"),
5520 | },
5521 | async ({ state }) => {
5522 | const stateCode = state.toUpperCase();
5523 | const alertsUrl = `${NWS_API_BASE}/alerts?area=${stateCode}`;
5524 | const alertsData = await makeNWSRequest<AlertsResponse>(alertsUrl);
5525 |
5526 | if (!alertsData) {
5527 | return {
5528 | content: [
5529 | {
5530 | type: "text",
5531 | text: "Failed to retrieve alerts data",
5532 | },
5533 | ],
5534 | };
5535 | }
5536 |
5537 | const features = alertsData.features || [];
5538 | if (features.length === 0) {
5539 | return {
5540 | content: [
5541 | {
5542 | type: "text",
5543 | text: `No active alerts for ${stateCode}`,
5544 | },
5545 | ],
5546 | };
5547 | }
5548 |
5549 | const formattedAlerts = features.map(formatAlert);
5550 | const alertsText = `Active alerts for ${stateCode}:\n\n${formattedAlerts.join("\n")}`;
5551 |
5552 | return {
5553 | content: [
5554 | {
5555 | type: "text",
5556 | text: alertsText,
5557 | },
5558 | ],
5559 | };
5560 | },
5561 | );
5562 |
5563 | server.tool(
5564 | "get-forecast",
5565 | "Get weather forecast for a location",
5566 | {
5567 | latitude: z.number().min(-90).max(90).describe("Latitude of the location"),
5568 | longitude: z.number().min(-180).max(180).describe("Longitude of the location"),
5569 | },
5570 | async ({ latitude, longitude }) => {
5571 | // Get grid point data
5572 | const pointsUrl = `${NWS_API_BASE}/points/${latitude.toFixed(4)},${longitude.toFixed(4)}`;
5573 | const pointsData = await makeNWSRequest<PointsResponse>(pointsUrl);
5574 |
5575 | if (!pointsData) {
5576 | return {
5577 | content: [
5578 | {
5579 | type: "text",
5580 | text: `Failed to retrieve grid point data for coordinates: ${latitude}, ${longitude}. This location may not be supported by the NWS API (only US locations are supported).`,
5581 | },
5582 | ],
5583 | };
5584 | }
5585 |
5586 | const forecastUrl = pointsData.properties?.forecast;
5587 | if (!forecastUrl) {
5588 | return {
5589 | content: [
5590 | {
5591 | type: "text",
5592 | text: "Failed to get forecast URL from grid point data",
5593 | },
5594 | ],
5595 | };
5596 | }
5597 |
5598 | // Get forecast data
5599 | const forecastData = await makeNWSRequest<ForecastResponse>(forecastUrl);
5600 | if (!forecastData) {
5601 | return {
5602 | content: [
5603 | {
5604 | type: "text",
5605 | text: "Failed to retrieve forecast data",
5606 | },
5607 | ],
5608 | };
5609 | }
5610 |
5611 | const periods = forecastData.properties?.periods || [];
5612 | if (periods.length === 0) {
5613 | return {
5614 | content: [
5615 | {
5616 | type: "text",
5617 | text: "No forecast periods available",
5618 | },
5619 | ],
5620 | };
5621 | }
5622 |
5623 | // Format forecast periods
5624 | const formattedForecast = periods.map((period: ForecastPeriod) =>
5625 | [
5626 | `${period.name || "Unknown"}:`,
5627 | `Temperature: ${period.temperature || "Unknown"}°${period.temperatureUnit || "F"}`,
5628 | `Wind: ${period.windSpeed || "Unknown"} ${period.windDirection || ""}`,
5629 | `${period.shortForecast || "No forecast available"}`,
5630 | "---",
5631 | ].join("\n"),
5632 | );
5633 |
5634 | const forecastText = `Forecast for ${latitude}, ${longitude}:\n\n${formattedForecast.join("\n")}`;
5635 |
5636 | return {
5637 | content: [
5638 | {
5639 | type: "text",
5640 | text: forecastText,
5641 | },
5642 | ],
5643 | };
5644 | },
5645 | );
5646 | ```
5647 |
5648 | ### Running the server
5649 |
5650 | Finally, implement the main function to run the server:
5651 |
5652 | ```typescript
5653 | async function main() {
5654 | const transport = new StdioServerTransport();
5655 | await server.connect(transport);
5656 | console.error("Weather MCP Server running on stdio");
5657 | }
5658 |
5659 | main().catch((error) => {
5660 | console.error("Fatal error in main():", error);
5661 | process.exit(1);
5662 | });
5663 | ```
5664 |
5665 | Make sure to run `npm run build` to build your server! This is a very important step in getting your server to connect.
5666 |
5667 | Let's now test your server from an existing MCP host, Claude for Desktop.
5668 |
5669 | ## Testing your server with Claude for Desktop
5670 |
5671 | <Note>
5672 | Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/quickstart/client) tutorial to build an MCP client that connects to the server we just built.
5673 | </Note>
5674 |
5675 | First, make sure you have Claude for Desktop installed. [You can install the latest version
5676 | here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
5677 |
5678 | 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.
5679 |
5680 | For example, if you have [VS Code](https://code.visualstudio.com/) installed:
5681 |
5682 | <Tabs>
5683 | <Tab title="MacOS/Linux">
5684 | ```bash
5685 | code ~/Library/Application\ Support/Claude/claude_desktop_config.json
5686 | ```
5687 | </Tab>
5688 |
5689 | <Tab title="Windows">
5690 | ```powershell
5691 | code $env:AppData\Claude\claude_desktop_config.json
5692 | ```
5693 | </Tab>
5694 | </Tabs>
5695 |
5696 | 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.
5697 |
5698 | In this case, we'll add our single weather server like so:
5699 |
5700 | <Tabs>
5701 | <Tab title="MacOS/Linux">
5702 | <CodeGroup>
5703 | ```json Node
5704 | {
5705 | "mcpServers": {
5706 | "weather": {
5707 | "command": "node",
5708 | "args": [
5709 | "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js"
5710 | ]
5711 | }
5712 | }
5713 | }
5714 | ```
5715 | </CodeGroup>
5716 | </Tab>
5717 |
5718 | <Tab title="Windows">
5719 | <CodeGroup>
5720 | ```json Node
5721 | {
5722 | "mcpServers": {
5723 | "weather": {
5724 | "command": "node",
5725 | "args": [
5726 | "C:\\PATH\\TO\\PARENT\\FOLDER\\weather\\build\\index.js"
5727 | ]
5728 | }
5729 | }
5730 | }
5731 | ```
5732 | </CodeGroup>
5733 | </Tab>
5734 | </Tabs>
5735 |
5736 | This tells Claude for Desktop:
5737 |
5738 | 1. There's an MCP server named "weather"
5739 | 2. Launch it by running `node /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js`
5740 |
5741 | Save the file, and restart **Claude for Desktop**.
5742 | </Tab>
5743 |
5744 | <Tab title="Java">
5745 | <Note>
5746 | This is a quickstart demo based on Spring AI MCP auto-configuration and boot starters.
5747 | To learn how to create sync and async MCP Servers, manually, consult the [Java SDK Server](/sdk/java/mcp-server) documentation.
5748 | </Note>
5749 |
5750 | Let's get started with building our weather server!
5751 | [You can find the complete code for what we'll be building here.](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-stdio-server)
5752 |
5753 | For more information, see the [MCP Server Boot Starter](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html) reference documentation.
5754 | For manual MCP Server implementation, refer to the [MCP Server Java SDK documentation](/sdk/java/mcp-server).
5755 |
5756 | ### System requirements
5757 |
5758 | * Java 17 or higher installed.
5759 | * [Spring Boot 3.3.x](https://docs.spring.io/spring-boot/installing.html) or higher
5760 |
5761 | ### Set up your environment
5762 |
5763 | Use the [Spring Initializer](https://start.spring.io/) to bootstrap the project.
5764 |
5765 | You will need to add the following dependencies:
5766 |
5767 | <Tabs>
5768 | <Tab title="Maven">
5769 | ```xml
5770 | <dependencies>
5771 | <dependency>
5772 | <groupId>org.springframework.ai</groupId>
5773 | <artifactId>spring-ai-starter-mcp-server</artifactId>
5774 | </dependency>
5775 |
5776 | <dependency>
5777 | <groupId>org.springframework</groupId>
5778 | <artifactId>spring-web</artifactId>
5779 | </dependency>
5780 | </dependencies>
5781 | ```
5782 | </Tab>
5783 |
5784 | <Tab title="Gradle">
5785 | ```groovy
5786 | dependencies {
5787 | implementation platform("org.springframework.ai:spring-ai-starter-mcp-server")
5788 | implementation platform("org.springframework:spring-web")
5789 | }
5790 | ```
5791 | </Tab>
5792 | </Tabs>
5793 |
5794 | Then configure your application by setting the application properties:
5795 |
5796 | <CodeGroup>
5797 | ```bash application.properties
5798 | spring.main.bannerMode=off
5799 | logging.pattern.console=
5800 | ```
5801 |
5802 | ```yaml application.yml
5803 | logging:
5804 | pattern:
5805 | console:
5806 | spring:
5807 | main:
5808 | banner-mode: off
5809 | ```
5810 | </CodeGroup>
5811 |
5812 | The [Server Configuration Properties](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html#_configuration_properties) documents all available properties.
5813 |
5814 | Now let's dive into building your server.
5815 |
5816 | ## Building your server
5817 |
5818 | ### Weather Service
5819 |
5820 | Let's implement a [WeatherService.java](https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/weather/starter-stdio-server/src/main/java/org/springframework/ai/mcp/sample/server/WeatherService.java) that uses a REST client to query the data from the National Weather Service API:
5821 |
5822 | ```java
5823 | @Service
5824 | public class WeatherService {
5825 |
5826 | private final RestClient restClient;
5827 |
5828 | public WeatherService() {
5829 | this.restClient = RestClient.builder()
5830 | .baseUrl("https://api.weather.gov")
5831 | .defaultHeader("Accept", "application/geo+json")
5832 | .defaultHeader("User-Agent", "WeatherApiClient/1.0 ([email protected])")
5833 | .build();
5834 | }
5835 |
5836 | @Tool(description = "Get weather forecast for a specific latitude/longitude")
5837 | public String getWeatherForecastByLocation(
5838 | double latitude, // Latitude coordinate
5839 | double longitude // Longitude coordinate
5840 | ) {
5841 | // Returns detailed forecast including:
5842 | // - Temperature and unit
5843 | // - Wind speed and direction
5844 | // - Detailed forecast description
5845 | }
5846 |
5847 | @Tool(description = "Get weather alerts for a US state")
5848 | public String getAlerts(
5849 | @ToolParam(description = "Two-letter US state code (e.g. CA, NY)" String state
5850 | ) {
5851 | // Returns active alerts including:
5852 | // - Event type
5853 | // - Affected area
5854 | // - Severity
5855 | // - Description
5856 | // - Safety instructions
5857 | }
5858 |
5859 | // ......
5860 | }
5861 | ```
5862 |
5863 | The `@Service` annotation with auto-register the service in your application context.
5864 | The Spring AI `@Tool` annotation, making it easy to create and maintain MCP tools.
5865 |
5866 | The auto-configuration will automatically register these tools with the MCP server.
5867 |
5868 | ### Create your Boot Application
5869 |
5870 | ```java
5871 | @SpringBootApplication
5872 | public class McpServerApplication {
5873 |
5874 | public static void main(String[] args) {
5875 | SpringApplication.run(McpServerApplication.class, args);
5876 | }
5877 |
5878 | @Bean
5879 | public ToolCallbackProvider weatherTools(WeatherService weatherService) {
5880 | return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
5881 | }
5882 | }
5883 | ```
5884 |
5885 | Uses the the `MethodToolCallbackProvider` utils to convert the `@Tools` into actionable callbacks used by the MCP server.
5886 |
5887 | ### Running the server
5888 |
5889 | Finally, let's build the server:
5890 |
5891 | ```bash
5892 | ./mvnw clean install
5893 | ```
5894 |
5895 | This will generate a `mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar` file within the `target` folder.
5896 |
5897 | Let's now test your server from an existing MCP host, Claude for Desktop.
5898 |
5899 | ## Testing your server with Claude for Desktop
5900 |
5901 | <Note>
5902 | Claude for Desktop is not yet available on Linux.
5903 | </Note>
5904 |
5905 | First, make sure you have Claude for Desktop installed.
5906 | [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.**
5907 |
5908 | We'll need to configure Claude for Desktop for whichever MCP servers you want to use.
5909 | To do this, open your Claude for Desktop App configuration at `~/Library/Application Support/Claude/claude_desktop_config.json` in a text editor.
5910 | Make sure to create the file if it doesn't exist.
5911 |
5912 | For example, if you have [VS Code](https://code.visualstudio.com/) installed:
5913 |
5914 | <Tabs>
5915 | <Tab title="MacOS/Linux">
5916 | ```bash
5917 | code ~/Library/Application\ Support/Claude/claude_desktop_config.json
5918 | ```
5919 | </Tab>
5920 |
5921 | <Tab title="Windows">
5922 | ```powershell
5923 | code $env:AppData\Claude\claude_desktop_config.json
5924 | ```
5925 | </Tab>
5926 | </Tabs>
5927 |
5928 | You'll then add your servers in the `mcpServers` key.
5929 | The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.
5930 |
5931 | In this case, we'll add our single weather server like so:
5932 |
5933 | <Tabs>
5934 | <Tab title="MacOS/Linux">
5935 | ```json java
5936 | {
5937 | "mcpServers": {
5938 | "spring-ai-mcp-weather": {
5939 | "command": "java",
5940 | "args": [
5941 | "-Dspring.ai.mcp.server.stdio=true",
5942 | "-jar",
5943 | "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar"
5944 | ]
5945 | }
5946 | }
5947 | }
5948 | ```
5949 | </Tab>
5950 |
5951 | <Tab title="Windows">
5952 | ```json java
5953 | {
5954 | "mcpServers": {
5955 | "spring-ai-mcp-weather": {
5956 | "command": "java",
5957 | "args": [
5958 | "-Dspring.ai.mcp.server.transport=STDIO",
5959 | "-jar",
5960 | "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\weather\\mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar"
5961 | ]
5962 | }
5963 | }
5964 | }
5965 | ```
5966 | </Tab>
5967 | </Tabs>
5968 |
5969 | <Note>
5970 | Make sure you pass in the absolute path to your server.
5971 | </Note>
5972 |
5973 | This tells Claude for Desktop:
5974 |
5975 | 1. There's an MCP server named "my-weather-server"
5976 | 2. To launch it by running `java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar`
5977 |
5978 | Save the file, and restart **Claude for Desktop**.
5979 |
5980 | ## Testing your server with Java client
5981 |
5982 | ### Create a MCP Client manually
5983 |
5984 | Use the `McpClient` to connect to the server:
5985 |
5986 | ```java
5987 | var stdioParams = ServerParameters.builder("java")
5988 | .args("-jar", "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar")
5989 | .build();
5990 |
5991 | var stdioTransport = new StdioClientTransport(stdioParams);
5992 |
5993 | var mcpClient = McpClient.sync(stdioTransport).build();
5994 |
5995 | mcpClient.initialize();
5996 |
5997 | ListToolsResult toolsList = mcpClient.listTools();
5998 |
5999 | CallToolResult weather = mcpClient.callTool(
6000 | new CallToolRequest("getWeatherForecastByLocation",
6001 | Map.of("latitude", "47.6062", "longitude", "-122.3321")));
6002 |
6003 | CallToolResult alert = mcpClient.callTool(
6004 | new CallToolRequest("getAlerts", Map.of("state", "NY")));
6005 |
6006 | mcpClient.closeGracefully();
6007 | ```
6008 |
6009 | ### Use MCP Client Boot Starter
6010 |
6011 | Create a new boot starter application using the `spring-ai-starter-mcp-client` dependency:
6012 |
6013 | ```xml
6014 | <dependency>
6015 | <groupId>org.springframework.ai</groupId>
6016 | <artifactId>spring-ai-starter-mcp-client</artifactId>
6017 | </dependency>
6018 | ```
6019 |
6020 | and set the `spring.ai.mcp.client.stdio.servers-configuration` property to point to your `claude_desktop_config.json`.
6021 | You can re-use the existing Anthropic Desktop configuration:
6022 |
6023 | ```properties
6024 | spring.ai.mcp.client.stdio.servers-configuration=file:PATH/TO/claude_desktop_config.json
6025 | ```
6026 |
6027 | When you start your client application, the auto-configuration will create, automatically MCP clients from the claude\_desktop\_config.json.
6028 |
6029 | For more information, see the [MCP Client Boot Starters](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-client-docs.html) reference documentation.
6030 |
6031 | ## More Java MCP Server examples
6032 |
6033 | The [starter-webflux-server](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-webflux-server) demonstrates how to create a MCP server using SSE transport.
6034 | It showcases how to define and register MCP Tools, Resources, and Prompts, using the Spring Boot's auto-configuration capabilities.
6035 | </Tab>
6036 |
6037 | <Tab title="Kotlin">
6038 | Let's get started with building our weather server! [You can find the complete code for what we'll be building here.](https://github.com/modelcontextprotocol/kotlin-sdk/tree/main/samples/weather-stdio-server)
6039 |
6040 | ### Prerequisite knowledge
6041 |
6042 | This quickstart assumes you have familiarity with:
6043 |
6044 | * Kotlin
6045 | * LLMs like Claude
6046 |
6047 | ### System requirements
6048 |
6049 | * Java 17 or higher installed.
6050 |
6051 | ### Set up your environment
6052 |
6053 | First, let's install `java` and `gradle` if you haven't already.
6054 | You can download `java` from [official Oracle JDK website](https://www.oracle.com/java/technologies/downloads/).
6055 | Verify your `java` installation:
6056 |
6057 | ```bash
6058 | java --version
6059 | ```
6060 |
6061 | Now, let's create and set up your project:
6062 |
6063 | <CodeGroup>
6064 | ```bash MacOS/Linux
6065 | # Create a new directory for our project
6066 | mkdir weather
6067 | cd weather
6068 |
6069 | # Initialize a new kotlin project
6070 | gradle init
6071 | ```
6072 |
6073 | ```powershell Windows
6074 | # Create a new directory for our project
6075 | md weather
6076 | cd weather
6077 |
6078 | # Initialize a new kotlin project
6079 | gradle init
6080 | ```
6081 | </CodeGroup>
6082 |
6083 | After running `gradle init`, you will be presented with options for creating your project.
6084 | Select **Application** as the project type, **Kotlin** as the programming language, and **Java 17** as the Java version.
6085 |
6086 | Alternatively, you can create a Kotlin application using the [IntelliJ IDEA project wizard](https://kotlinlang.org/docs/jvm-get-started.html).
6087 |
6088 | After creating the project, add the following dependencies:
6089 |
6090 | <CodeGroup>
6091 | ```kotlin build.gradle.kts
6092 | val mcpVersion = "0.4.0"
6093 | val slf4jVersion = "2.0.9"
6094 | val ktorVersion = "3.1.1"
6095 |
6096 | dependencies {
6097 | implementation("io.modelcontextprotocol:kotlin-sdk:$mcpVersion")
6098 | implementation("org.slf4j:slf4j-nop:$slf4jVersion")
6099 | implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
6100 | implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion")
6101 | }
6102 | ```
6103 |
6104 | ```groovy build.gradle
6105 | def mcpVersion = '0.3.0'
6106 | def slf4jVersion = '2.0.9'
6107 | def ktorVersion = '3.1.1'
6108 |
6109 | dependencies {
6110 | implementation "io.modelcontextprotocol:kotlin-sdk:$mcpVersion"
6111 | implementation "org.slf4j:slf4j-nop:$slf4jVersion"
6112 | implementation "io.ktor:ktor-client-content-negotiation:$ktorVersion"
6113 | implementation "io.ktor:ktor-serialization-kotlinx-json:$ktorVersion"
6114 | }
6115 | ```
6116 | </CodeGroup>
6117 |
6118 | Also, add the following plugins to your build script:
6119 |
6120 | <CodeGroup>
6121 | ```kotlin build.gradle.kts
6122 | plugins {
6123 | kotlin("plugin.serialization") version "your_version_of_kotlin"
6124 | id("com.github.johnrengelman.shadow") version "8.1.1"
6125 | }
6126 | ```
6127 |
6128 | ```groovy build.gradle
6129 | plugins {
6130 | id 'org.jetbrains.kotlin.plugin.serialization' version 'your_version_of_kotlin'
6131 | id 'com.github.johnrengelman.shadow' version '8.1.1'
6132 | }
6133 | ```
6134 | </CodeGroup>
6135 |
6136 | Now let’s dive into building your server.
6137 |
6138 | ## Building your server
6139 |
6140 | ### Setting up the instance
6141 |
6142 | Add a server initialization function:
6143 |
6144 | ```kotlin
6145 | // Main function to run the MCP server
6146 | fun `run mcp server`() {
6147 | // Create the MCP Server instance with a basic implementation
6148 | val server = Server(
6149 | Implementation(
6150 | name = "weather", // Tool name is "weather"
6151 | version = "1.0.0" // Version of the implementation
6152 | ),
6153 | ServerOptions(
6154 | capabilities = ServerCapabilities(tools = ServerCapabilities.Tools(listChanged = true))
6155 | )
6156 | )
6157 |
6158 | // Create a transport using standard IO for server communication
6159 | val transport = StdioServerTransport(
6160 | System.`in`.asInput(),
6161 | System.out.asSink().buffered()
6162 | )
6163 |
6164 | runBlocking {
6165 | server.connect(transport)
6166 | val done = Job()
6167 | server.onClose {
6168 | done.complete()
6169 | }
6170 | done.join()
6171 | }
6172 | }
6173 | ```
6174 |
6175 | ### Weather API helper functions
6176 |
6177 | Next, let's add functions and data classes for querying and converting responses from the National Weather Service API:
6178 |
6179 | ```kotlin
6180 | // Extension function to fetch forecast information for given latitude and longitude
6181 | suspend fun HttpClient.getForecast(latitude: Double, longitude: Double): List<String> {
6182 | val points = this.get("/points/$latitude,$longitude").body<Points>()
6183 | val forecast = this.get(points.properties.forecast).body<Forecast>()
6184 | return forecast.properties.periods.map { period ->
6185 | """
6186 | ${period.name}:
6187 | Temperature: ${period.temperature} ${period.temperatureUnit}
6188 | Wind: ${period.windSpeed} ${period.windDirection}
6189 | Forecast: ${period.detailedForecast}
6190 | """.trimIndent()
6191 | }
6192 | }
6193 |
6194 | // Extension function to fetch weather alerts for a given state
6195 | suspend fun HttpClient.getAlerts(state: String): List<String> {
6196 | val alerts = this.get("/alerts/active/area/$state").body<Alert>()
6197 | return alerts.features.map { feature ->
6198 | """
6199 | Event: ${feature.properties.event}
6200 | Area: ${feature.properties.areaDesc}
6201 | Severity: ${feature.properties.severity}
6202 | Description: ${feature.properties.description}
6203 | Instruction: ${feature.properties.instruction}
6204 | """.trimIndent()
6205 | }
6206 | }
6207 |
6208 | @Serializable
6209 | data class Points(
6210 | val properties: Properties
6211 | ) {
6212 | @Serializable
6213 | data class Properties(val forecast: String)
6214 | }
6215 |
6216 | @Serializable
6217 | data class Forecast(
6218 | val properties: Properties
6219 | ) {
6220 | @Serializable
6221 | data class Properties(val periods: List<Period>)
6222 |
6223 | @Serializable
6224 | data class Period(
6225 | val number: Int, val name: String, val startTime: String, val endTime: String,
6226 | val isDaytime: Boolean, val temperature: Int, val temperatureUnit: String,
6227 | val temperatureTrend: String, val probabilityOfPrecipitation: JsonObject,
6228 | val windSpeed: String, val windDirection: String,
6229 | val shortForecast: String, val detailedForecast: String,
6230 | )
6231 | }
6232 |
6233 | @Serializable
6234 | data class Alert(
6235 | val features: List<Feature>
6236 | ) {
6237 | @Serializable
6238 | data class Feature(
6239 | val properties: Properties
6240 | )
6241 |
6242 | @Serializable
6243 | data class Properties(
6244 | val event: String, val areaDesc: String, val severity: String,
6245 | val description: String, val instruction: String?,
6246 | )
6247 | }
6248 | ```
6249 |
6250 | ### Implementing tool execution
6251 |
6252 | The tool execution handler is responsible for actually executing the logic of each tool. Let's add it:
6253 |
6254 | ```kotlin
6255 | // Create an HTTP client with a default request configuration and JSON content negotiation
6256 | val httpClient = HttpClient {
6257 | defaultRequest {
6258 | url("https://api.weather.gov")
6259 | headers {
6260 | append("Accept", "application/geo+json")
6261 | append("User-Agent", "WeatherApiClient/1.0")
6262 | }
6263 | contentType(ContentType.Application.Json)
6264 | }
6265 | // Install content negotiation plugin for JSON serialization/deserialization
6266 | install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) }
6267 | }
6268 |
6269 | // Register a tool to fetch weather alerts by state
6270 | server.addTool(
6271 | name = "get_alerts",
6272 | description = """
6273 | Get weather alerts for a US state. Input is Two-letter US state code (e.g. CA, NY)
6274 | """.trimIndent(),
6275 | inputSchema = Tool.Input(
6276 | properties = buildJsonObject {
6277 | putJsonObject("state") {
6278 | put("type", "string")
6279 | put("description", "Two-letter US state code (e.g. CA, NY)")
6280 | }
6281 | },
6282 | required = listOf("state")
6283 | )
6284 | ) { request ->
6285 | val state = request.arguments["state"]?.jsonPrimitive?.content
6286 | if (state == null) {
6287 | return@addTool CallToolResult(
6288 | content = listOf(TextContent("The 'state' parameter is required."))
6289 | )
6290 | }
6291 |
6292 | val alerts = httpClient.getAlerts(state)
6293 |
6294 | CallToolResult(content = alerts.map { TextContent(it) })
6295 | }
6296 |
6297 | // Register a tool to fetch weather forecast by latitude and longitude
6298 | server.addTool(
6299 | name = "get_forecast",
6300 | description = """
6301 | Get weather forecast for a specific latitude/longitude
6302 | """.trimIndent(),
6303 | inputSchema = Tool.Input(
6304 | properties = buildJsonObject {
6305 | putJsonObject("latitude") { put("type", "number") }
6306 | putJsonObject("longitude") { put("type", "number") }
6307 | },
6308 | required = listOf("latitude", "longitude")
6309 | )
6310 | ) { request ->
6311 | val latitude = request.arguments["latitude"]?.jsonPrimitive?.doubleOrNull
6312 | val longitude = request.arguments["longitude"]?.jsonPrimitive?.doubleOrNull
6313 | if (latitude == null || longitude == null) {
6314 | return@addTool CallToolResult(
6315 | content = listOf(TextContent("The 'latitude' and 'longitude' parameters are required."))
6316 | )
6317 | }
6318 |
6319 | val forecast = httpClient.getForecast(latitude, longitude)
6320 |
6321 | CallToolResult(content = forecast.map { TextContent(it) })
6322 | }
6323 | ```
6324 |
6325 | ### Running the server
6326 |
6327 | Finally, implement the main function to run the server:
6328 |
6329 | ```kotlin
6330 | fun main() = `run mcp server`()
6331 | ```
6332 |
6333 | Make sure to run `./gradlew build` to build your server. This is a very important step in getting your server to connect.
6334 |
6335 | Let's now test your server from an existing MCP host, Claude for Desktop.
6336 |
6337 | ## Testing your server with Claude for Desktop
6338 |
6339 | <Note>
6340 | Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/quickstart/client) tutorial to build an MCP client that connects to the server we just built.
6341 | </Note>
6342 |
6343 | First, make sure you have Claude for Desktop installed. [You can install the latest version
6344 | here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
6345 |
6346 | We'll need to configure Claude for Desktop for whichever MCP servers you want to use.
6347 | To do this, open your Claude for Desktop App configuration at `~/Library/Application Support/Claude/claude_desktop_config.json` in a text editor.
6348 | Make sure to create the file if it doesn't exist.
6349 |
6350 | For example, if you have [VS Code](https://code.visualstudio.com/) installed:
6351 |
6352 | <CodeGroup>
6353 | ```bash MacOS/Linux
6354 | code ~/Library/Application\ Support/Claude/claude_desktop_config.json
6355 | ```
6356 |
6357 | ```powershell Windows
6358 | code $env:AppData\Claude\claude_desktop_config.json
6359 | ```
6360 | </CodeGroup>
6361 |
6362 | You'll then add your servers in the `mcpServers` key.
6363 | The MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.
6364 |
6365 | In this case, we'll add our single weather server like so:
6366 |
6367 | <CodeGroup>
6368 | ```json MacOS/Linux
6369 | {
6370 | "mcpServers": {
6371 | "weather": {
6372 | "command": "java",
6373 | "args": [
6374 | "-jar",
6375 | "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/libs/weather-0.1.0-all.jar"
6376 | ]
6377 | }
6378 | }
6379 | }
6380 | ```
6381 |
6382 | ```json Windows
6383 | {
6384 | "mcpServers": {
6385 | "weather": {
6386 | "command": "java",
6387 | "args": [
6388 | "-jar",
6389 | "C:\\PATH\\TO\\PARENT\\FOLDER\\weather\\build\\libs\\weather-0.1.0-all.jar"
6390 | ]
6391 | }
6392 | }
6393 | }
6394 | ```
6395 | </CodeGroup>
6396 |
6397 | This tells Claude for Desktop:
6398 |
6399 | 1. There's an MCP server named "weather"
6400 | 2. Launch it by running `java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/libs/weather-0.1.0-all.jar`
6401 |
6402 | Save the file, and restart **Claude for Desktop**.
6403 | </Tab>
6404 |
6405 | <Tab title="C#">
6406 | Let's get started with building our weather server! [You can find the complete code for what we'll be building here.](https://github.com/modelcontextprotocol/csharp-sdk/tree/main/samples/QuickstartWeatherServer)
6407 |
6408 | ### Prerequisite knowledge
6409 |
6410 | This quickstart assumes you have familiarity with:
6411 |
6412 | * C#
6413 | * LLMs like Claude
6414 | * .NET 8 or higher
6415 |
6416 | ### System requirements
6417 |
6418 | * [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) or higher installed.
6419 |
6420 | ### Set up your environment
6421 |
6422 | First, let's install `dotnet` if you haven't already. You can download `dotnet` from [official Microsoft .NET website](https://dotnet.microsoft.com/download/). Verify your `dotnet` installation:
6423 |
6424 | ```bash
6425 | dotnet --version
6426 | ```
6427 |
6428 | Now, let's create and set up your project:
6429 |
6430 | <CodeGroup>
6431 | ```bash MacOS/Linux
6432 | # Create a new directory for our project
6433 | mkdir weather
6434 | cd weather
6435 | # Initialize a new C# project
6436 | dotnet new console
6437 | ```
6438 |
6439 | ```powershell Windows
6440 | # Create a new directory for our project
6441 | mkdir weather
6442 | cd weather
6443 | # Initialize a new C# project
6444 | dotnet new console
6445 | ```
6446 | </CodeGroup>
6447 |
6448 | After running `dotnet new console`, you will be presented with a new C# project.
6449 | You can open the project in your favorite IDE, such as [Visual Studio](https://visualstudio.microsoft.com/) or [Rider](https://www.jetbrains.com/rider/).
6450 | Alternatively, you can create a C# application using the [Visual Studio project wizard](https://learn.microsoft.com/en-us/visualstudio/get-started/csharp/tutorial-console?view=vs-2022).
6451 | After creating the project, add NuGet package for the Model Context Protocol SDK and hosting:
6452 |
6453 | ```bash
6454 | # Add the Model Context Protocol SDK NuGet package
6455 | dotnet add package ModelContextProtocol --prerelease
6456 | # Add the .NET Hosting NuGet package
6457 | dotnet add package Microsoft.Extensions.Hosting
6458 | ```
6459 |
6460 | Now let’s dive into building your server.
6461 |
6462 | ## Building your server
6463 |
6464 | Open the `Program.cs` file in your project and replace its contents with the following code:
6465 |
6466 | ```csharp
6467 | using Microsoft.Extensions.DependencyInjection;
6468 | using Microsoft.Extensions.Hosting;
6469 | using ModelContextProtocol;
6470 | using System.Net.Http.Headers;
6471 |
6472 | var builder = Host.CreateEmptyApplicationBuilder(settings: null);
6473 |
6474 | builder.Services.AddMcpServer()
6475 | .WithStdioServerTransport()
6476 | .WithToolsFromAssembly();
6477 |
6478 | builder.Services.AddSingleton(_ =>
6479 | {
6480 | var client = new HttpClient() { BaseAddress = new Uri("https://api.weather.gov") };
6481 | client.DefaultRequestHeaders.UserAgent.Add(new ProductInfoHeaderValue("weather-tool", "1.0"));
6482 | return client;
6483 | });
6484 |
6485 | var app = builder.Build();
6486 |
6487 | await app.RunAsync();
6488 | ```
6489 |
6490 | <Note>
6491 | When creating the `ApplicationHostBuilder`, ensure you use `CreateEmptyApplicationBuilder` instead of `CreateDefaultBuilder`. This ensures that the server does not write any additional messages to the console. This is only neccessary for servers using STDIO transport.
6492 | </Note>
6493 |
6494 | This code sets up a basic console application that uses the Model Context Protocol SDK to create an MCP server with standard I/O transport.
6495 |
6496 | ### Weather API helper functions
6497 |
6498 | Next, define a class with the tool execution handlers for querying and converting responses from the National Weather Service API:
6499 |
6500 | ```csharp
6501 | using ModelContextProtocol.Server;
6502 | using System.ComponentModel;
6503 | using System.Net.Http.Json;
6504 | using System.Text.Json;
6505 |
6506 | namespace QuickstartWeatherServer.Tools;
6507 |
6508 | [McpServerToolType]
6509 | public static class WeatherTools
6510 | {
6511 | [McpServerTool, Description("Get weather alerts for a US state.")]
6512 | public static async Task<string> GetAlerts(
6513 | HttpClient client,
6514 | [Description("The US state to get alerts for.")] string state)
6515 | {
6516 | var jsonElement = await client.GetFromJsonAsync<JsonElement>($"/alerts/active/area/{state}");
6517 | var alerts = jsonElement.GetProperty("features").EnumerateArray();
6518 |
6519 | if (!alerts.Any())
6520 | {
6521 | return "No active alerts for this state.";
6522 | }
6523 |
6524 | return string.Join("\n--\n", alerts.Select(alert =>
6525 | {
6526 | JsonElement properties = alert.GetProperty("properties");
6527 | return $"""
6528 | Event: {properties.GetProperty("event").GetString()}
6529 | Area: {properties.GetProperty("areaDesc").GetString()}
6530 | Severity: {properties.GetProperty("severity").GetString()}
6531 | Description: {properties.GetProperty("description").GetString()}
6532 | Instruction: {properties.GetProperty("instruction").GetString()}
6533 | """;
6534 | }));
6535 | }
6536 |
6537 | [McpServerTool, Description("Get weather forecast for a location.")]
6538 | public static async Task<string> GetForecast(
6539 | HttpClient client,
6540 | [Description("Latitude of the location.")] double latitude,
6541 | [Description("Longitude of the location.")] double longitude)
6542 | {
6543 | var jsonElement = await client.GetFromJsonAsync<JsonElement>($"/points/{latitude},{longitude}");
6544 | var periods = jsonElement.GetProperty("properties").GetProperty("periods").EnumerateArray();
6545 |
6546 | return string.Join("\n---\n", periods.Select(period => $"""
6547 | {period.GetProperty("name").GetString()}
6548 | Temperature: {period.GetProperty("temperature").GetInt32()}°F
6549 | Wind: {period.GetProperty("windSpeed").GetString()} {period.GetProperty("windDirection").GetString()}
6550 | Forecast: {period.GetProperty("detailedForecast").GetString()}
6551 | """));
6552 | }
6553 | }
6554 | ```
6555 |
6556 | ### Running the server
6557 |
6558 | Finally, run the server using the following command:
6559 |
6560 | ```bash
6561 | dotnet run
6562 | ```
6563 |
6564 | This will start the server and listen for incoming requests on standard input/output.
6565 |
6566 | ## Testing your server with Claude for Desktop
6567 |
6568 | <Note>
6569 | Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/quickstart/client) tutorial to build an MCP client that connects to the server we just built.
6570 | </Note>
6571 |
6572 | First, make sure you have Claude for Desktop installed. [You can install the latest version
6573 | here.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**
6574 | 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.
6575 | For example, if you have [VS Code](https://code.visualstudio.com/) installed:
6576 |
6577 | <Tabs>
6578 | <Tab title="MacOS/Linux">
6579 | ```bash
6580 | code ~/Library/Application\ Support/Claude/claude_desktop_config.json
6581 | ```
6582 | </Tab>
6583 |
6584 | <Tab title="Windows">
6585 | ```powershell
6586 | code $env:AppData\Claude\claude_desktop_config.json
6587 | ```
6588 | </Tab>
6589 | </Tabs>
6590 |
6591 | 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.
6592 | In this case, we'll add our single weather server like so:
6593 |
6594 | <Tabs>
6595 | <Tab title="MacOS/Linux">
6596 | ```json
6597 | {
6598 | "mcpServers": {
6599 | "weather": {
6600 | "command": "dotnet",
6601 | "args": [
6602 | "run",
6603 | "--project",
6604 | "/ABSOLUTE/PATH/TO/PROJECT",
6605 | "--no-build"
6606 | ]
6607 | }
6608 | }
6609 | }
6610 | ```
6611 | </Tab>
6612 |
6613 | <Tab title="Windows">
6614 | ```json
6615 | {
6616 | "mcpServers": {
6617 | "weather": {
6618 | "command": "dotnet",
6619 | "args": [
6620 | "run",
6621 | "--project",
6622 | "C:\\ABSOLUTE\\PATH\\TO\\PROJECT",
6623 | "--no-build"
6624 | ]
6625 | }
6626 | }
6627 | }
6628 | ```
6629 | </Tab>
6630 | </Tabs>
6631 |
6632 | This tells Claude for Desktop:
6633 |
6634 | 1. There's an MCP server named "weather"
6635 | 2. Launch it by running `dotnet run /ABSOLUTE/PATH/TO/PROJECT`
6636 | Save the file, and restart **Claude for Desktop**.
6637 | </Tab>
6638 | </Tabs>
6639 |
6640 | ### Test with commands
6641 |
6642 | 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 hammer <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> icon:
6643 |
6644 | <Frame>
6645 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/visual-indicator-mcp-tools.png" />
6646 | </Frame>
6647 |
6648 | After clicking on the hammer icon, you should see two tools listed:
6649 |
6650 | <Frame>
6651 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/available-mcp-tools.png" />
6652 | </Frame>
6653 |
6654 | If your server isn't being picked up by Claude for Desktop, proceed to the [Troubleshooting](#troubleshooting) section for debugging tips.
6655 |
6656 | If the hammer icon has shown up, you can now test your server by running the following commands in Claude for Desktop:
6657 |
6658 | * What's the weather in Sacramento?
6659 | * What are the active weather alerts in Texas?
6660 |
6661 | <Frame>
6662 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/current-weather.png" />
6663 | </Frame>
6664 |
6665 | <Frame>
6666 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/weather-alerts.png" />
6667 | </Frame>
6668 |
6669 | <Note>
6670 | Since this is the US National Weather service, the queries will only work for US locations.
6671 | </Note>
6672 |
6673 | ## What's happening under the hood
6674 |
6675 | When you ask a question:
6676 |
6677 | 1. The client sends your question to Claude
6678 | 2. Claude analyzes the available tools and decides which one(s) to use
6679 | 3. The client executes the chosen tool(s) through the MCP server
6680 | 4. The results are sent back to Claude
6681 | 5. Claude formulates a natural language response
6682 | 6. The response is displayed to you!
6683 |
6684 | ## Troubleshooting
6685 |
6686 | <AccordionGroup>
6687 | <Accordion title="Claude for Desktop Integration Issues">
6688 | **Getting logs from Claude for Desktop**
6689 |
6690 | Claude.app logging related to MCP is written to log files in `~/Library/Logs/Claude`:
6691 |
6692 | * `mcp.log` will contain general logging about MCP connections and connection failures.
6693 | * Files named `mcp-server-SERVERNAME.log` will contain error (stderr) logging from the named server.
6694 |
6695 | You can run the following command to list recent logs and follow along with any new ones:
6696 |
6697 | ```bash
6698 | # Check Claude's logs for errors
6699 | tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
6700 | ```
6701 |
6702 | **Server not showing up in Claude**
6703 |
6704 | 1. Check your `claude_desktop_config.json` file syntax
6705 | 2. Make sure the path to your project is absolute and not relative
6706 | 3. Restart Claude for Desktop completely
6707 |
6708 | **Tool calls failing silently**
6709 |
6710 | If Claude attempts to use the tools but they fail:
6711 |
6712 | 1. Check Claude's logs for errors
6713 | 2. Verify your server builds and runs without errors
6714 | 3. Try restarting Claude for Desktop
6715 |
6716 | **None of this is working. What do I do?**
6717 |
6718 | Please refer to our [debugging guide](/docs/tools/debugging) for better debugging tools and more detailed guidance.
6719 | </Accordion>
6720 |
6721 | <Accordion title="Weather API Issues">
6722 | **Error: Failed to retrieve grid point data**
6723 |
6724 | This usually means either:
6725 |
6726 | 1. The coordinates are outside the US
6727 | 2. The NWS API is having issues
6728 | 3. You're being rate limited
6729 |
6730 | Fix:
6731 |
6732 | * Verify you're using US coordinates
6733 | * Add a small delay between requests
6734 | * Check the NWS API status page
6735 |
6736 | **Error: No active alerts for \[STATE]**
6737 |
6738 | This isn't an error - it just means there are no current weather alerts for that state. Try a different state or check during severe weather.
6739 | </Accordion>
6740 | </AccordionGroup>
6741 |
6742 | <Note>
6743 | For more advanced troubleshooting, check out our guide on [Debugging MCP](/docs/tools/debugging)
6744 | </Note>
6745 |
6746 | ## Next steps
6747 |
6748 | <CardGroup cols={2}>
6749 | <Card title="Building a client" icon="outlet" href="/quickstart/client">
6750 | Learn how to build your own MCP client that can connect to your server
6751 | </Card>
6752 |
6753 | <Card title="Example servers" icon="grid" href="/examples">
6754 | Check out our gallery of official MCP servers and implementations
6755 | </Card>
6756 |
6757 | <Card title="Debugging Guide" icon="bug" href="/docs/tools/debugging">
6758 | Learn how to effectively debug MCP servers and integrations
6759 | </Card>
6760 |
6761 | <Card title="Building MCP with LLMs" icon="comments" href="/tutorials/building-mcp-with-llms">
6762 | Learn how to use LLMs like Claude to speed up your MCP development
6763 | </Card>
6764 | </CardGroup>
6765 |
6766 |
6767 | # For Claude Desktop Users
6768 | Source: https://modelcontextprotocol.io/quickstart/user
6769 |
6770 | Get started using pre-built servers in Claude for Desktop.
6771 |
6772 | In this tutorial, you will extend [Claude for Desktop](https://claude.ai/download) so that it can read from your computer's file system, write new files, move files, and even search files.
6773 |
6774 | <Frame>
6775 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-filesystem.png" />
6776 | </Frame>
6777 |
6778 | Don't worry — it will ask you for your permission before executing these actions!
6779 |
6780 | ## 1. Download Claude for Desktop
6781 |
6782 | Start by downloading [Claude for Desktop](https://claude.ai/download), choosing either macOS or Windows. (Linux is not yet supported for Claude for Desktop.)
6783 |
6784 | Follow the installation instructions.
6785 |
6786 | If you already have Claude for Desktop, make sure it's on the latest version by clicking on the Claude menu on your computer and selecting "Check for Updates..."
6787 |
6788 | <Accordion title="Why Claude for Desktop and not Claude.ai?">
6789 | Because servers are locally run, MCP currently only supports desktop hosts. Remote hosts are in active development.
6790 | </Accordion>
6791 |
6792 | ## 2. Add the Filesystem MCP Server
6793 |
6794 | To add this filesystem functionality, we will be installing a pre-built [Filesystem MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) to Claude for Desktop. This is one of dozens of [servers](https://github.com/modelcontextprotocol/servers/tree/main) created by Anthropic and the community.
6795 |
6796 | Get started by opening up the Claude menu on your computer and select "Settings..." Please note that these are not the Claude Account Settings found in the app window itself.
6797 |
6798 | This is what it should look like on a Mac:
6799 |
6800 | <Frame style={{ textAlign: 'center' }}>
6801 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-menu.png" width="400" />
6802 | </Frame>
6803 |
6804 | Click on "Developer" in the left-hand bar of the Settings pane, and then click on "Edit Config":
6805 |
6806 | <Frame>
6807 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-developer.png" />
6808 | </Frame>
6809 |
6810 | This will create a configuration file at:
6811 |
6812 | * macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
6813 | * Windows: `%APPDATA%\Claude\claude_desktop_config.json`
6814 |
6815 | if you don't already have one, and will display the file in your file system.
6816 |
6817 | Open up the configuration file in any text editor. Replace the file contents with this:
6818 |
6819 | <Tabs>
6820 | <Tab title="MacOS/Linux">
6821 | ```json
6822 | {
6823 | "mcpServers": {
6824 | "filesystem": {
6825 | "command": "npx",
6826 | "args": [
6827 | "-y",
6828 | "@modelcontextprotocol/server-filesystem",
6829 | "/Users/username/Desktop",
6830 | "/Users/username/Downloads"
6831 | ]
6832 | }
6833 | }
6834 | }
6835 | ```
6836 | </Tab>
6837 |
6838 | <Tab title="Windows">
6839 | ```json
6840 | {
6841 | "mcpServers": {
6842 | "filesystem": {
6843 | "command": "npx",
6844 | "args": [
6845 | "-y",
6846 | "@modelcontextprotocol/server-filesystem",
6847 | "C:\\Users\\username\\Desktop",
6848 | "C:\\Users\\username\\Downloads"
6849 | ]
6850 | }
6851 | }
6852 | }
6853 | ```
6854 | </Tab>
6855 | </Tabs>
6856 |
6857 | Make sure to replace `username` with your computer's username. The paths should point to valid directories that you want Claude to be able to access and modify. It's set up to work for Desktop and Downloads, but you can add more paths as well.
6858 |
6859 | You will also need [Node.js](https://nodejs.org) on your computer for this to run properly. To verify you have Node installed, open the command line on your computer.
6860 |
6861 | * On macOS, open the Terminal from your Applications folder
6862 | * On Windows, press Windows + R, type "cmd", and press Enter
6863 |
6864 | Once in the command line, verify you have Node installed by entering in the following command:
6865 |
6866 | ```bash
6867 | node --version
6868 | ```
6869 |
6870 | If you get an error saying "command not found" or "node is not recognized", download Node from [nodejs.org](https://nodejs.org/).
6871 |
6872 | <Tip>
6873 | **How does the configuration file work?**
6874 |
6875 | This configuration file tells Claude for Desktop which MCP servers to start up every time you start the application. In this case, we have added one server called "filesystem" that will use the Node `npx` command to install and run `@modelcontextprotocol/server-filesystem`. This server, described [here](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem), will let you access your file system in Claude for Desktop.
6876 | </Tip>
6877 |
6878 | <Warning>
6879 | **Command Privileges**
6880 |
6881 | Claude for Desktop will run the commands in the configuration file with the permissions of your user account, and access to your local files. Only add commands if you understand and trust the source.
6882 | </Warning>
6883 |
6884 | ## 3. Restart Claude
6885 |
6886 | After updating your configuration file, you need to restart Claude for Desktop.
6887 |
6888 | Upon restarting, you should see a hammer <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/claude-desktop-mcp-hammer-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> icon in the bottom right corner of the input box:
6889 |
6890 | <Frame>
6891 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-hammer.png" />
6892 | </Frame>
6893 |
6894 | After clicking on the hammer icon, you should see the tools that come with the Filesystem MCP Server:
6895 |
6896 | <Frame style={{ textAlign: 'center' }}>
6897 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-tools.png" width="400" />
6898 | </Frame>
6899 |
6900 | If your server isn't being picked up by Claude for Desktop, proceed to the [Troubleshooting](#troubleshooting) section for debugging tips.
6901 |
6902 | ## 4. Try it out!
6903 |
6904 | You can now talk to Claude and ask it about your filesystem. It should know when to call the relevant tools.
6905 |
6906 | Things you might try asking Claude:
6907 |
6908 | * Can you write a poem and save it to my desktop?
6909 | * What are some work-related files in my downloads folder?
6910 | * Can you take all the images on my desktop and move them to a new folder called "Images"?
6911 |
6912 | As needed, Claude will call the relevant tools and seek your approval before taking an action:
6913 |
6914 | <Frame style={{ textAlign: 'center' }}>
6915 | <img src="https://mintlify.s3.us-west-1.amazonaws.com/mcp/images/quickstart-approve.png" width="500" />
6916 | </Frame>
6917 |
6918 | ## Troubleshooting
6919 |
6920 | <AccordionGroup>
6921 | <Accordion title="Server not showing up in Claude / hammer icon missing">
6922 | 1. Restart Claude for Desktop completely
6923 | 2. Check your `claude_desktop_config.json` file syntax
6924 | 3. Make sure the file paths included in `claude_desktop_config.json` are valid and that they are absolute and not relative
6925 | 4. Look at [logs](#getting-logs-from-claude-for-desktop) to see why the server is not connecting
6926 | 5. In your command line, try manually running the server (replacing `username` as you did in `claude_desktop_config.json`) to see if you get any errors:
6927 |
6928 | <Tabs>
6929 | <Tab title="MacOS/Linux">
6930 | ```bash
6931 | npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads
6932 | ```
6933 | </Tab>
6934 |
6935 | <Tab title="Windows">
6936 | ```bash
6937 | npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Desktop C:\Users\username\Downloads
6938 | ```
6939 | </Tab>
6940 | </Tabs>
6941 | </Accordion>
6942 |
6943 | <Accordion title="Getting logs from Claude for Desktop">
6944 | Claude.app logging related to MCP is written to log files in:
6945 |
6946 | * macOS: `~/Library/Logs/Claude`
6947 |
6948 | * Windows: `%APPDATA%\Claude\logs`
6949 |
6950 | * `mcp.log` will contain general logging about MCP connections and connection failures.
6951 |
6952 | * Files named `mcp-server-SERVERNAME.log` will contain error (stderr) logging from the named server.
6953 |
6954 | You can run the following command to list recent logs and follow along with any new ones (on Windows, it will only show recent logs):
6955 |
6956 | <Tabs>
6957 | <Tab title="MacOS/Linux">
6958 | ```bash
6959 | # Check Claude's logs for errors
6960 | tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
6961 | ```
6962 | </Tab>
6963 |
6964 | <Tab title="Windows">
6965 | ```bash
6966 | type "%APPDATA%\Claude\logs\mcp*.log"
6967 | ```
6968 | </Tab>
6969 | </Tabs>
6970 | </Accordion>
6971 |
6972 | <Accordion title="Tool calls failing silently">
6973 | If Claude attempts to use the tools but they fail:
6974 |
6975 | 1. Check Claude's logs for errors
6976 | 2. Verify your server builds and runs without errors
6977 | 3. Try restarting Claude for Desktop
6978 | </Accordion>
6979 |
6980 | <Accordion title="None of this is working. What do I do?">
6981 | Please refer to our [debugging guide](/docs/tools/debugging) for better debugging tools and more detailed guidance.
6982 | </Accordion>
6983 |
6984 | <Accordion title="ENOENT error and `${APPDATA}` in paths on Windows">
6985 | If your configured server fails to load, and you see within its logs an error referring to `${APPDATA}` within a path, you may need to add the expanded value of `%APPDATA%` to your `env` key in `claude_desktop_config.json`:
6986 |
6987 | ```json
6988 | {
6989 | "brave-search": {
6990 | "command": "npx",
6991 | "args": ["-y", "@modelcontextprotocol/server-brave-search"],
6992 | "env": {
6993 | "APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
6994 | "BRAVE_API_KEY": "..."
6995 | }
6996 | }
6997 | }
6998 | ```
6999 |
7000 | With this change in place, launch Claude Desktop once again.
7001 |
7002 | <Warning>
7003 | **NPM should be installed globally**
7004 |
7005 | The `npx` command may continue to fail if you have not installed NPM globally. If NPM is already installed globally, you will find `%APPDATA%\npm` exists on your system. If not, you can install NPM globally by running the following command:
7006 |
7007 | ```bash
7008 | npm install -g npm
7009 | ```
7010 | </Warning>
7011 | </Accordion>
7012 | </AccordionGroup>
7013 |
7014 | ## Next steps
7015 |
7016 | <CardGroup cols={2}>
7017 | <Card title="Explore other servers" icon="grid" href="/examples">
7018 | Check out our gallery of official MCP servers and implementations
7019 | </Card>
7020 |
7021 | <Card title="Build your own server" icon="code" href="/quickstart/server">
7022 | Now build your own custom server to use in Claude for Desktop and other clients
7023 | </Card>
7024 | </CardGroup>
7025 |
7026 |
7027 | # MCP Client
7028 | Source: https://modelcontextprotocol.io/sdk/java/mcp-client
7029 |
7030 | Learn how to use the Model Context Protocol (MCP) client to interact with MCP servers
7031 |
7032 | # Model Context Protocol Client
7033 |
7034 | The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers. It implements the client-side of the protocol, handling:
7035 |
7036 | * Protocol version negotiation to ensure compatibility with servers
7037 | * Capability negotiation to determine available features
7038 | * Message transport and JSON-RPC communication
7039 | * Tool discovery and execution
7040 | * Resource access and management
7041 | * Prompt system interactions
7042 | * Optional features like roots management and sampling support
7043 |
7044 | <Tip>
7045 | The core `io.modelcontextprotocol.sdk:mcp` module provides STDIO and SSE client transport implementations without requiring external web frameworks.
7046 |
7047 | Spring-specific transport implementations are available as an **optional** dependency `io.modelcontextprotocol.sdk:mcp-spring-webflux` for [Spring Framework](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) users.
7048 | </Tip>
7049 |
7050 | The client provides both synchronous and asynchronous APIs for flexibility in different application contexts.
7051 |
7052 | <Tabs>
7053 | <Tab title="Sync API">
7054 | ```java
7055 | // Create a sync client with custom configuration
7056 | McpSyncClient client = McpClient.sync(transport)
7057 | .requestTimeout(Duration.ofSeconds(10))
7058 | .capabilities(ClientCapabilities.builder()
7059 | .roots(true) // Enable roots capability
7060 | .sampling() // Enable sampling capability
7061 | .build())
7062 | .sampling(request -> new CreateMessageResult(response))
7063 | .build();
7064 |
7065 | // Initialize connection
7066 | client.initialize();
7067 |
7068 | // List available tools
7069 | ListToolsResult tools = client.listTools();
7070 |
7071 | // Call a tool
7072 | CallToolResult result = client.callTool(
7073 | new CallToolRequest("calculator",
7074 | Map.of("operation", "add", "a", 2, "b", 3))
7075 | );
7076 |
7077 | // List and read resources
7078 | ListResourcesResult resources = client.listResources();
7079 | ReadResourceResult resource = client.readResource(
7080 | new ReadResourceRequest("resource://uri")
7081 | );
7082 |
7083 | // List and use prompts
7084 | ListPromptsResult prompts = client.listPrompts();
7085 | GetPromptResult prompt = client.getPrompt(
7086 | new GetPromptRequest("greeting", Map.of("name", "Spring"))
7087 | );
7088 |
7089 | // Add/remove roots
7090 | client.addRoot(new Root("file:///path", "description"));
7091 | client.removeRoot("file:///path");
7092 |
7093 | // Close client
7094 | client.closeGracefully();
7095 | ```
7096 | </Tab>
7097 |
7098 | <Tab title="Async API">
7099 | ```java
7100 | // Create an async client with custom configuration
7101 | McpAsyncClient client = McpClient.async(transport)
7102 | .requestTimeout(Duration.ofSeconds(10))
7103 | .capabilities(ClientCapabilities.builder()
7104 | .roots(true) // Enable roots capability
7105 | .sampling() // Enable sampling capability
7106 | .build())
7107 | .sampling(request -> Mono.just(new CreateMessageResult(response)))
7108 | .toolsChangeConsumer(tools -> Mono.fromRunnable(() -> {
7109 | logger.info("Tools updated: {}", tools);
7110 | }))
7111 | .resourcesChangeConsumer(resources -> Mono.fromRunnable(() -> {
7112 | logger.info("Resources updated: {}", resources);
7113 | }))
7114 | .promptsChangeConsumer(prompts -> Mono.fromRunnable(() -> {
7115 | logger.info("Prompts updated: {}", prompts);
7116 | }))
7117 | .build();
7118 |
7119 | // Initialize connection and use features
7120 | client.initialize()
7121 | .flatMap(initResult -> client.listTools())
7122 | .flatMap(tools -> {
7123 | return client.callTool(new CallToolRequest(
7124 | "calculator",
7125 | Map.of("operation", "add", "a", 2, "b", 3)
7126 | ));
7127 | })
7128 | .flatMap(result -> {
7129 | return client.listResources()
7130 | .flatMap(resources ->
7131 | client.readResource(new ReadResourceRequest("resource://uri"))
7132 | );
7133 | })
7134 | .flatMap(resource -> {
7135 | return client.listPrompts()
7136 | .flatMap(prompts ->
7137 | client.getPrompt(new GetPromptRequest(
7138 | "greeting",
7139 | Map.of("name", "Spring")
7140 | ))
7141 | );
7142 | })
7143 | .flatMap(prompt -> {
7144 | return client.addRoot(new Root("file:///path", "description"))
7145 | .then(client.removeRoot("file:///path"));
7146 | })
7147 | .doFinally(signalType -> {
7148 | client.closeGracefully().subscribe();
7149 | })
7150 | .subscribe();
7151 | ```
7152 | </Tab>
7153 | </Tabs>
7154 |
7155 | ## Client Transport
7156 |
7157 | The transport layer handles the communication between MCP clients and servers, providing different implementations for various use cases. The client transport manages message serialization, connection establishment, and protocol-specific communication patterns.
7158 |
7159 | <Tabs>
7160 | <Tab title="STDIO">
7161 | Creates transport for in-process based communication
7162 |
7163 | ```java
7164 | ServerParameters params = ServerParameters.builder("npx")
7165 | .args("-y", "@modelcontextprotocol/server-everything", "dir")
7166 | .build();
7167 | McpTransport transport = new StdioClientTransport(params);
7168 | ```
7169 | </Tab>
7170 |
7171 | <Tab title="SSE (HttpClient)">
7172 | Creates a framework agnostic (pure Java API) SSE client transport. Included in the core mcp module.
7173 |
7174 | ```java
7175 | McpTransport transport = new HttpClientSseClientTransport("http://your-mcp-server");
7176 | ```
7177 | </Tab>
7178 |
7179 | <Tab title="SSE (WebFlux)">
7180 | Creates WebFlux-based SSE client transport. Requires the mcp-webflux-sse-transport dependency.
7181 |
7182 | ```java
7183 | WebClient.Builder webClientBuilder = WebClient.builder()
7184 | .baseUrl("http://your-mcp-server");
7185 | McpTransport transport = new WebFluxSseClientTransport(webClientBuilder);
7186 | ```
7187 | </Tab>
7188 | </Tabs>
7189 |
7190 | ## Client Capabilities
7191 |
7192 | The client can be configured with various capabilities:
7193 |
7194 | ```java
7195 | var capabilities = ClientCapabilities.builder()
7196 | .roots(true) // Enable filesystem roots support with list changes notifications
7197 | .sampling() // Enable LLM sampling support
7198 | .build();
7199 | ```
7200 |
7201 | ### Roots Support
7202 |
7203 | Roots define the boundaries of where servers can operate within the filesystem:
7204 |
7205 | ```java
7206 | // Add a root dynamically
7207 | client.addRoot(new Root("file:///path", "description"));
7208 |
7209 | // Remove a root
7210 | client.removeRoot("file:///path");
7211 |
7212 | // Notify server of roots changes
7213 | client.rootsListChangedNotification();
7214 | ```
7215 |
7216 | The roots capability allows servers to:
7217 |
7218 | * Request the list of accessible filesystem roots
7219 | * Receive notifications when the roots list changes
7220 | * Understand which directories and files they have access to
7221 |
7222 | ### Sampling Support
7223 |
7224 | Sampling enables servers to request LLM interactions ("completions" or "generations") through the client:
7225 |
7226 | ```java
7227 | // Configure sampling handler
7228 | Function<CreateMessageRequest, CreateMessageResult> samplingHandler = request -> {
7229 | // Sampling implementation that interfaces with LLM
7230 | return new CreateMessageResult(response);
7231 | };
7232 |
7233 | // Create client with sampling support
7234 | var client = McpClient.sync(transport)
7235 | .capabilities(ClientCapabilities.builder()
7236 | .sampling()
7237 | .build())
7238 | .sampling(samplingHandler)
7239 | .build();
7240 | ```
7241 |
7242 | This capability allows:
7243 |
7244 | * Servers to leverage AI capabilities without requiring API keys
7245 | * Clients to maintain control over model access and permissions
7246 | * Support for both text and image-based interactions
7247 | * Optional inclusion of MCP server context in prompts
7248 |
7249 | ## Using MCP Clients
7250 |
7251 | ### Tool Execution
7252 |
7253 | Tools are server-side functions that clients can discover and execute. The MCP client provides methods to list available tools and execute them with specific parameters. Each tool has a unique name and accepts a map of parameters.
7254 |
7255 | <Tabs>
7256 | <Tab title="Sync API">
7257 | ```java
7258 | // List available tools and their names
7259 | var tools = client.listTools();
7260 | tools.forEach(tool -> System.out.println(tool.getName()));
7261 |
7262 | // Execute a tool with parameters
7263 | var result = client.callTool("calculator", Map.of(
7264 | "operation", "add",
7265 | "a", 1,
7266 | "b", 2
7267 | ));
7268 | ```
7269 | </Tab>
7270 |
7271 | <Tab title="Async API">
7272 | ```java
7273 | // List available tools asynchronously
7274 | client.listTools()
7275 | .doOnNext(tools -> tools.forEach(tool ->
7276 | System.out.println(tool.getName())))
7277 | .subscribe();
7278 |
7279 | // Execute a tool asynchronously
7280 | client.callTool("calculator", Map.of(
7281 | "operation", "add",
7282 | "a", 1,
7283 | "b", 2
7284 | ))
7285 | .subscribe();
7286 | ```
7287 | </Tab>
7288 | </Tabs>
7289 |
7290 | ### Resource Access
7291 |
7292 | Resources represent server-side data sources that clients can access using URI templates. The MCP client provides methods to discover available resources and retrieve their contents through a standardized interface.
7293 |
7294 | <Tabs>
7295 | <Tab title="Sync API">
7296 | ```java
7297 | // List available resources and their names
7298 | var resources = client.listResources();
7299 | resources.forEach(resource -> System.out.println(resource.getName()));
7300 |
7301 | // Retrieve resource content using a URI template
7302 | var content = client.getResource("file", Map.of(
7303 | "path", "/path/to/file.txt"
7304 | ));
7305 | ```
7306 | </Tab>
7307 |
7308 | <Tab title="Async API">
7309 | ```java
7310 | // List available resources asynchronously
7311 | client.listResources()
7312 | .doOnNext(resources -> resources.forEach(resource ->
7313 | System.out.println(resource.getName())))
7314 | .subscribe();
7315 |
7316 | // Retrieve resource content asynchronously
7317 | client.getResource("file", Map.of(
7318 | "path", "/path/to/file.txt"
7319 | ))
7320 | .subscribe();
7321 | ```
7322 | </Tab>
7323 | </Tabs>
7324 |
7325 | ### Prompt System
7326 |
7327 | The prompt system enables interaction with server-side prompt templates. These templates can be discovered and executed with custom parameters, allowing for dynamic text generation based on predefined patterns.
7328 |
7329 | <Tabs>
7330 | <Tab title="Sync API">
7331 | ```java
7332 | // List available prompt templates
7333 | var prompts = client.listPrompts();
7334 | prompts.forEach(prompt -> System.out.println(prompt.getName()));
7335 |
7336 | // Execute a prompt template with parameters
7337 | var response = client.executePrompt("echo", Map.of(
7338 | "text", "Hello, World!"
7339 | ));
7340 | ```
7341 | </Tab>
7342 |
7343 | <Tab title="Async API">
7344 | ```java
7345 | // List available prompt templates asynchronously
7346 | client.listPrompts()
7347 | .doOnNext(prompts -> prompts.forEach(prompt ->
7348 | System.out.println(prompt.getName())))
7349 | .subscribe();
7350 |
7351 | // Execute a prompt template asynchronously
7352 | client.executePrompt("echo", Map.of(
7353 | "text", "Hello, World!"
7354 | ))
7355 | .subscribe();
7356 | ```
7357 | </Tab>
7358 | </Tabs>
7359 |
7360 |
7361 | # Overview
7362 | Source: https://modelcontextprotocol.io/sdk/java/mcp-overview
7363 |
7364 | Introduction to the Model Context Protocol (MCP) Java SDK
7365 |
7366 | Java SDK for the [Model Context Protocol](https://modelcontextprotocol.org/docs/concepts/architecture)
7367 | enables standardized integration between AI models and tools.
7368 |
7369 | <Note>
7370 | ### Breaking Changes in 0.8.x ⚠️
7371 |
7372 | **Note:** Version 0.8.x introduces several breaking changes including a new session-based architecture.
7373 | If you're upgrading from 0.7.0, please refer to the [Migration Guide](https://github.com/modelcontextprotocol/java-sdk/blob/main/migration-0.8.0.md) for detailed instructions.
7374 | </Note>
7375 |
7376 | ## Features
7377 |
7378 | * MCP Client and MCP Server implementations supporting:
7379 | * Protocol [version compatibility negotiation](https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle/#initialization)
7380 | * [Tool](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/) discovery, execution, list change notifications
7381 | * [Resource](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/resources/) management with URI templates
7382 | * [Roots](https://spec.modelcontextprotocol.io/specification/2024-11-05/client/roots/) list management and notifications
7383 | * [Prompt](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/prompts/) handling and management
7384 | * [Sampling](https://spec.modelcontextprotocol.io/specification/2024-11-05/client/sampling/) support for AI model interactions
7385 | * Multiple transport implementations:
7386 | * Default transports (included in core `mcp` module, no external web frameworks required):
7387 | * Stdio-based transport for process-based communication
7388 | * Java HttpClient-based SSE client transport for HTTP SSE Client-side streaming
7389 | * Servlet-based SSE server transport for HTTP SSE Server streaming
7390 | * Optional Spring-based transports (convenience if using Spring Framework):
7391 | * WebFlux SSE client and server transports for reactive HTTP streaming
7392 | * WebMVC SSE transport for servlet-based HTTP streaming
7393 | * Supports Synchronous and Asynchronous programming paradigms
7394 |
7395 | <Tip>
7396 | The core `io.modelcontextprotocol.sdk:mcp` module provides default STDIO and SSE client and server transport implementations without requiring external web frameworks.
7397 |
7398 | Spring-specific transports are available as optional dependencies for convenience when using the [Spring Framework](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html).
7399 | </Tip>
7400 |
7401 | ## Architecture
7402 |
7403 | The SDK follows a layered architecture with clear separation of concerns:
7404 |
7405 | 
7406 |
7407 | * **Client/Server Layer (McpClient/McpServer)**: Both use McpSession for sync/async operations,
7408 | with McpClient handling client-side protocol operations and McpServer managing server-side protocol operations.
7409 | * **Session Layer (McpSession)**: Manages communication patterns and state using DefaultMcpSession implementation.
7410 | * **Transport Layer (McpTransport)**: Handles JSON-RPC message serialization/deserialization via:
7411 | * StdioTransport (stdin/stdout) in the core module
7412 | * HTTP SSE transports in dedicated transport modules (Java HttpClient, Spring WebFlux, Spring WebMVC)
7413 |
7414 | The MCP Client is a key component in the Model Context Protocol (MCP) architecture, responsible for establishing and managing connections with MCP servers.
7415 | It implements the client-side of the protocol.
7416 |
7417 | 
7418 |
7419 | The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients.
7420 | It implements the server-side of the protocol.
7421 |
7422 | 
7423 |
7424 | Key Interactions:
7425 |
7426 | * **Client/Server Initialization**: Transport setup, protocol compatibility check, capability negotiation, and implementation details exchange.
7427 | * **Message Flow**: JSON-RPC message handling with validation, type-safe response processing, and error handling.
7428 | * **Resource Management**: Resource discovery, URI template-based access, subscription system, and content retrieval.
7429 |
7430 | ## Dependencies
7431 |
7432 | Add the following Maven dependency to your project:
7433 |
7434 | <Tabs>
7435 | <Tab title="Maven">
7436 | The core MCP functionality:
7437 |
7438 | ```xml
7439 | <dependency>
7440 | <groupId>io.modelcontextprotocol.sdk</groupId>
7441 | <artifactId>mcp</artifactId>
7442 | </dependency>
7443 | ```
7444 |
7445 | The core `mcp` module already includes default STDIO and SSE transport implementations and doesn't require external web frameworks.
7446 |
7447 | If you're using the Spring Framework and want to use Spring-specific transport implementations, add one of the following optional dependencies:
7448 |
7449 | ```xml
7450 | <!-- Optional: Spring WebFlux-based SSE client and server transport -->
7451 | <dependency>
7452 | <groupId>io.modelcontextprotocol.sdk</groupId>
7453 | <artifactId>mcp-spring-webflux</artifactId>
7454 | </dependency>
7455 |
7456 | <!-- Optional: Spring WebMVC-based SSE server transport -->
7457 | <dependency>
7458 | <groupId>io.modelcontextprotocol.sdk</groupId>
7459 | <artifactId>mcp-spring-webmvc</artifactId>
7460 | </dependency>
7461 | ```
7462 | </Tab>
7463 |
7464 | <Tab title="Gradle">
7465 | The core MCP functionality:
7466 |
7467 | ```groovy
7468 | dependencies {
7469 | implementation platform("io.modelcontextprotocol.sdk:mcp")
7470 | //...
7471 | }
7472 | ```
7473 |
7474 | The core `mcp` module already includes default STDIO and SSE transport implementations and doesn't require external web frameworks.
7475 |
7476 | If you're using the Spring Framework and want to use Spring-specific transport implementations, add one of the following optional dependencies:
7477 |
7478 | ```groovy
7479 | // Optional: Spring WebFlux-based SSE client and server transport
7480 | dependencies {
7481 | implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webflux")
7482 | }
7483 |
7484 | // Optional: Spring WebMVC-based SSE server transport
7485 | dependencies {
7486 | implementation platform("io.modelcontextprotocol.sdk:mcp-spring-webmvc")
7487 | }
7488 | ```
7489 | </Tab>
7490 | </Tabs>
7491 |
7492 | ### Bill of Materials (BOM)
7493 |
7494 | The Bill of Materials (BOM) declares the recommended versions of all the dependencies used by a given release.
7495 | Using the BOM from your application's build script avoids the need for you to specify and maintain the dependency versions yourself.
7496 | Instead, the version of the BOM you're using determines the utilized dependency versions.
7497 | It also ensures that you're using supported and tested versions of the dependencies by default, unless you choose to override them.
7498 |
7499 | Add the BOM to your project:
7500 |
7501 | <Tabs>
7502 | <Tab title="Maven">
7503 | ```xml
7504 | <dependencyManagement>
7505 | <dependencies>
7506 | <dependency>
7507 | <groupId>io.modelcontextprotocol.sdk</groupId>
7508 | <artifactId>mcp-bom</artifactId>
7509 | <version>0.8.1</version>
7510 | <type>pom</type>
7511 | <scope>import</scope>
7512 | </dependency>
7513 | </dependencies>
7514 | </dependencyManagement>
7515 | ```
7516 | </Tab>
7517 |
7518 | <Tab title="Gradle">
7519 | ```groovy
7520 | dependencies {
7521 | implementation platform("io.modelcontextprotocol.sdk:mcp-bom:0.8.1")
7522 | //...
7523 | }
7524 | ```
7525 |
7526 | Gradle users can also use the Spring AI MCP BOM by leveraging Gradle (5.0+) native support for declaring dependency constraints using a Maven BOM.
7527 | This is implemented by adding a 'platform' dependency handler method to the dependencies section of your Gradle build script.
7528 | As shown in the snippet above this can then be followed by version-less declarations of the Starter Dependencies for the one or more spring-ai modules you wish to use, e.g. spring-ai-openai.
7529 | </Tab>
7530 | </Tabs>
7531 |
7532 | Replace the version number with the version of the BOM you want to use.
7533 |
7534 | ### Available Dependencies
7535 |
7536 | The following dependencies are available and managed by the BOM:
7537 |
7538 | * Core Dependencies
7539 | * `io.modelcontextprotocol.sdk:mcp` - Core MCP library providing the base functionality and APIs for Model Context Protocol implementation, including default STDIO and SSE client and server transport implementations. No external web frameworks required.
7540 | * Optional Transport Dependencies (convenience if using Spring Framework)
7541 | * `io.modelcontextprotocol.sdk:mcp-spring-webflux` - WebFlux-based Server-Sent Events (SSE) transport implementation for reactive applications.
7542 | * `io.modelcontextprotocol.sdk:mcp-spring-webmvc` - WebMVC-based Server-Sent Events (SSE) transport implementation for servlet-based applications.
7543 | * Testing Dependencies
7544 | * `io.modelcontextprotocol.sdk:mcp-test` - Testing utilities and support for MCP-based applications.
7545 |
7546 |
7547 | # MCP Server
7548 | Source: https://modelcontextprotocol.io/sdk/java/mcp-server
7549 |
7550 | Learn how to implement and configure a Model Context Protocol (MCP) server
7551 |
7552 | <Note>
7553 | ### Breaking Changes in 0.8.x ⚠️
7554 |
7555 | **Note:** Version 0.8.x introduces several breaking changes including a new session-based architecture.
7556 | If you're upgrading from 0.7.0, please refer to the [Migration Guide](https://github.com/modelcontextprotocol/java-sdk/blob/main/migration-0.8.0.md) for detailed instructions.
7557 | </Note>
7558 |
7559 | ## Overview
7560 |
7561 | The MCP Server is a foundational component in the Model Context Protocol (MCP) architecture that provides tools, resources, and capabilities to clients. It implements the server-side of the protocol, responsible for:
7562 |
7563 | * Exposing tools that clients can discover and execute
7564 | * Managing resources with URI-based access patterns
7565 | * Providing prompt templates and handling prompt requests
7566 | * Supporting capability negotiation with clients
7567 | * Implementing server-side protocol operations
7568 | * Managing concurrent client connections
7569 | * Providing structured logging and notifications
7570 |
7571 | <Tip>
7572 | The core `io.modelcontextprotocol.sdk:mcp` module provides STDIO and SSE server transport implementations without requiring external web frameworks.
7573 |
7574 | Spring-specific transport implementations are available as an **optional** dependencies `io.modelcontextprotocol.sdk:mcp-spring-webflux`, `io.modelcontextprotocol.sdk:mcp-spring-webmvc` for [Spring Framework](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-client-boot-starter-docs.html) users.
7575 | </Tip>
7576 |
7577 | The server supports both synchronous and asynchronous APIs, allowing for flexible integration in different application contexts.
7578 |
7579 | <Tabs>
7580 | <Tab title="Sync API">
7581 | ```java
7582 | // Create a server with custom configuration
7583 | McpSyncServer syncServer = McpServer.sync(transportProvider)
7584 | .serverInfo("my-server", "1.0.0")
7585 | .capabilities(ServerCapabilities.builder()
7586 | .resources(true) // Enable resource support
7587 | .tools(true) // Enable tool support
7588 | .prompts(true) // Enable prompt support
7589 | .logging() // Enable logging support
7590 | .build())
7591 | .build();
7592 |
7593 | // Register tools, resources, and prompts
7594 | syncServer.addTool(syncToolSpecification);
7595 | syncServer.addResource(syncResourceSpecification);
7596 | syncServer.addPrompt(syncPromptSpecification);
7597 |
7598 | // Send logging notifications
7599 | syncServer.loggingNotification(LoggingMessageNotification.builder()
7600 | .level(LoggingLevel.INFO)
7601 | .logger("custom-logger")
7602 | .data("Server initialized")
7603 | .build());
7604 |
7605 | // Close the server when done
7606 | syncServer.close();
7607 | ```
7608 | </Tab>
7609 |
7610 | <Tab title="Async API">
7611 | ```java
7612 | // Create an async server with custom configuration
7613 | McpAsyncServer asyncServer = McpServer.async(transportProvider)
7614 | .serverInfo("my-server", "1.0.0")
7615 | .capabilities(ServerCapabilities.builder()
7616 | .resources(true) // Enable resource support
7617 | .tools(true) // Enable tool support
7618 | .prompts(true) // Enable prompt support
7619 | .logging() // Enable logging support
7620 | .build())
7621 | .build();
7622 |
7623 | // Register tools, resources, and prompts
7624 | asyncServer.addTool(asyncToolSpecification)
7625 | .doOnSuccess(v -> logger.info("Tool registered"))
7626 | .subscribe();
7627 |
7628 | asyncServer.addResource(asyncResourceSpecification)
7629 | .doOnSuccess(v -> logger.info("Resource registered"))
7630 | .subscribe();
7631 |
7632 | asyncServer.addPrompt(asyncPromptSpecification)
7633 | .doOnSuccess(v -> logger.info("Prompt registered"))
7634 | .subscribe();
7635 |
7636 | // Send logging notifications
7637 | asyncServer.loggingNotification(LoggingMessageNotification.builder()
7638 | .level(LoggingLevel.INFO)
7639 | .logger("custom-logger")
7640 | .data("Server initialized")
7641 | .build());
7642 |
7643 | // Close the server when done
7644 | asyncServer.close()
7645 | .doOnSuccess(v -> logger.info("Server closed"))
7646 | .subscribe();
7647 | ```
7648 | </Tab>
7649 | </Tabs>
7650 |
7651 | ## Server Transport Providers
7652 |
7653 | The transport layer in the MCP SDK is responsible for handling the communication between clients and servers.
7654 | It provides different implementations to support various communication protocols and patterns.
7655 | The SDK includes several built-in transport provider implementations:
7656 |
7657 | <Tabs>
7658 | <Tab title="STDIO">
7659 | <>
7660 | Create in-process based transport:
7661 |
7662 | ```java
7663 | StdioServerTransportProvider transportProvider = new StdioServerTransportProvider(new ObjectMapper());
7664 | ```
7665 |
7666 | Provides bidirectional JSON-RPC message handling over standard input/output streams with non-blocking message processing, serialization/deserialization, and graceful shutdown support.
7667 |
7668 | Key features:
7669 |
7670 | <ul>
7671 | <li>Bidirectional communication through stdin/stdout</li>
7672 | <li>Process-based integration support</li>
7673 | <li>Simple setup and configuration</li>
7674 | <li>Lightweight implementation</li>
7675 | </ul>
7676 | </>
7677 | </Tab>
7678 |
7679 | <Tab title="SSE (WebFlux)">
7680 | <>
7681 | <p>Creates WebFlux-based SSE server transport.<br />Requires the <code>mcp-spring-webflux</code> dependency.</p>
7682 |
7683 | ```java
7684 | @Configuration
7685 | class McpConfig {
7686 | @Bean
7687 | WebFluxSseServerTransportProvider webFluxSseServerTransportProvider(ObjectMapper mapper) {
7688 | return new WebFluxSseServerTransportProvider(mapper, "/mcp/message");
7689 | }
7690 |
7691 | @Bean
7692 | RouterFunction<?> mcpRouterFunction(WebFluxSseServerTransportProvider transportProvider) {
7693 | return transportProvider.getRouterFunction();
7694 | }
7695 | }
7696 | ```
7697 |
7698 | <p>Implements the MCP HTTP with SSE transport specification, providing:</p>
7699 |
7700 | <ul>
7701 | <li>Reactive HTTP streaming with WebFlux</li>
7702 | <li>Concurrent client connections through SSE endpoints</li>
7703 | <li>Message routing and session management</li>
7704 | <li>Graceful shutdown capabilities</li>
7705 | </ul>
7706 | </>
7707 | </Tab>
7708 |
7709 | <Tab title="SSE (WebMvc)">
7710 | <>
7711 | <p>Creates WebMvc-based SSE server transport.<br />Requires the <code>mcp-spring-webmvc</code> dependency.</p>
7712 |
7713 | ```java
7714 | @Configuration
7715 | @EnableWebMvc
7716 | class McpConfig {
7717 | @Bean
7718 | WebMvcSseServerTransportProvider webMvcSseServerTransportProvider(ObjectMapper mapper) {
7719 | return new WebMvcSseServerTransportProvider(mapper, "/mcp/message");
7720 | }
7721 |
7722 | @Bean
7723 | RouterFunction<ServerResponse> mcpRouterFunction(WebMvcSseServerTransportProvider transportProvider) {
7724 | return transportProvider.getRouterFunction();
7725 | }
7726 | }
7727 | ```
7728 |
7729 | <p>Implements the MCP HTTP with SSE transport specification, providing:</p>
7730 |
7731 | <ul>
7732 | <li>Server-side event streaming</li>
7733 | <li>Integration with Spring WebMVC</li>
7734 | <li>Support for traditional web applications</li>
7735 | <li>Synchronous operation handling</li>
7736 | </ul>
7737 | </>
7738 | </Tab>
7739 |
7740 | <Tab title="SSE (Servlet)">
7741 | <>
7742 | <p>
7743 | Creates a Servlet-based SSE server transport. It is included in the core <code>mcp</code> module.<br />
7744 | The <code>HttpServletSseServerTransport</code> can be used with any Servlet container.<br />
7745 | To use it with a Spring Web application, you can register it as a Servlet bean:
7746 | </p>
7747 |
7748 | ```java
7749 | @Configuration
7750 | @EnableWebMvc
7751 | public class McpServerConfig implements WebMvcConfigurer {
7752 |
7753 | @Bean
7754 | public HttpServletSseServerTransportProvider servletSseServerTransportProvider() {
7755 | return new HttpServletSseServerTransportProvider(new ObjectMapper(), "/mcp/message");
7756 | }
7757 |
7758 | @Bean
7759 | public ServletRegistrationBean customServletBean(HttpServletSseServerTransportProvider transportProvider) {
7760 | return new ServletRegistrationBean(transportProvider);
7761 | }
7762 | }
7763 | ```
7764 |
7765 | <p>
7766 | Implements the MCP HTTP with SSE transport specification using the traditional Servlet API, providing:
7767 | </p>
7768 |
7769 | <ul>
7770 | <li>Asynchronous message handling using Servlet 6.0 async support</li>
7771 | <li>Session management for multiple client connections</li>
7772 |
7773 | <li>
7774 | Two types of endpoints:
7775 |
7776 | <ul>
7777 | <li>SSE endpoint (<code>/sse</code>) for server-to-client events</li>
7778 | <li>Message endpoint (configurable) for client-to-server requests</li>
7779 | </ul>
7780 | </li>
7781 |
7782 | <li>Error handling and response formatting</li>
7783 | <li>Graceful shutdown support</li>
7784 | </ul>
7785 | </>
7786 | </Tab>
7787 | </Tabs>
7788 |
7789 | ## Server Capabilities
7790 |
7791 | The server can be configured with various capabilities:
7792 |
7793 | ```java
7794 | var capabilities = ServerCapabilities.builder()
7795 | .resources(false, true) // Resource support with list changes notifications
7796 | .tools(true) // Tool support with list changes notifications
7797 | .prompts(true) // Prompt support with list changes notifications
7798 | .logging() // Enable logging support (enabled by default with logging level INFO)
7799 | .build();
7800 | ```
7801 |
7802 | ### Logging Support
7803 |
7804 | The server provides structured logging capabilities that allow sending log messages to clients with different severity levels:
7805 |
7806 | ```java
7807 | // Send a log message to clients
7808 | server.loggingNotification(LoggingMessageNotification.builder()
7809 | .level(LoggingLevel.INFO)
7810 | .logger("custom-logger")
7811 | .data("Custom log message")
7812 | .build());
7813 | ```
7814 |
7815 | Clients can control the minimum logging level they receive through the `mcpClient.setLoggingLevel(level)` request. Messages below the set level will be filtered out.
7816 | Supported logging levels (in order of increasing severity): DEBUG (0), INFO (1), NOTICE (2), WARNING (3), ERROR (4), CRITICAL (5), ALERT (6), EMERGENCY (7)
7817 |
7818 | ### Tool Specification
7819 |
7820 | The Model Context Protocol allows servers to [expose tools](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/tools/) that can be invoked by language models.
7821 | The Java SDK allows implementing a Tool Specifications with their handler functions.
7822 | Tools enable AI models to perform calculations, access external APIs, query databases, and manipulate files:
7823 |
7824 | <Tabs>
7825 | <Tab title="Sync">
7826 | ```java
7827 | // Sync tool specification
7828 | var schema = """
7829 | {
7830 | "type" : "object",
7831 | "id" : "urn:jsonschema:Operation",
7832 | "properties" : {
7833 | "operation" : {
7834 | "type" : "string"
7835 | },
7836 | "a" : {
7837 | "type" : "number"
7838 | },
7839 | "b" : {
7840 | "type" : "number"
7841 | }
7842 | }
7843 | }
7844 | """;
7845 | var syncToolSpecification = new McpServerFeatures.SyncToolSpecification(
7846 | new Tool("calculator", "Basic calculator", schema),
7847 | (exchange, arguments) -> {
7848 | // Tool implementation
7849 | return new CallToolResult(result, false);
7850 | }
7851 | );
7852 | ```
7853 | </Tab>
7854 |
7855 | <Tab title="Async">
7856 | ```java
7857 | // Async tool specification
7858 | var schema = """
7859 | {
7860 | "type" : "object",
7861 | "id" : "urn:jsonschema:Operation",
7862 | "properties" : {
7863 | "operation" : {
7864 | "type" : "string"
7865 | },
7866 | "a" : {
7867 | "type" : "number"
7868 | },
7869 | "b" : {
7870 | "type" : "number"
7871 | }
7872 | }
7873 | }
7874 | """;
7875 | var asyncToolSpecification = new McpServerFeatures.AsyncToolSpecification(
7876 | new Tool("calculator", "Basic calculator", schema),
7877 | (exchange, arguments) -> {
7878 | // Tool implementation
7879 | return Mono.just(new CallToolResult(result, false));
7880 | }
7881 | );
7882 | ```
7883 | </Tab>
7884 | </Tabs>
7885 |
7886 | The Tool specification includes a Tool definition with `name`, `description`, and `parameter schema` followed by a call handler that implements the tool's logic.
7887 | The function's first argument is `McpAsyncServerExchange` for client interaction, and the second is a map of tool arguments.
7888 |
7889 | ### Resource Specification
7890 |
7891 | Specification of a resource with its handler function.
7892 | Resources provide context to AI models by exposing data such as: File contents, Database records, API responses, System information, Application state.
7893 | Example resource specification:
7894 |
7895 | <Tabs>
7896 | <Tab title="Sync">
7897 | ```java
7898 | // Sync resource specification
7899 | var syncResourceSpecification = new McpServerFeatures.syncResourceSpecification(
7900 | new Resource("custom://resource", "name", "description", "mime-type", null),
7901 | (exchange, request) -> {
7902 | // Resource read implementation
7903 | return new ReadResourceResult(contents);
7904 | }
7905 | );
7906 | ```
7907 | </Tab>
7908 |
7909 | <Tab title="Async">
7910 | ```java
7911 | // Async resource specification
7912 | var asyncResourceSpecification = new McpServerFeatures.asyncResourceSpecification(
7913 | new Resource("custom://resource", "name", "description", "mime-type", null),
7914 | (exchange, request) -> {
7915 | // Resource read implementation
7916 | return Mono.just(new ReadResourceResult(contents));
7917 | }
7918 | );
7919 | ```
7920 | </Tab>
7921 | </Tabs>
7922 |
7923 | The resource specification comprised of resource definitions and resource read handler.
7924 | The resource definition including `name`, `description`, and `MIME type`.
7925 | The first argument of the function that handles resource read requests is an `McpAsyncServerExchange` upon which the server can
7926 | interact with the connected client.
7927 | The second arguments is a `McpSchema.ReadResourceRequest`.
7928 |
7929 | ### Prompt Specification
7930 |
7931 | As part of the [Prompting capabilities](https://spec.modelcontextprotocol.io/specification/2024-11-05/server/prompts/), MCP provides a standardized way for servers to expose prompt templates to clients.
7932 | The Prompt Specification is a structured template for AI model interactions that enables consistent message formatting, parameter substitution, context injection, response formatting, and instruction templating.
7933 |
7934 | <Tabs>
7935 | <Tab title="Sync">
7936 | ```java
7937 | // Sync prompt specification
7938 | var syncPromptSpecification = new McpServerFeatures.syncPromptSpecification(
7939 | new Prompt("greeting", "description", List.of(
7940 | new PromptArgument("name", "description", true)
7941 | )),
7942 | (exchange, request) -> {
7943 | // Prompt implementation
7944 | return new GetPromptResult(description, messages);
7945 | }
7946 | );
7947 | ```
7948 | </Tab>
7949 |
7950 | <Tab title="Async">
7951 | ```java
7952 | // Async prompt specification
7953 | var asyncPromptSpecification = new McpServerFeatures.asyncPromptSpecification(
7954 | new Prompt("greeting", "description", List.of(
7955 | new PromptArgument("name", "description", true)
7956 | )),
7957 | (exchange, request) -> {
7958 | // Prompt implementation
7959 | return Mono.just(new GetPromptResult(description, messages));
7960 | }
7961 | );
7962 | ```
7963 | </Tab>
7964 | </Tabs>
7965 |
7966 | The prompt definition includes name (identifier for the prompt), description (purpose of the prompt), and list of arguments (parameters for templating).
7967 | The handler function processes requests and returns formatted templates.
7968 | The first argument is `McpAsyncServerExchange` for client interaction, and the second argument is a `GetPromptRequest` instance.
7969 |
7970 | ### Using Sampling from a Server
7971 |
7972 | To use [Sampling capabilities](https://spec.modelcontextprotocol.io/specification/2024-11-05/client/sampling/), connect to a client that supports sampling.
7973 | No special server configuration is needed, but verify client sampling support before making requests.
7974 | Learn about [client sampling support](./mcp-client#sampling-support).
7975 |
7976 | Once connected to a compatible client, the server can request language model generations:
7977 |
7978 | <Tabs>
7979 | <Tab title="Sync API">
7980 | ```java
7981 | // Create a server
7982 | McpSyncServer server = McpServer.sync(transportProvider)
7983 | .serverInfo("my-server", "1.0.0")
7984 | .build();
7985 |
7986 | // Define a tool that uses sampling
7987 | var calculatorTool = new McpServerFeatures.SyncToolSpecification(
7988 | new Tool("ai-calculator", "Performs calculations using AI", schema),
7989 | (exchange, arguments) -> {
7990 | // Check if client supports sampling
7991 | if (exchange.getClientCapabilities().sampling() == null) {
7992 | return new CallToolResult("Client does not support AI capabilities", false);
7993 | }
7994 |
7995 | // Create a sampling request
7996 | McpSchema.CreateMessageRequest request = McpSchema.CreateMessageRequest.builder()
7997 | .content(new McpSchema.TextContent("Calculate: " + arguments.get("expression")))
7998 | .modelPreferences(McpSchema.ModelPreferences.builder()
7999 | .hints(List.of(
8000 | McpSchema.ModelHint.of("claude-3-sonnet"),
8001 | McpSchema.ModelHint.of("claude")
8002 | ))
8003 | .intelligencePriority(0.8) // Prioritize intelligence
8004 | .speedPriority(0.5) // Moderate speed importance
8005 | .build())
8006 | .systemPrompt("You are a helpful calculator assistant. Provide only the numerical answer.")
8007 | .maxTokens(100)
8008 | .build();
8009 |
8010 | // Request sampling from the client
8011 | McpSchema.CreateMessageResult result = exchange.createMessage(request);
8012 |
8013 | // Process the result
8014 | String answer = result.content().text();
8015 | return new CallToolResult(answer, false);
8016 | }
8017 | );
8018 |
8019 | // Add the tool to the server
8020 | server.addTool(calculatorTool);
8021 | ```
8022 | </Tab>
8023 |
8024 | <Tab title="Async API">
8025 | ```java
8026 | // Create a server
8027 | McpAsyncServer server = McpServer.async(transportProvider)
8028 | .serverInfo("my-server", "1.0.0")
8029 | .build();
8030 |
8031 | // Define a tool that uses sampling
8032 | var calculatorTool = new McpServerFeatures.AsyncToolSpecification(
8033 | new Tool("ai-calculator", "Performs calculations using AI", schema),
8034 | (exchange, arguments) -> {
8035 | // Check if client supports sampling
8036 | if (exchange.getClientCapabilities().sampling() == null) {
8037 | return Mono.just(new CallToolResult("Client does not support AI capabilities", false));
8038 | }
8039 |
8040 | // Create a sampling request
8041 | McpSchema.CreateMessageRequest request = McpSchema.CreateMessageRequest.builder()
8042 | .content(new McpSchema.TextContent("Calculate: " + arguments.get("expression")))
8043 | .modelPreferences(McpSchema.ModelPreferences.builder()
8044 | .hints(List.of(
8045 | McpSchema.ModelHint.of("claude-3-sonnet"),
8046 | McpSchema.ModelHint.of("claude")
8047 | ))
8048 | .intelligencePriority(0.8) // Prioritize intelligence
8049 | .speedPriority(0.5) // Moderate speed importance
8050 | .build())
8051 | .systemPrompt("You are a helpful calculator assistant. Provide only the numerical answer.")
8052 | .maxTokens(100)
8053 | .build();
8054 |
8055 | // Request sampling from the client
8056 | return exchange.createMessage(request)
8057 | .map(result -> {
8058 | // Process the result
8059 | String answer = result.content().text();
8060 | return new CallToolResult(answer, false);
8061 | });
8062 | }
8063 | );
8064 |
8065 | // Add the tool to the server
8066 | server.addTool(calculatorTool)
8067 | .subscribe();
8068 | ```
8069 | </Tab>
8070 | </Tabs>
8071 |
8072 | The `CreateMessageRequest` object allows you to specify: `Content` - the input text or image for the model,
8073 | `Model Preferences` - hints and priorities for model selection, `System Prompt` - instructions for the model's behavior and
8074 | `Max Tokens` - maximum length of the generated response.
8075 |
8076 | ## Error Handling
8077 |
8078 | The SDK provides comprehensive error handling through the McpError class, covering protocol compatibility, transport communication, JSON-RPC messaging, tool execution, resource management, prompt handling, timeouts, and connection issues. This unified error handling approach ensures consistent and reliable error management across both synchronous and asynchronous operations.
8079 |
8080 |
8081 | # Building MCP with LLMs
8082 | Source: https://modelcontextprotocol.io/tutorials/building-mcp-with-llms
8083 |
8084 | Speed up your MCP development using LLMs such as Claude!
8085 |
8086 | This guide will help you use LLMs to help you build custom Model Context Protocol (MCP) servers and clients. We'll be focusing on Claude for this tutorial, but you can do this with any frontier LLM.
8087 |
8088 | ## Preparing the documentation
8089 |
8090 | Before starting, gather the necessary documentation to help Claude understand MCP:
8091 |
8092 | 1. Visit [https://modelcontextprotocol.io/llms-full.txt](https://modelcontextprotocol.io/llms-full.txt) and copy the full documentation text
8093 | 2. Navigate to either the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) or [Python SDK repository](https://github.com/modelcontextprotocol/python-sdk)
8094 | 3. Copy the README files and other relevant documentation
8095 | 4. Paste these documents into your conversation with Claude
8096 |
8097 | ## Describing your server
8098 |
8099 | Once you've provided the documentation, clearly describe to Claude what kind of server you want to build. Be specific about:
8100 |
8101 | * What resources your server will expose
8102 | * What tools it will provide
8103 | * Any prompts it should offer
8104 | * What external systems it needs to interact with
8105 |
8106 | For example:
8107 |
8108 | ```
8109 | Build an MCP server that:
8110 | - Connects to my company's PostgreSQL database
8111 | - Exposes table schemas as resources
8112 | - Provides tools for running read-only SQL queries
8113 | - Includes prompts for common data analysis tasks
8114 | ```
8115 |
8116 | ## Working with Claude
8117 |
8118 | When working with Claude on MCP servers:
8119 |
8120 | 1. Start with the core functionality first, then iterate to add more features
8121 | 2. Ask Claude to explain any parts of the code you don't understand
8122 | 3. Request modifications or improvements as needed
8123 | 4. Have Claude help you test the server and handle edge cases
8124 |
8125 | Claude can help implement all the key MCP features:
8126 |
8127 | * Resource management and exposure
8128 | * Tool definitions and implementations
8129 | * Prompt templates and handlers
8130 | * Error handling and logging
8131 | * Connection and transport setup
8132 |
8133 | ## Best practices
8134 |
8135 | When building MCP servers with Claude:
8136 |
8137 | * Break down complex servers into smaller pieces
8138 | * Test each component thoroughly before moving on
8139 | * Keep security in mind - validate inputs and limit access appropriately
8140 | * Document your code well for future maintenance
8141 | * Follow MCP protocol specifications carefully
8142 |
8143 | ## Next steps
8144 |
8145 | After Claude helps you build your server:
8146 |
8147 | 1. Review the generated code carefully
8148 | 2. Test the server with the MCP Inspector tool
8149 | 3. Connect it to Claude.app or other MCP clients
8150 | 4. Iterate based on real usage and feedback
8151 |
8152 | Remember that Claude can help you modify and improve your server as requirements change over time.
8153 |
8154 | Need more guidance? Just ask Claude specific questions about implementing MCP features or troubleshooting issues that arise.
8155 |
8156 |
```