[
{
"chunk_id": "md_architecture_b82bfe7e__0",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "Architecture overview\nThis overview of the Model Context Protocol (MCP) discusses its scope and core concepts, and provides an example demonstrating each core concept.\nBecause MCP SDKs abstract away many concerns, most developers will likely find the data layer protocol section to be the most useful",
"chunk_index": 0,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__1",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "data layer protocol section to be the most useful. It discusses how MCP servers can provide context to an AI application.\nFor specific implementation details, please refer to the documentation for your language-specific SDK.\nScope\nThe Model Context Protocol includes the following projects:\n\nMCP Spe",
"chunk_index": 1,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__2",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "Protocol includes the following projects:\n\nMCP Specification: A specification of MCP that outlines the implementation requirements for clients and servers.\nMCP SDKs: SDKs for different programming languages that implement MCP.\nMCP Development Tools: Tools for developing MCP servers and clients, incl",
"chunk_index": 2,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__3",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "Tools for developing MCP servers and clients, including the MCP Inspector\nMCP Reference Server Implementations: Reference implementations of MCP servers.\n\n MCP focuses solely on the protocol for context exchange—it does not dictate\n how AI applications use LLMs or manage the provided context.\n\nConce",
"chunk_index": 3,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__4",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "ns use LLMs or manage the provided context.\n\nConcepts of MCP\nParticipants\nMCP follows a client-server architecture where an MCP host — an AI application like Claude Code or Claude Desktop — establishes connections to one or more MCP servers. The MCP host accomplishes this by creating one MCP client",
"chunk_index": 4,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__5",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "host accomplishes this by creating one MCP client for each MCP server. Each MCP client maintains a dedicated one-to-one connection with its corresponding MCP server.\nThe key participants in the MCP architecture are:\n\nMCP Host: The AI application that coordinates and manages one or multiple MCP clien",
"chunk_index": 5,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__6",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "coordinates and manages one or multiple MCP clients\nMCP Client: A component that maintains a connection to an MCP server and obtains context from an MCP server for the MCP host to use\nMCP Server: A program that provides context to MCP clients\n\nFor example: Visual Studio Code acts as an MCP host. Wh",
"chunk_index": 6,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__7",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "xample: Visual Studio Code acts as an MCP host. When Visual Studio Code establishes a connection to an MCP server, such as the Sentry MCP server, the Visual Studio Code runtime instantiates an MCP client object that maintains the connection to the Sentry MCP server.\nWhen Visual Studio Code subsequen",
"chunk_index": 7,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__8",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "ntry MCP server.\nWhen Visual Studio Code subsequently connects to another MCP server, such as the local filesystem server, the Visual Studio Code runtime instantiates an additional MCP client object to maintain this connection, hence maintaining a one-to-one\nrelationship of MCP clients to MCP server",
"chunk_index": 8,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__9",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "e-to-one\nrelationship of MCP clients to MCP servers.\n```mermaid theme={null}\ngraph TB\n subgraph \"MCP Host (AI Application)\"\n Client1[\"MCP Client 1\"]\n Client2[\"MCP Client 2\"]\n Client3[\"MCP Client 3\"]\n end\nServer1[\"MCP Server 1
(e.g., Sentry)\"]\nServer2[\"MCP Server 2
(e.g., Filesystem)\"]\nServer",
"chunk_index": 9,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__10",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "ver2[\"MCP Server 2
(e.g., Filesystem)\"]\nServer3[\"MCP Server 3
(e.g., Database)\"]\n\nClient1 ---|\"One-to-one
connection\"| Server1\nClient2 ---|\"One-to-one
connection\"| Server2\nClient3 ---|\"One-to-one
connection\"| Server3\n\n```\nNote that MCP server refers to the program that serves con",
"chunk_index": 10,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__11",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "t MCP server refers to the program that serves context data, regardless of\nwhere it runs. MCP servers can execute locally or remotely. For example, when\nClaude Desktop launches the filesystem\nserver,\nthe server runs locally on the same machine because it uses the STDIO\ntransport. This is commonly re",
"chunk_index": 11,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__12",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "e it uses the STDIO\ntransport. This is commonly referred to as a \"local\" MCP server. The official\nSentry MCP server runs on the\nSentry platform, and uses the Streamable HTTP transport. This is commonly\nreferred to as a \"remote\" MCP server.\nLayers\nMCP consists of two layers:\n\nData layer: Defines the",
"chunk_index": 12,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__13",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "consists of two layers:\n\nData layer: Defines the JSON-RPC based protocol for client-server communication, including lifecycle management, and core primitives, such as tools, resources, prompts and notifications.\nTransport layer: Defines the communication mechanisms and channels that enable data exc",
"chunk_index": 13,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__14",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "ation mechanisms and channels that enable data exchange between clients and servers, including transport-specific connection establishment, message framing, and authorization.\n\nConceptually the data layer is the inner layer, while the transport layer is the outer layer.\nData layer\nThe data layer imp",
"chunk_index": 14,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__15",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "is the outer layer.\nData layer\nThe data layer implements a JSON-RPC 2.0 based exchange protocol that defines the message structure and semantics.\nThis layer includes:\n\nLifecycle management: Handles connection initialization, capability negotiation, and connection termination between clients and ser",
"chunk_index": 15,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__16",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "and connection termination between clients and servers\nServer features: Enables servers to provide core functionality including tools for AI actions, resources for context data, and prompts for interaction templates from and to the client\nClient features: Enables servers to ask the client to sample",
"chunk_index": 16,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__17",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "ures: Enables servers to ask the client to sample from the host LLM, elicit input from the user, and log messages to the client\nUtility features: Supports additional capabilities like notifications for real-time updates and progress tracking for long-running operations\n\nTransport layer\nThe transport",
"chunk_index": 17,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__18",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "-running operations\n\nTransport layer\nThe transport layer manages communication channels and authentication between clients and servers. It handles connection establishment, message framing, and secure communication between MCP participants.\nMCP supports two transport mechanisms:\n\nStdio transport: Us",
"chunk_index": 18,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__19",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "rts two transport mechanisms:\n\nStdio transport: Uses standard input/output streams for direct process communication between local processes on the same machine, providing optimal performance with no network overhead.\nStreamable HTTP transport: Uses HTTP POST for client-to-server messages with option",
"chunk_index": 19,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__20",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "TTP POST for client-to-server messages with optional Server-Sent Events for streaming capabilities. This transport enables remote server communication and supports standard HTTP authentication methods including bearer tokens, API keys, and custom headers. MCP recommends using OAuth to obtain authent",
"chunk_index": 20,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__21",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "ders. MCP recommends using OAuth to obtain authentication tokens.\n\nThe transport layer abstracts communication details from the protocol layer, enabling the same JSON-RPC 2.0 message format across all transport mechanisms.\nData Layer Protocol\nA core part of MCP is defining the schema and semantics b",
"chunk_index": 21,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__22",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "part of MCP is defining the schema and semantics between MCP clients and MCP servers. Developers will likely find the data layer — in particular, the set of primitives — to be the most interesting part of MCP. It is the part of MCP that defines the ways developers can share context from MCP servers",
"chunk_index": 22,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__23",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "ays developers can share context from MCP servers to MCP clients.\nMCP uses JSON-RPC 2.0 as its underlying RPC protocol. Client and servers send requests to each other and respond accordingly. Notifications can be used when no response is required.\nLifecycle management\nMCP is a stateful protocol that",
"chunk_index": 23,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__24",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "fecycle management\nMCP is a stateful protocol that requires lifecycle management. The purpose of lifecycle management is to negotiate the capabilities that both client and server support. Detailed information can be found in the specification, and the example showcases the initialization sequence.\nP",
"chunk_index": 24,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__25",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "e example showcases the initialization sequence.\nPrimitives\nMCP primitives are the most important concept within MCP. They define what clients and servers can offer each other. These primitives specify the types of contextual information that can be shared with AI applications and the range of actio",
"chunk_index": 25,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__26",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "shared with AI applications and the range of actions that can be performed.\nMCP defines three core primitives that servers can expose:\n\nTools: Executable functions that AI applications can invoke to perform actions (e.g., file operations, API calls, database queries)\nResources: Data sources that pro",
"chunk_index": 26,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__27",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "database queries)\nResources: Data sources that provide contextual information to AI applications (e.g., file contents, database records, API responses)\nPrompts: Reusable templates that help structure interactions with language models (e.g., system prompts, few-shot examples)\n\nEach primitive type has",
"chunk_index": 27,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__28",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "ompts, few-shot examples)\n\nEach primitive type has associated methods for discovery (*/list), retrieval (*/get), and in some cases, execution (tools/call).\nMCP clients will use the */list methods to discover available primitives. For example, a client can first list all available tools (tools/list)",
"chunk_index": 28,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__29",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "t can first list all available tools (tools/list) and then execute them. This design allows listings to be dynamic.\nAs a concrete example, consider an MCP server that provides context about a database. It can expose tools for querying the database, a resource that contains the schema of the database",
"chunk_index": 29,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__30",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "resource that contains the schema of the database, and a prompt that includes few-shot examples for interacting with the tools.\nFor more details about server primitives see server concepts.\nMCP also defines primitives that clients can expose. These primitives allow MCP server authors to build riche",
"chunk_index": 30,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__31",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "primitives allow MCP server authors to build richer interactions.\n\nSampling: Allows servers to request language model completions from the client's AI application. This is useful when servers' authors want access to a language model, but want to stay model independent and not include a language mode",
"chunk_index": 31,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__32",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "model independent and not include a language model SDK in their MCP server. They can use the sampling/complete method to request a language model completion from the client's AI application.\nElicitation: Allows servers to request additional information from users. This is useful when servers' autho",
"chunk_index": 32,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__33",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "ion from users. This is useful when servers' authors want to get more information from the user, or ask for confirmation of an action. They can use the elicitation/request method to request additional information from the user.\nLogging: Enables servers to send log messages to clients for debugging a",
"chunk_index": 33,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__34",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "rs to send log messages to clients for debugging and monitoring purposes.\n\nFor more details about client primitives see client concepts.\nNotifications\nThe protocol supports real-time notifications to enable dynamic updates between servers and clients. For example, when a server's available tools cha",
"chunk_index": 34,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__35",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": ". For example, when a server's available tools change—such as when new functionality becomes available or existing tools are modified—the server can send tool update notifications to inform connected clients about these changes. Notifications are sent as JSON-RPC 2.0 notification messages (without e",
"chunk_index": 35,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__36",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "t as JSON-RPC 2.0 notification messages (without expecting a response) and enable MCP servers to provide real-time updates to connected clients.\nExample\nData Layer\nThis section provides a step-by-step walkthrough of an MCP client-server interaction, focusing on the data layer protocol. We'll demonst",
"chunk_index": 36,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__37",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "focusing on the data layer protocol. We'll demonstrate the lifecycle sequence, tool operations, and notifications using JSON-RPC 2.0 messages.\n\n MCP begins with lifecycle management through a capability negotiation handshake. As described in the lifecycle management section, the client sends an init",
"chunk_index": 37,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__38",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "cycle management section, the client sends an initialize request to establish the connection and negotiate supported features.\n\n ```json Initialize Request theme={null}\n {\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"initialize\",\n \"params\": {\n \"protocolVersion\": \"2025-06-18\",\n \"capabilities\":",
"chunk_index": 38,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__39",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "\"protocolVersion\": \"2025-06-18\",\n \"capabilities\": {\n \"elicitation\": {}\n },\n \"clientInfo\": {\n \"name\": \"example-client\",\n \"version\": \"1.0.0\"\n }\n }\n }\n ```\n\n ```json Initialize Response theme={null}\n {\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"protocolVersion\": \"2025-06-18\",\n \"capabilities\": {\n \"too",
"chunk_index": 39,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__40",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "olVersion\": \"2025-06-18\",\n \"capabilities\": {\n \"tools\": {\n \"listChanged\": true\n },\n \"resources\": {}\n },\n \"serverInfo\": {\n \"name\": \"example-server\",\n \"version\": \"1.0.0\"\n }\n }\n }\n ```\n\n\n#### Understanding the Initialization Exchange\n\nThe initialization process is a key part of MCP's lifecyc",
"chunk_index": 40,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__41",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "tialization process is a key part of MCP's lifecycle management and serves several critical purposes:\n\n1. **Protocol Version Negotiation**: The `protocolVersion` field (e.g., \"2025-06-18\") ensures both client and server are using compatible protocol versions. This prevents communication errors that",
"chunk_index": 41,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__42",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "versions. This prevents communication errors that could occur when different versions attempt to interact. If a mutually compatible version is not negotiated, the connection should be terminated.\n\n2. **Capability Discovery**: The `capabilities` object allows each party to declare what features they",
"chunk_index": 42,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__43",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "t allows each party to declare what features they support, including which [primitives](#primitives) they can handle (tools, resources, prompts) and whether they support features like [notifications](#notifications). This enables efficient communication by avoiding unsupported operations.\n\n3. **Iden",
"chunk_index": 43,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__44",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "ion by avoiding unsupported operations.\n\n3. **Identity Exchange**: The `clientInfo` and `serverInfo` objects provide identification and versioning information for debugging and compatibility purposes.\n\nIn this example, the capability negotiation demonstrates how MCP primitives are declared:\n\n**Clien",
"chunk_index": 44,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__45",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "nstrates how MCP primitives are declared:\n\n**Client Capabilities**:\n\n* `\"elicitation\": {}` - The client declares it can work with user interaction requests (can receive `elicitation/create` method calls)\n\n**Server Capabilities**:\n\n* `\"tools\": {\"listChanged\": true}` - The server supports the tools pr",
"chunk_index": 45,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__46",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "hanged\": true}` - The server supports the tools primitive AND can send `tools/list_changed` notifications when its tool list changes\n* `\"resources\": {}` - The server also supports the resources primitive (can handle `resources/list` and `resources/read` methods)\n\nAfter successful initialization, the",
"chunk_index": 46,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__47",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "ad` methods)\n\nAfter successful initialization, the client sends a notification to indicate it's ready:\n\n```json Notification theme={null}\n{\n \"jsonrpc\": \"2.0\",\n \"method\": \"notifications/initialized\"\n}\n```\n\n#### How This Works in AI Applications\n\nDuring initialization, the AI application's MCP client",
"chunk_index": 47,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__48",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "g initialization, the AI application's MCP client manager establishes connections to configured servers and stores their capabilities for later use. The application uses this information to determine which servers can provide specific types of functionality (tools, resources, prompts) and whether th",
"chunk_index": 48,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__49",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "onality (tools, resources, prompts) and whether they support real-time updates.\n\n```python Pseudo-code for AI application initialization theme={null}\n# Pseudo Code\nasync with stdio_client(server_config) as (read, write):\n async with ClientSession(read, write) as session:\n init_response = await sessi",
"chunk_index": 49,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__50",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "d, write) as session:\n init_response = await session.initialize()\n if init_response.capabilities.tools:\n app.register_mcp_server(session, supports_tools=True)\n app.set_server_ready(session)\n```\n\n Now that the connection is established, the client can discover available tools by sending a tools/list",
"chunk_index": 50,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__51",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "discover available tools by sending a tools/list request. This request is fundamental to MCP's tool discovery mechanism — it allows clients to understand what tools are available on the server before attempting to use them.\n\n ```json Tools List Request theme={null}\n {\n \"jsonrpc\": \"2.0\",",
"chunk_index": 51,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__52",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "s List Request theme={null}\n {\n \"jsonrpc\": \"2.0\",\n \"id\": 2,\n \"method\": \"tools/list\"\n }\n ```\n\n ```json Tools List Response theme={null}\n {\n \"jsonrpc\": \"2.0\",\n \"id\": 2,\n \"result\": {\n \"tools\": [\n {\n \"name\": \"calculator_arithmetic\",\n \"title\": \"Calculator\",\n \"description\": \"Perform mathematical calculati",
"chunk_index": 52,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__53",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "\",\n \"description\": \"Perform mathematical calculations including basic arithmetic, trigonometric functions, and algebraic operations\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"expression\": {\n \"type\": \"string\",\n \"description\": \"Mathematical expression to evaluate (e.g., '2 + 3 * 4', 'si",
"chunk_index": 53,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__54",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "cal expression to evaluate (e.g., '2 + 3 * 4', 'sin(30)', 'sqrt(16)')\"\n }\n },\n \"required\": [\"expression\"]\n }\n },\n {\n \"name\": \"weather_current\",\n \"title\": \"Weather Information\",\n \"description\": \"Get current weather information for any location worldwide\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"proper",
"chunk_index": 54,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__55",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "de\",\n \"inputSchema\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"City name, address, or coordinates (latitude,longitude)\"\n },\n \"units\": {\n \"type\": \"string\",\n \"enum\": [\"metric\", \"imperial\", \"kelvin\"],\n \"description\": \"Temperature units to use in response\",",
"chunk_index": 55,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__56",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "cription\": \"Temperature units to use in response\",\n \"default\": \"metric\"\n }\n },\n \"required\": [\"location\"]\n }\n }\n ]\n }\n }\n ```\n\n\n#### Understanding the Tool Discovery Request\n\nThe `tools/list` request is simple, containing no parameters.\n\n#### Understanding the Tool Discovery Response\n\nThe",
"chunk_index": 56,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__57",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "### Understanding the Tool Discovery Response\n\nThe response contains a `tools` array that provides comprehensive metadata about each available tool. This array-based structure allows servers to expose multiple tools simultaneously while maintaining clear boundaries between different functionalities.",
"chunk_index": 57,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__58",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "lear boundaries between different functionalities.\n\nEach tool object in the response includes several key fields:\n\n* **`name`**: A unique identifier for the tool within the server's namespace. This serves as the primary key for tool execution and should follow a clear naming pattern (e.g., `calculat",
"chunk_index": 58,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__59",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "uld follow a clear naming pattern (e.g., `calculator_arithmetic` rather than just `calculate`)\n* **`title`**: A human-readable display name for the tool that clients can show to users\n* **`description`**: Detailed explanation of what the tool does and when to use it\n* **`inputSchema`**: A JSON Schem",
"chunk_index": 59,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__60",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "d when to use it\n* **`inputSchema`**: A JSON Schema that defines the expected input parameters, enabling type validation and providing clear documentation about required and optional parameters\n\n#### How This Works in AI Applications\n\nThe AI application fetches available tools from all connected MCP",
"chunk_index": 60,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__61",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "ion fetches available tools from all connected MCP servers and combines them into a unified tool registry that the language model can access. This allows the LLM to understand what actions it can perform and automatically generates the appropriate tool calls during conversations.\n\n```python Pseudo-c",
"chunk_index": 61,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__62",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "ol calls during conversations.\n\n```python Pseudo-code for AI application tool discovery theme={null}\n# Pseudo-code using MCP Python SDK patterns\navailable_tools = []\nfor session in app.mcp_server_sessions():\n tools_response = await session.list_tools()\n available_tools.extend(tools_response.tools)\nc",
"chunk_index": 62,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__63",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "()\n available_tools.extend(tools_response.tools)\nconversation.register_available_tools(available_tools)\n```\n\n The client can now execute a tool using the tools/call method. This demonstrates how MCP primitives are used in practice: after discovering available tools, the client can invoke them with a",
"chunk_index": 63,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__64",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "available tools, the client can invoke them with appropriate arguments.\n#### Understanding the Tool Execution Request\n\nThe `tools/call` request follows a structured format that ensures type safety and clear communication between client and server. Note that we're using the proper tool name from the",
"chunk_index": 64,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__65",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "te that we're using the proper tool name from the discovery response (`weather_current`) rather than a simplified name:\n\n\n ```json Tool Call Request theme={null}\n {\n \"jsonrpc\": \"2.0\",\n \"id\": 3,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"weather_current\",\n \"arguments\": {\n \"location\":",
"chunk_index": 65,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__66",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": ": \"weather_current\",\n \"arguments\": {\n \"location\": \"San Francisco\",\n \"units\": \"imperial\"\n }\n }\n }\n ```\n\n ```json Tool Call Response theme={null}\n {\n \"jsonrpc\": \"2.0\",\n \"id\": 3,\n \"result\": {\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"Current weather in San Francisco: 68°F, partly cloudy with light wi",
"chunk_index": 66,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__67",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "n San Francisco: 68°F, partly cloudy with light winds from the west at 8 mph. Humidity: 65%\"\n }\n ]\n }\n }\n ```\n\n\n#### Key Elements of Tool Execution\n\nThe request structure includes several important components:\n\n1. **`name`**: Must match exactly the tool name from the discovery response (",
"chunk_index": 67,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__68",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "xactly the tool name from the discovery response (`weather_current`). This ensures the server can correctly identify which tool to execute.\n\n2. **`arguments`**: Contains the input parameters as defined by the tool's `inputSchema`. In this example:\n * `location`: \"San Francisco\" (required parameter)",
"chunk_index": 68,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__69",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "`location`: \"San Francisco\" (required parameter)\n * `units`: \"imperial\" (optional parameter, defaults to \"metric\" if not specified)\n\n3. **JSON-RPC Structure**: Uses standard JSON-RPC 2.0 format with unique `id` for request-response correlation.\n\n#### Understanding the Tool Execution Response\n\nThe r",
"chunk_index": 69,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__70",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "# Understanding the Tool Execution Response\n\nThe response demonstrates MCP's flexible content system:\n\n1. **`content` Array**: Tool responses return an array of content objects, allowing for rich, multi-format responses (text, images, resources, etc.)\n\n2. **Content Types**: Each content object has a",
"chunk_index": 70,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__71",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": ")\n\n2. **Content Types**: Each content object has a `type` field. In this example, `\"type\": \"text\"` indicates plain text content, but MCP supports various content types for different use cases.\n\n3. **Structured Output**: The response provides actionable information that the AI application can use as",
"chunk_index": 71,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__72",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "le information that the AI application can use as context for language model interactions.\n\nThis execution pattern allows AI applications to dynamically invoke server functionality and receive structured responses that can be integrated into conversations with language models.\n\n#### How This Works i",
"chunk_index": 72,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__73",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "tions with language models.\n\n#### How This Works in AI Applications\n\nWhen the language model decides to use a tool during a conversation, the AI application intercepts the tool call, routes it to the appropriate MCP server, executes it, and returns the results back to the LLM as part of the conversa",
"chunk_index": 73,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__74",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "he results back to the LLM as part of the conversation flow. This enables the LLM to access real-time data and perform actions in the external world.\n\n```python theme={null}\n# Pseudo-code for AI application tool execution\nasync def handle_tool_call(conversation, tool_name, arguments):\n session = app",
"chunk_index": 74,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__75",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "onversation, tool_name, arguments):\n session = app.find_mcp_session_for_tool(tool_name)\n result = await session.call_tool(tool_name, arguments)\n conversation.add_tool_result(result.content)\n```\n\n MCP supports real-time notifications that enable servers to inform clients about changes without being e",
"chunk_index": 75,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__76",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "rs to inform clients about changes without being explicitly requested. This demonstrates the notification system, a key feature that keeps MCP connections synchronized and responsive.\n#### Understanding Tool List Change Notifications\n\nWhen the server's available tools change—such as when new functio",
"chunk_index": 76,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__77",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "'s available tools change—such as when new functionality becomes available, existing tools are modified, or tools become temporarily unavailable—the server can proactively notify connected clients:\n\n```json Request theme={null}\n{\n \"jsonrpc\": \"2.0\",\n \"method\": \"notifications/tools/list_changed\"\n}\n```",
"chunk_index": 77,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__78",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "\"method\": \"notifications/tools/list_changed\"\n}\n```\n\n#### Key Features of MCP Notifications\n\n1. **No Response Required**: Notice there's no `id` field in the notification. This follows JSON-RPC 2.0 notification semantics where no response is expected or sent.\n\n2. **Capability-Based**: This notificati",
"chunk_index": 78,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__79",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "or sent.\n\n2. **Capability-Based**: This notification is only sent by servers that declared `\"listChanged\": true` in their tools capability during initialization (as shown in Step 1).\n\n3. **Event-Driven**: The server decides when to send notifications based on internal state changes, making MCP conne",
"chunk_index": 79,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__80",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "based on internal state changes, making MCP connections dynamic and responsive.\n\n#### Client Response to Notifications\n\nUpon receiving this notification, the client typically reacts by requesting the updated tool list. This creates a refresh cycle that keeps the client's understanding of available",
"chunk_index": 80,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__81",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "hat keeps the client's understanding of available tools current:\n\n```json Request theme={null}\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 4,\n \"method\": \"tools/list\"\n}\n```\n\n#### Why Notifications Matter\n\nThis notification system is crucial for several reasons:\n\n1. **Dynamic Environments**: Tools may come and go bas",
"chunk_index": 81,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__82",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "*Dynamic Environments**: Tools may come and go based on server state, external dependencies, or user permissions\n2. **Efficiency**: Clients don't need to poll for changes; they're notified when updates occur\n3. **Consistency**: Ensures clients always have accurate information about available server",
"chunk_index": 82,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__83",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "have accurate information about available server capabilities\n4. **Real-time Collaboration**: Enables responsive AI applications that can adapt to changing contexts\n\nThis notification pattern extends beyond tools to other MCP primitives, enabling comprehensive real-time synchronization between clie",
"chunk_index": 83,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__84",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "mprehensive real-time synchronization between clients and servers.\n\n#### How This Works in AI Applications\n\nWhen the AI application receives a notification about changed tools, it immediately refreshes its tool registry and updates the LLM's available capabilities. This ensures that ongoing conversa",
"chunk_index": 84,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__85",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "e capabilities. This ensures that ongoing conversations always have access to the most current set of tools, and the LLM can dynamically adapt to new functionality as it becomes available.\n\n```python theme={null}\n# Pseudo-code for AI application notification handling\nasync def handle_tools_changed_n",
"chunk_index": 85,
"total_chunks": 87
},
{
"chunk_id": "md_architecture_b82bfe7e__86",
"doc_id": "md_architecture_b82bfe7e",
"title": "Architecture overview",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\architecture.md",
"filename": "architecture.md",
"file_path": "architecture.md",
"updated_at": "1760788520.8599238",
"text": "fication handling\nasync def handle_tools_changed_notification(session):\n tools_response = await session.list_tools()\n app.update_available_tools(session, tools_response.tools)\n if app.conversation.is_active():\n app.conversation.notify_llm_of_new_capabilities()\n```",
"chunk_index": 86,
"total_chunks": 87
},
{
"chunk_id": "md_authorization_8784292d__0",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "Understanding Authorization in MCP\n\nLearn how to implement secure authorization for MCP servers using OAuth 2.1 to protect sensitive resources and operations\n\nAuthorization in the Model Context Protocol (MCP) secures access to sensitive resources and operations exposed by MCP servers. If your MCP se",
"chunk_index": 0,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__1",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "operations exposed by MCP servers. If your MCP server handles user data or administrative actions, authorization ensures only permitted users can access its endpoints.\nMCP uses standardized authorization flows to build trust between MCP clients and MCP servers. Its design doesn't focus on one speci",
"chunk_index": 1,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__2",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "MCP servers. Its design doesn't focus on one specific authorization or identity system, but rather follows the conventions outlined for OAuth 2.1. For detailed information, see the Authorization specification.\nWhen Should You Use Authorization?\nWhile authorization for MCP servers is optional, it is",
"chunk_index": 2,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__3",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "authorization for MCP servers is optional, it is strongly recommended when:\n\nYour server accesses user-specific data (emails, documents, databases)\nYou need to audit who performed which actions\nYour server grants access to its APIs that require user consent\nYou're building for enterprise environmen",
"chunk_index": 3,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__4",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "consent\nYou're building for enterprise environments with strict access controls\nYou want to implement rate limiting or usage tracking per user\n\nAuthorization for Local MCP Servers\nFor MCP servers using the STDIO transport, you can use environment-based credentials or credentials provided by third-p",
"chunk_index": 4,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__5",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "sed credentials or credentials provided by third-party libraries embedded directly in the MCP server instead. Because a STDIO-built MCP server runs locally, it has access to a range of flexible options when it comes to acquiring user credentials that may or may not rely on in-browser authentication",
"chunk_index": 5,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__6",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "may or may not rely on in-browser authentication and authorization flows.\nOAuth flows, in turn, are designed for HTTP-based transports where the MCP server is remotely-hosted and the client uses OAuth to establish that a user is authorized to access said remote server.\n\nThe Authorization Flow: Step",
"chunk_index": 6,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__7",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "said remote server.\n\nThe Authorization Flow: Step by Step\nLet's walk through what happens when a client wants to connect to your protected MCP server:\n\n When your MCP client first tries to connect, your server responds with a 401 Unauthorized and tells the client where to find authorization informa",
"chunk_index": 7,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__8",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "lls the client where to find authorization information, captured in a Protected Resource Metadata (PRM) document. The document is hosted by the MCP server, follows a predictable path pattern, and is provided to the client in the resource_metadata parameter within the WWW-Authenticate header.\n```http",
"chunk_index": 8,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__9",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ameter within the WWW-Authenticate header.\n```http theme={null}\nHTTP/1.1 401 Unauthorized\nWWW-Authenticate: Bearer realm=\"mcp\",\n resource_metadata=\"https://your-server.com/.well-known/oauth-protected-resource\"\n```\n\nThis tells the client that authorization is required for the MCP server and where to",
"chunk_index": 9,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__10",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ation is required for the MCP server and where to get the necessary information to kickstart the authorization flow.\n\n With the URI pointer to the PRM document, the client will fetch the metadata to learn about the authorization server, supported scopes, and other resource information. The data is t",
"chunk_index": 10,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__11",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "pes, and other resource information. The data is typically encapsulated in a JSON blob, similar to the one below.\n```json theme={null}\n{\n \"resource\": \"https://your-server.com/mcp\",\n \"authorization_servers\": [\"https://auth.your-server.com\"],\n \"scopes_supported\": [\"mcp:tools\", \"mcp:resources\"]\n}\n```",
"chunk_index": 11,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__12",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "supported\": [\"mcp:tools\", \"mcp:resources\"]\n}\n```\n\nYou can see a more comprehensive example in [RFC 9278 Section 3.2](https://datatracker.ietf.org/doc/html/rfc9728#name-protected-resource-metadata-r).\n\n Next, the client discovers what the authorization server can do by fetching its metadata. If the P",
"chunk_index": 12,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__13",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "n server can do by fetching its metadata. If the PRM document lists more than one authorization server, the client can decide which one to use.\nWith an authorization server selected, the client will then construct a standard metadata URI and issue a request to the [OpenID Connect (OIDC) Discovery](h",
"chunk_index": 13,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__14",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "request to the [OpenID Connect (OIDC) Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) or [OAuth 2.0 Auth Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) endpoints (depending on authorization server support)\nand retrieve another set of metadata properties that w",
"chunk_index": 14,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__15",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "retrieve another set of metadata properties that will allow it to know the endpoints it needs to complete the authorization flow.\n\n```json theme={null}\n{\n \"issuer\": \"https://auth.your-server.com\",\n \"authorization_endpoint\": \"https://auth.your-server.com/authorize\",\n \"token_endpoint\": \"https://auth.y",
"chunk_index": 15,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__16",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "com/authorize\",\n \"token_endpoint\": \"https://auth.your-server.com/token\",\n \"registration_endpoint\": \"https://auth.your-server.com/register\"\n}\n```\n\n With all the metadata out of the way, the client now needs to make sure that it's registered with the authorization server. This can be done in two ways.",
"chunk_index": 16,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__17",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "uthorization server. This can be done in two ways.\nFirst, the client can be **pre-registered** with a given authorization server, in which case it can have embedded client registration information that it uses to complete the authorization flow.\n\nAlternatively, the client can use **Dynamic Client Re",
"chunk_index": 17,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__18",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ernatively, the client can use **Dynamic Client Registration** (DCR) to dynamically register itself with the authorization server. The latter scenario requires the authorization server to support DCR. If the authorization server does support DCR, the client will send a request to the `registration_e",
"chunk_index": 18,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__19",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "client will send a request to the `registration_endpoint` with its information:\n\n```json theme={null}\n{\n \"client_name\": \"My MCP Client\",\n \"redirect_uris\": [\"http://localhost:3000/callback\"],\n \"grant_types\": [\"authorization_code\", \"refresh_token\"],\n \"response_types\": [\"code\"]\n}\n```\n\nIf the registrat",
"chunk_index": 19,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__20",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "\"response_types\": [\"code\"]\n}\n```\n\nIf the registration succeeds, the authorization server will return a JSON blob with client registration information.\n\n\n **No DCR or Pre-Registration**\n\n In case a MCP client connects to a MCP server that doesn't use an authorization server that supports DCR and",
"chunk_index": 20,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__21",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "use an authorization server that supports DCR and the client is not pre-registered with said authorization server, it's the responsibility of the client developer to provide an affordance for the end-user to enter client information manually.\n\n\n The client will now need to open a browser to t",
"chunk_index": 21,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__22",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "The client will now need to open a browser to the /authorize endpoint, where the user can log in and grant the required permissions. The authorization server will then redirect back to the client with an authorization code that the client exchanges for tokens:\n```json theme={null}\n{\n \"access_toke",
"chunk_index": 22,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__23",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "s for tokens:\n```json theme={null}\n{\n \"access_token\": \"eyJhbGciOiJSUzI1NiIs...\",\n \"refresh_token\": \"def502...\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 3600\n}\n```\n\nThe access token is what the client will use to authenticate requests to the MCP server. This step follows standard [OAuth 2.1 authoriza",
"chunk_index": 23,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__24",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "r. This step follows standard [OAuth 2.1 authorization code with PKCE](https://oauth.net/2/grant-types/authorization-code/) conventions.\n\n Finally, the client can make requests to your MCP server using the access token embedded in the Authorization header:\n```http theme={null}\nGET /mcp HTTP/1.1\nHost",
"chunk_index": 24,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__25",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "eader:\n```http theme={null}\nGET /mcp HTTP/1.1\nHost: your-server.com\nAuthorization: Bearer eyJhbGciOiJSUzI1NiIs...\n```\n\nThe MCP server will need to validate the token and process the request if the token is valid and has the required permissions.\n\nImplementation Example\nTo get started with a practica",
"chunk_index": 25,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__26",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "lementation Example\nTo get started with a practical implementation, we will use a Keycloak authorization server hosted in a Docker container. Keycloak is an open-source authorization server that can be easily deployed locally for testing and experimentation.\nMake sure that you download and install D",
"chunk_index": 26,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__27",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ntation.\nMake sure that you download and install Docker Desktop. We will need it to deploy Keycloak on our development machine.\nKeycloak Setup\nFrom your terminal application, run the following command to start the Keycloak container:\nbash theme={null}\ndocker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRA",
"chunk_index": 27,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__28",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "}\ndocker run -p 127.0.0.1:8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak start-dev\nThis command will pull the Keycloak container image locally and bootstrap the basic configuration. It will run on port 8080 and have an admin user with ad",
"chunk_index": 28,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__29",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ll run on port 8080 and have an admin user with admin password.\n\nNot for Production\nThe configuration above may be suitable for testing and experimentation; however, you should never use it in production. Refer to the Configuring Keycloak for production guide for additional details on how to deploy",
"chunk_index": 29,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__30",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ion guide for additional details on how to deploy the authorization server for scenarios that require reliability, security, and high availability.\n\nYou will be able to access the Keycloak authorization server from your browser at http://localhost:8080.\n\nWhen running with the default configuration,",
"chunk_index": 30,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__31",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "80.\n\nWhen running with the default configuration, Keycloak will already support many of the capabilities that we need for MCP servers, including Dynamic Client Registration. You can check this by looking at the OIDC configuration, available at:\nhttp theme={null}\nhttp://localhost:8080/realms/master/.",
"chunk_index": 31,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__32",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "theme={null}\nhttp://localhost:8080/realms/master/.well-known/openid-configuration\nWe will also need to set up Keycloak to support our scopes and allow our host (local machine) to dynamically register clients, as the default policies restrict anonymous dynamic client registration.\nGo to Client scopes",
"chunk_index": 32,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__33",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "s dynamic client registration.\nGo to Client scopes in the Keycloak dashboard and create a new mcp:tools scope. We will use this to access all of the tools on our MCP server.\n\nAfter creating the scope, make sure that you assign its type to Default and have flipped the Include in token scope switch, a",
"chunk_index": 33,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__34",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "have flipped the Include in token scope switch, as this will be needed for token validation.\nLet's now also set up an audience for our Keycloak-issued tokens. An audience is important to configure because it embeds the intended destination directly into the issued access token. This helps your MCP",
"chunk_index": 34,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__35",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "into the issued access token. This helps your MCP server to verify that the token it got was actually meant for it rather than some other API. This is key to help avoid token passthrough scenarios.\nTo do this, open your mcp:tools client scope and click on Mappers, followed by Configure a new mapper.",
"chunk_index": 35,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__36",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ck on Mappers, followed by Configure a new mapper. Select Audience.\n\nFor Name, use audience-config. Add a value for Included Custom Audience, set to http://localhost:3000. This will be the URI of our test server.\n\nNot for Production\nThe audience configuration above is meant for testing. For producti",
"chunk_index": 36,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__37",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "iguration above is meant for testing. For production scenarios, additional set-up and configuration will be required to ensure that audiences are properly constrained for issued tokens. Specifically, the audience needs to be based on the resource parameter passed from the client, not a fixed value.",
"chunk_index": 37,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__38",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ameter passed from the client, not a fixed value.\n\nNow, navigate to Clients, then Client registration, and then Trusted Hosts. Disable the Client URIs Must Match setting and add the hosts from which you're testing. You can get your current host IP by running the ifconfig command on Linux or macOS, o",
"chunk_index": 38,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__39",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "running the ifconfig command on Linux or macOS, or ipconfig on Windows. You can see the IP address you need to add by looking at the keycloak logs for a line that looks like Failed to verify remote host : 192.168.215.1. Check that the IP address is associated with your host. This may be for a bridg",
"chunk_index": 39,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__40",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "associated with your host. This may be for a bridge network depending on your docker setup.\n\nGetting the Host\nIf you are running Keycloak from a container, you will also be able to see the host IP from the Terminal in the container logs.\n\nLastly, we need to register a new client that we can use with",
"chunk_index": 40,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__41",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "need to register a new client that we can use with the MCP server itself to talk to Keycloak for things like token introspection. To do that:\n\nGo to Clients.\nClick Create client.\nGive your client a unique Client ID and click Next.\nEnable Client authentication and click Next.\nClick Save.\n\nWorth notin",
"chunk_index": 41,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__42",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ntication and click Next.\nClick Save.\n\nWorth noting that token introspection is just one of the available approaches to validate tokens. This can also be done with the help of standalone libraries, specific to each language and platform.\nWhen you open the client details, go to Credentials and take n",
"chunk_index": 42,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__43",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "n the client details, go to Credentials and take note of the Client Secret.\n\nHandling Secrets\nNever embed client credentials directly in your code. We recommend using environment variables or specialized solutions for secret storage.\n\nWith Keycloak configured, every time the authorization flow is tr",
"chunk_index": 43,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__44",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "onfigured, every time the authorization flow is triggered, your MCP server will receive a token like this:\ntext theme={null}\neyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICI1TjcxMGw1WW5MWk13WGZ1VlJKWGtCS3ZZMzZzb3JnRG5scmlyZ2tlTHlzIn0.eyJleHAiOjE3NTU1NDA4MTcsImlhdCI6MTc1NTU0MDc1NywiYXV0aF90aW1lIjo",
"chunk_index": 44,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__45",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "TU1NDA4MTcsImlhdCI6MTc1NTU0MDc1NywiYXV0aF90aW1lIjoxNzU1NTM4ODg4LCJqdGkiOiJvbnJ0YWM6YjM0MDgwZmYtODQwNC02ODY3LTgxYmUtMTIzMWI1MDU5M2E4IiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL3JlYWxtcy9tYXN0ZXIiLCJhdWQiOiJodHRwOi8vbG9jYWxob3N0OjMwMDAiLCJzdWIiOiIzM2VkNmM2Yi1jNmUwLTQ5MjgtYTE2MS1mMmY2OWM3YTAzYjkiLCJ0eXAiO",
"chunk_index": 45,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__46",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "2Yi1jNmUwLTQ5MjgtYTE2MS1mMmY2OWM3YTAzYjkiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiI3OTc1YTViNi04YjU5LTRhODUtOWNiYS04ZmFlYmRhYjg5NzQiLCJzaWQiOiI4ZjdlYzI3Ni0zNThmLTRjY2MtYjMxMy1kYjA4MjkwZjM3NmYiLCJzY29wZSI6Im1jcDp0b29scyJ9.P5xCRtXORly0R0EXjyqRCUx-z3J4uAOWNAvYtLPXroykZuVCCJ-K1haiQSwbURqfsVOMbL7jiV-sD6miuPzI1tmKOk",
"chunk_index": 46,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__47",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "roykZuVCCJ-K1haiQSwbURqfsVOMbL7jiV-sD6miuPzI1tmKOkN_Yct0Vp-azvj7U5rEj7U6tvPfMkg2Uj_jrIX0KOskyU2pVvGZ-5BgqaSvwTEdsGu_V3_E0xDuSBq2uj_wmhqiyTFm5lJ1WkM3Hnxxx1_AAnTj7iOKMFZ4VCwMmk8hhSC7clnDauORc0sutxiJuYUZzxNiNPkmNeQtMCGqWdP1igcbWbrfnNXhJ6NswBOuRbh97_QraET3hl-CNmyS6C72Xc0aOwR_uJ7xVSBTD02OaQ1JA6kjCATz30kG",
"chunk_index": 47,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__48",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "T3hl-CNmyS6C72Xc0aOwR_uJ7xVSBTD02OaQ1JA6kjCATz30kGYg\nDecoded, it will look like this:\njson theme={null}\n{\n \"alg\": \"RS256\",\n \"typ\": \"JWT\",\n \"kid\": \"5N710l5YnLZMwXfuVRJXkBKvY36sorgDnlrirgkeLys\"\n}.{\n \"exp\": 1755540817,\n \"iat\": 1755540757,\n \"auth_time\": 1755538888,\n \"jti\": \"onrtac:b34080ff-8404-6867-81b",
"chunk_index": 48,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__49",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "1755538888,\n \"jti\": \"onrtac:b34080ff-8404-6867-81be-1231b50593a8\",\n \"iss\": \"http://localhost:8080/realms/master\",\n \"aud\": \"http://localhost:3000\",\n \"sub\": \"33ed6c6b-c6e0-4928-a161-f2f69c7a03b9\",\n \"typ\": \"Bearer\",\n \"azp\": \"7975a5b6-8b59-4a85-9cba-8faebdab8974\",\n \"sid\": \"8f7ec276-358f-4ccc-b313-db0829",
"chunk_index": 49,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__50",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "bdab8974\",\n \"sid\": \"8f7ec276-358f-4ccc-b313-db08290f376f\",\n \"scope\": \"mcp:tools\"\n}.[Signature]\n\nEmbedded Audience\nNotice the aud claim embedded in the token - it's currently set to be the URI of the test MCP server and it's inferred from the scope that we've previously configured. This will be impor",
"chunk_index": 50,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__51",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "at we've previously configured. This will be important in our implementation to validate.\n\nMCP Server Setup\nWe will now set up our MCP server to use the locally-running Keycloak authorization server. Depending on your programming language preference, you can use one of the supported MCP SDKs.\nFor ou",
"chunk_index": 51,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__52",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "you can use one of the supported MCP SDKs.\nFor our testing purposes, we will create an extremely simple MCP server that exposes two tools - one for addition and another for multiplication. The server will require authorization to access these.\n\n You can see the complete TypeScript project in the sa",
"chunk_index": 52,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__53",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "can see the complete TypeScript project in the sample repository.\nPrior to running the code below, ensure that you have a `.env` file with the following content:\n\n```env theme={null}\n# Server host/port\nHOST=localhost\nPORT=3000\n\n# Auth server location\nAUTH_HOST=localhost\nAUTH_PORT=8080\nAUTH_REALM=ma",
"chunk_index": 53,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__54",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "n\nAUTH_HOST=localhost\nAUTH_PORT=8080\nAUTH_REALM=master\n\n# Keycloak OAuth client credentials\nOAUTH_CLIENT_ID=\nOAUTH_CLIENT_SECRET=\n```\n\n`OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET` are associated with the MCP server client we created earlier.\n\nIn addit",
"chunk_index": 54,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__55",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "he MCP server client we created earlier.\n\nIn addition to implementing the MCP authorization specification, the server below also does token introspection via Keycloak to make sure that the token it receives from the client is valid. It also implements basic logging to allow you to easily diagnose an",
"chunk_index": 55,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__56",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "s basic logging to allow you to easily diagnose any issues.\n\n```typescript theme={null}\nimport \"dotenv/config\";\nimport express from \"express\";\nimport { randomUUID } from \"node:crypto\";\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StreamableHTTPServerTransport } from",
"chunk_index": 56,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__57",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "s\";\nimport { StreamableHTTPServerTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\nimport { isInitializeRequest } from \"@modelcontextprotocol/sdk/types.js\";\nimport { z } from \"zod\";\nimport cors from \"cors\";\nimport {\n mcpAuthMetadataRouter,\n getOAuthProtectedResourceMetadataUrl,",
"chunk_index": 57,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__58",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ataRouter,\n getOAuthProtectedResourceMetadataUrl,\n} from \"@modelcontextprotocol/sdk/server/auth/router.js\";\nimport { requireBearerAuth } from \"@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js\";\nimport { OAuthMetadata } from \"@modelcontextprotocol/sdk/shared/auth.js\";\nimport { checkReso",
"chunk_index": 58,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__59",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "xtprotocol/sdk/shared/auth.js\";\nimport { checkResourceAllowed } from \"@modelcontextprotocol/sdk/shared/auth-utils.js\";\nconst CONFIG = {\n host: process.env.HOST || \"localhost\",\n port: Number(process.env.PORT) || 3000,\n auth: {\n host: process.env.AUTH_HOST || process.env.HOST || \"localhost\",\n port: Nu",
"chunk_index": 59,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__60",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "HOST || process.env.HOST || \"localhost\",\n port: Number(process.env.AUTH_PORT) || 8080,\n realm: process.env.AUTH_REALM || \"master\",\n clientId: process.env.OAUTH_CLIENT_ID || \"mcp-server\",\n clientSecret: process.env.OAUTH_CLIENT_SECRET || \"\",\n },\n};\n\nfunction createOAuthUrls() {\n const authBaseUrl = n",
"chunk_index": 60,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__61",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "unction createOAuthUrls() {\n const authBaseUrl = new URL(\n `http://${CONFIG.auth.host}:${CONFIG.auth.port}/realms/${CONFIG.auth.realm}/`,\n );\n return {\n issuer: authBaseUrl.toString(),\n introspection_endpoint: new URL(\n \"protocol/openid-connect/token/introspect\",\n authBaseUrl,\n ).toString(),\n author",
"chunk_index": 61,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__62",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "/introspect\",\n authBaseUrl,\n ).toString(),\n authorization_endpoint: new URL(\n \"protocol/openid-connect/auth\",\n authBaseUrl,\n ).toString(),\n token_endpoint: new URL(\n \"protocol/openid-connect/token\",\n authBaseUrl,\n ).toString(),\n };\n}\n\nfunction createRequestLogger() {\n return (req: any, res: any, nex",
"chunk_index": 62,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__63",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "RequestLogger() {\n return (req: any, res: any, next: any) => {\n const start = Date.now();\n res.on(\"finish\", () => {\n const ms = Date.now() - start;\n console.log(\n `${req.method} ${req.originalUrl} -> ${res.statusCode} ${ms}ms`,\n );\n });\n next();\n };\n}\n\nconst app = express();\n\napp.use(\n express.json(",
"chunk_index": 63,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__64",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "}\n\nconst app = express();\n\napp.use(\n express.json({\n verify: (req: any, _res, buf) => {\n req.rawBody = buf?.toString() ?? \"\";\n },\n }),\n);\n\napp.use(\n cors({\n origin: \"*\",\n exposedHeaders: [\"Mcp-Session-Id\"],\n }),\n);\n\napp.use(createRequestLogger());\n\nconst mcpServerUrl = new URL(`http://${CONFIG.host}",
"chunk_index": 64,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__65",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "onst mcpServerUrl = new URL(`http://${CONFIG.host}:${CONFIG.port}`);\nconst oauthUrls = createOAuthUrls();\n\nconst oauthMetadata: OAuthMetadata = {\n ...oauthUrls,\n response_types_supported: [\"code\"],\n};\n\nconst tokenVerifier = {\n verifyAccessToken: async (token: string) => {\n const endpoint = oauthMeta",
"chunk_index": 65,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__66",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "c (token: string) => {\n const endpoint = oauthMetadata.introspection_endpoint;\n\n if (!endpoint) {\n console.error(\"[auth] no introspection endpoint in metadata\");\n throw new Error(\"No token verification endpoint available in metadata\");\n }\n\n const params = new URLSearchParams({\n token: token,\n client",
"chunk_index": 66,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__67",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ams = new URLSearchParams({\n token: token,\n client_id: CONFIG.auth.clientId,\n });\n\n if (CONFIG.auth.clientSecret) {\n params.set(\"client_secret\", CONFIG.auth.clientSecret);\n }\n\n let response: Response;\n try {\n response = await fetch(endpoint, {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"applicati",
"chunk_index": 67,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__68",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "d: \"POST\",\n headers: {\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n },\n body: params.toString(),\n });\n } catch (e) {\n console.error(\"[auth] introspection fetch threw\", e);\n throw e;\n }\n\n if (!response.ok) {\n const txt = await response.text();\n console.error(\"[auth] introspection non-OK\", {",
"chunk_index": 68,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__69",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": ");\n console.error(\"[auth] introspection non-OK\", { status: response.status });\n\n try {\n const obj = JSON.parse(txt);\n console.log(JSON.stringify(obj, null, 2));\n } catch {\n console.error(txt);\n }\n throw new Error(`Invalid or expired token: ${txt}`);\n }\n\n let data: any;\n try {\n data = await response.",
"chunk_index": 69,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__70",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "}\n\n let data: any;\n try {\n data = await response.json();\n } catch (e) {\n const txt = await response.text();\n console.error(\"[auth] failed to parse introspection JSON\", {\n error: String(e),\n body: txt,\n });\n throw e;\n }\n\n if (data.active === false) {\n throw new Error(\"Inactive token\");\n }\n\n if (!dat",
"chunk_index": 70,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__71",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "throw new Error(\"Inactive token\");\n }\n\n if (!data.aud) {\n throw new Error(\"Resource indicator (aud) missing\");\n }\n\n const audiences: string[] = Array.isArray(data.aud) ? data.aud : [data.aud];\n const allowed = audiences.some((a) =>\n checkResourceAllowed({\n requestedResource: a,\n configuredResource",
"chunk_index": 71,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__72",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "lowed({\n requestedResource: a,\n configuredResource: mcpServerUrl,\n }),\n );\n if (!allowed) {\n throw new Error(\n `None of the provided audiences are allowed. Expected ${mcpServerUrl}, got: ${audiences.join(\", \")}`,\n );\n }\n\n return {\n token,\n clientId: data.client_id,\n scopes: data.scope ? data.scope.s",
"chunk_index": 72,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__73",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "data.client_id,\n scopes: data.scope ? data.scope.split(\" \") : [],\n expiresAt: data.exp,\n };\n },\n};\napp.use(\n mcpAuthMetadataRouter({\n oauthMetadata,\n resourceServerUrl: mcpServerUrl,\n scopesSupported: [\"mcp:tools\"],\n resourceName: \"MCP Demo Server\",\n }),\n);\n\nconst authMiddleware = requireBearerAuth(",
"chunk_index": 73,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__74",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "}),\n);\n\nconst authMiddleware = requireBearerAuth({\n verifier: tokenVerifier,\n requiredScopes: [],\n resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(mcpServerUrl),\n});\n\nconst transports: { [sessionId: string]: StreamableHTTPServerTransport } = {};\n\nfunction createMcpServer() {\n const server",
"chunk_index": 74,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__75",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "= {};\n\nfunction createMcpServer() {\n const server = new McpServer({\n name: \"example-server\",\n version: \"1.0.0\",\n });\n\n server.registerTool(\n \"add\",\n {\n title: \"Addition Tool\",\n description: \"Add two numbers together\",\n inputSchema: {\n a: z.number().describe(\"First number to add\"),\n b: z.number().de",
"chunk_index": 75,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__76",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "describe(\"First number to add\"),\n b: z.number().describe(\"Second number to add\"),\n },\n },\n async ({ a, b }) => ({\n content: [{ type: \"text\", text: `${a} + ${b} = ${a + b}` }],\n }),\n );\n\n server.registerTool(\n \"multiply\",\n {\n title: \"Multiplication Tool\",\n description: \"Multiply two numbers together\"",
"chunk_index": 76,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__77",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ol\",\n description: \"Multiply two numbers together\",\n inputSchema: {\n x: z.number().describe(\"First number to multiply\"),\n y: z.number().describe(\"Second number to multiply\"),\n },\n },\n async ({ x, y }) => ({\n content: [{ type: \"text\", text: `${x} × ${y} = ${x * y}` }],\n }),\n );\n\n return server;\n}\n\nco",
"chunk_index": 77,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__78",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "y} = ${x * y}` }],\n }),\n );\n\n return server;\n}\n\nconst mcpPostHandler = async (req: express.Request, res: express.Response) => {\n const sessionId = req.headers[\"mcp-session-id\"] as string | undefined;\n let transport: StreamableHTTPServerTransport;\n\n if (sessionId && transports[sessionId]) {\n transpor",
"chunk_index": 78,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__79",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "f (sessionId && transports[sessionId]) {\n transport = transports[sessionId];\n } else if (!sessionId && isInitializeRequest(req.body)) {\n transport = new StreamableHTTPServerTransport({\n sessionIdGenerator: () => randomUUID(),\n onsessioninitialized: (sessionId) => {\n transports[sessionId] = transport",
"chunk_index": 79,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__80",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "sessionId) => {\n transports[sessionId] = transport;\n },\n });\n\n transport.onclose = () => {\n if (transport.sessionId) {\n delete transports[transport.sessionId];\n }\n };\n\n const server = createMcpServer();\n await server.connect(transport);\n } else {\n res.status(400).json({\n jsonrpc: \"2.0\",\n error: {\n c",
"chunk_index": 80,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__81",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "s.status(400).json({\n jsonrpc: \"2.0\",\n error: {\n code: -32000,\n message: \"Bad Request: No valid session ID provided\",\n },\n id: null,\n });\n return;\n }\n\n await transport.handleRequest(req, res, req.body);\n};\n\nconst handleSessionRequest = async (\n req: express.Request,\n res: express.Response,\n) => {\n c",
"chunk_index": 81,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__82",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "express.Request,\n res: express.Response,\n) => {\n const sessionId = req.headers[\"mcp-session-id\"] as string | undefined;\n if (!sessionId || !transports[sessionId]) {\n res.status(400).send(\"Invalid or missing session ID\");\n return;\n }\n\n const transport = transports[sessionId];\n await transport.handleR",
"chunk_index": 82,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__83",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "= transports[sessionId];\n await transport.handleRequest(req, res);\n};\n\napp.post(\"/\", authMiddleware, mcpPostHandler);\napp.get(\"/\", authMiddleware, handleSessionRequest);\napp.delete(\"/\", authMiddleware, handleSessionRequest);\n\napp.listen(CONFIG.port, CONFIG.host, () => {\n console.log(`🚀 MCP Server r",
"chunk_index": 83,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__84",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "CONFIG.host, () => {\n console.log(`🚀 MCP Server running on ${mcpServerUrl.origin}`);\n console.log(`📡 MCP endpoint available at ${mcpServerUrl.origin}`);\n console.log(\n `🔐 OAuth metadata available at ${getOAuthProtectedResourceMetadataUrl(mcpServerUrl)}`,\n );\n});\n```\n\nWhen you run the server, you ca",
"chunk_index": 84,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__85",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "l)}`,\n );\n});\n```\n\nWhen you run the server, you can add it to your MCP client, such as Visual Studio Code, by providing the MCP server endpoint.\n\nFor more details about implementing MCP servers in TypeScript, refer to the [TypeScript SDK documentation](https://github.com/modelcontextprotocol/typescr",
"chunk_index": 85,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__86",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "n](https://github.com/modelcontextprotocol/typescript-sdk).\n\n You can see the complete Python project in the sample repository.\nTo simplify our authorization interaction, in Python scenarios we rely on [FastMCP](https://gofastmcp.com/getting-started/welcome). A lot of the conventions around authoriz",
"chunk_index": 86,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__87",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "welcome). A lot of the conventions around authorization, like the endpoints and token validation logic, are consistent across languages, but some offer simpler ways in integrating them in production scenarios.\n\nPrior to writing the actual server, we need to set up our configuration in `config.py` -",
"chunk_index": 87,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__88",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "need to set up our configuration in `config.py` - the contents are entirely based on your local server setup:\n\n```python theme={null}\n\"\"\"Configuration settings for the MCP auth server.\"\"\"\n\nimport os\nfrom typing import Optional\n\nclass Config:\n \"\"\"Configuration class that loads from environment variab",
"chunk_index": 88,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__89",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "iguration class that loads from environment variables with sensible defaults.\"\"\"\n\n # Server settings\n HOST: str = os.getenv(\"HOST\", \"localhost\")\n PORT: int = int(os.getenv(\"PORT\", \"3000\"))\n\n # Auth server settings\n AUTH_HOST: str = os.getenv(\"AUTH_HOST\", \"localhost\")\n AUTH_PORT: int = int(os.getenv(",
"chunk_index": 89,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__90",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ST\", \"localhost\")\n AUTH_PORT: int = int(os.getenv(\"AUTH_PORT\", \"8080\"))\n AUTH_REALM: str = os.getenv(\"AUTH_REALM\", \"master\")\n\n # OAuth client settings\n OAUTH_CLIENT_ID: str = os.getenv(\"OAUTH_CLIENT_ID\", \"mcp-server\")\n OAUTH_CLIENT_SECRET: str = os.getenv(\"OAUTH_CLIENT_SECRET\", \"UO3rmozkFFkXr0QxPTkz",
"chunk_index": 90,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__91",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "etenv(\"OAUTH_CLIENT_SECRET\", \"UO3rmozkFFkXr0QxPTkzZ0LMXDidIikB\")\n\n # Server settings\n MCP_SCOPE: str = os.getenv(\"MCP_SCOPE\", \"mcp:tools\")\n OAUTH_STRICT: bool = os.getenv(\"OAUTH_STRICT\", \"false\").lower() in (\"true\", \"1\", \"yes\")\n TRANSPORT: str = os.getenv(\"TRANSPORT\", \"streamable-http\")\n\n @property",
"chunk_index": 91,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__92",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "etenv(\"TRANSPORT\", \"streamable-http\")\n\n @property\n def server_url(self) -> str:\n \"\"\"Build the server URL.\"\"\"\n return f\"http://{self.HOST}:{self.PORT}\"\n\n @property\n def auth_base_url(self) -> str:\n \"\"\"Build the auth server base URL.\"\"\"\n return f\"http://{self.AUTH_HOST}:{self.AUTH_PORT}/realms/{self.A",
"chunk_index": 92,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__93",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "//{self.AUTH_HOST}:{self.AUTH_PORT}/realms/{self.AUTH_REALM}/\"\n\n def validate(self) -> None:\n \"\"\"Validate configuration.\"\"\"\n if self.TRANSPORT not in [\"sse\", \"streamable-http\"]:\n raise ValueError(f\"Invalid transport: {self.TRANSPORT}. Must be 'sse' or 'streamable-http'\")\n\n# Global configuration inst",
"chunk_index": 93,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__94",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "r 'streamable-http'\")\n\n# Global configuration instance\nconfig = Config()\n\n```\n\nThe server implementation is as follows:\n\n```python theme={null}\nimport datetime\nimport logging\nfrom typing import Any\n\nfrom pydantic import AnyHttpUrl\n\nfrom mcp.server.auth.settings import AuthSettings\nfrom mcp.server.fa",
"chunk_index": 94,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__95",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "th.settings import AuthSettings\nfrom mcp.server.fastmcp.server import FastMCP\n\nfrom .config import config\nfrom .token_verifier import IntrospectionTokenVerifier\n\nlogger = logging.getLogger(__name__)\n\ndef create_oauth_urls() -> dict[str, str]:\n \"\"\"Create OAuth URLs based on configuration (Keycloak-st",
"chunk_index": 95,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__96",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ate OAuth URLs based on configuration (Keycloak-style).\"\"\"\n from urllib.parse import urljoin\n\n auth_base_url = config.auth_base_url\n\n return {\n \"issuer\": auth_base_url,\n \"introspection_endpoint\": urljoin(auth_base_url, \"protocol/openid-connect/token/introspect\"),\n \"authorization_endpoint\": urljoin(a",
"chunk_index": 96,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__97",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "introspect\"),\n \"authorization_endpoint\": urljoin(auth_base_url, \"protocol/openid-connect/auth\"),\n \"token_endpoint\": urljoin(auth_base_url, \"protocol/openid-connect/token\"),\n }\n\ndef create_server() -> FastMCP:\n \"\"\"Create and configure the FastMCP server.\"\"\"\n\n config.validate()\n\n oauth_urls = create_o",
"chunk_index": 97,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__98",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "er.\"\"\"\n\n config.validate()\n\n oauth_urls = create_oauth_urls()\n\n token_verifier = IntrospectionTokenVerifier(\n introspection_endpoint=oauth_urls[\"introspection_endpoint\"],\n server_url=config.server_url,\n client_id=config.OAUTH_CLIENT_ID,\n client_secret=config.OAUTH_CLIENT_SECRET,\n )\n\n app = FastMCP(",
"chunk_index": 98,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__99",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "t=config.OAUTH_CLIENT_SECRET,\n )\n\n app = FastMCP(\n name=\"MCP Resource Server\",\n instructions=\"Resource Server that validates tokens via Authorization Server introspection\",\n host=config.HOST,\n port=config.PORT,\n debug=True,\n streamable_http_path=\"/\",\n token_verifier=token_verifier,\n auth=AuthSetting",
"chunk_index": 99,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__100",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "token_verifier=token_verifier,\n auth=AuthSettings(\n issuer_url=AnyHttpUrl(oauth_urls[\"issuer\"]),\n required_scopes=[config.MCP_SCOPE],\n resource_server_url=AnyHttpUrl(config.server_url),\n ),\n )\n\n @app.tool()\n async def add_numbers(a: float, b: float) -> dict[str, Any]:\n \"\"\"\n Add two numbers togethe",
"chunk_index": 100,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__101",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": ") -> dict[str, Any]:\n \"\"\"\n Add two numbers together.\n This tool demonstrates basic arithmetic operations with OAuth authentication.\n\n Args:\n a: The first number to add\n b: The second number to add\n \"\"\"\n result = a + b\n return {\n \"operation\": \"addition\",\n \"operand_a\": a,\n \"operand_b\": b,\n \"result\": r",
"chunk_index": 101,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__102",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "n\",\n \"operand_a\": a,\n \"operand_b\": b,\n \"result\": result,\n \"timestamp\": datetime.datetime.now().isoformat()\n }\n\n @app.tool()\n async def multiply_numbers(x: float, y: float) -> dict[str, Any]:\n \"\"\"\n Multiply two numbers together.\n This tool demonstrates basic arithmetic operations with OAuth authentic",
"chunk_index": 102,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__103",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "s basic arithmetic operations with OAuth authentication.\n\n Args:\n x: The first number to multiply\n y: The second number to multiply\n \"\"\"\n result = x * y\n return {\n \"operation\": \"multiplication\",\n \"operand_x\": x,\n \"operand_y\": y,\n \"result\": result,\n \"timestamp\": datetime.datetime.now().isoformat()\n }",
"chunk_index": 103,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__104",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "timestamp\": datetime.datetime.now().isoformat()\n }\n\n return app\n\ndef main() -> int:\n \"\"\"\n Run the MCP Resource Server.\n\n This server:\n - Provides RFC 9728 Protected Resource Metadata\n - Validates tokens via Authorization Server introspection\n - Serves MCP tools requiring authentication\n\n Configurati",
"chunk_index": 104,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__105",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "s MCP tools requiring authentication\n\n Configuration is loaded from config.py and environment variables.\n \"\"\"\n logging.basicConfig(level=logging.INFO)\n\n try:\n config.validate()\n oauth_urls = create_oauth_urls()\n\n except ValueError as e:\n logger.error(\"Configuration error: %s\", e)\n return 1\n\n try:\n m",
"chunk_index": 105,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__106",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "(\"Configuration error: %s\", e)\n return 1\n\n try:\n mcp_server = create_server()\n\n logger.info(\"Starting MCP Server on %s:%s\", config.HOST, config.PORT)\n logger.info(\"Authorization Server: %s\", oauth_urls[\"issuer\"])\n logger.info(\"Transport: %s\", config.TRANSPORT)\n\n mcp_server.run(transport=config.TRANS",
"chunk_index": 106,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__107",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "TRANSPORT)\n\n mcp_server.run(transport=config.TRANSPORT)\n return 0\n\n except Exception:\n logger.exception(\"Server error\")\n return 1\n\nif __name__ == \"__main__\":\n exit(main())\n```\n\nLastly, the token verification logic is delegated entirely to `token_verifier.py`, ensuring that we can use the Keycloak in",
"chunk_index": 107,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__108",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "fier.py`, ensuring that we can use the Keycloak introspection endpoint to verify the validity of any credential artifacts\n\n```python theme={null}\n\"\"\"Token verifier implementation using OAuth 2.0 Token Introspection (RFC 7662).\"\"\"\n\nimport logging\nfrom typing import Any\n\nfrom mcp.server.auth.provider",
"chunk_index": 108,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__109",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "typing import Any\n\nfrom mcp.server.auth.provider import AccessToken, TokenVerifier\nfrom mcp.shared.auth_utils import check_resource_allowed, resource_url_from_server_url\n\nlogger = logging.getLogger(__name__)\n\nclass IntrospectionTokenVerifier(TokenVerifier):\n \"\"\"Token verifier that uses OAuth 2.0 To",
"chunk_index": 109,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__110",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "rifier):\n \"\"\"Token verifier that uses OAuth 2.0 Token Introspection (RFC 7662).\n \"\"\"\n\n def __init__(\n self,\n introspection_endpoint: str,\n server_url: str,\n client_id: str,\n client_secret: str,\n ):\n self.introspection_endpoint = introspection_endpoint\n self.server_url = server_url\n self.client_id =",
"chunk_index": 110,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__111",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "t\n self.server_url = server_url\n self.client_id = client_id\n self.client_secret = client_secret\n self.resource_url = resource_url_from_server_url(server_url)\n\n async def verify_token(self, token: str) -> AccessToken | None:\n \"\"\"Verify token via introspection endpoint.\"\"\"\n import httpx\n\n if not self.",
"chunk_index": 111,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__112",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "spection endpoint.\"\"\"\n import httpx\n\n if not self.introspection_endpoint.startswith((\"https://\", \"http://localhost\", \"http://127.0.0.1\")):\n return None\n\n timeout = httpx.Timeout(10.0, connect=5.0)\n limits = httpx.Limits(max_connections=10, max_keepalive_connections=5)\n\n async with httpx.AsyncClient(",
"chunk_index": 112,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__113",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ive_connections=5)\n\n async with httpx.AsyncClient(\n timeout=timeout,\n limits=limits,\n verify=True,\n ) as client:\n try:\n form_data = {\n \"token\": token,\n \"client_id\": self.client_id,\n \"client_secret\": self.client_secret,\n }\n headers = {\"Content-Type\": \"application/x-www-form-urlencoded\"}\n\n response =",
"chunk_index": 113,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__114",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "\"application/x-www-form-urlencoded\"}\n\n response = await client.post(\n self.introspection_endpoint,\n data=form_data,\n headers=headers,\n )\n\n if response.status_code != 200:\n return None\n\n data = response.json()\n if not data.get(\"active\", False):\n return None\n\n if not self._validate_resource(data):\n re",
"chunk_index": 114,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__115",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "n None\n\n if not self._validate_resource(data):\n return None\n\n return AccessToken(\n token=token,\n client_id=data.get(\"client_id\", \"unknown\"),\n scopes=data.get(\"scope\", \"\").split() if data.get(\"scope\") else [],\n expires_at=data.get(\"exp\"),\n resource=data.get(\"aud\"), # Include resource in token\n )\n\n ex",
"chunk_index": 115,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__116",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ta.get(\"aud\"), # Include resource in token\n )\n\n except Exception as e:\n return None\n\n def _validate_resource(self, token_data: dict[str, Any]) -> bool:\n \"\"\"Validate token was issued for this resource server.\n\n Rules:\n - Reject if 'aud' missing.\n - Accept if any audience entry matches the derived res",
"chunk_index": 116,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__117",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "cept if any audience entry matches the derived resource URL.\n - Supports string or list forms per JWT spec.\n \"\"\"\n if not self.server_url or not self.resource_url:\n return False\n\n aud: list[str] | str | None = token_data.get(\"aud\")\n if isinstance(aud, list):\n return any(self._is_valid_resource(a) for",
"chunk_index": 117,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__118",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "list):\n return any(self._is_valid_resource(a) for a in aud)\n if isinstance(aud, str):\n return self._is_valid_resource(aud)\n return False\n\n def _is_valid_resource(self, resource: str) -> bool:\n \"\"\"Check if the given resource matches our server.\"\"\"\n return check_resource_allowed(self.resource_url, re",
"chunk_index": 118,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__119",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "eturn check_resource_allowed(self.resource_url, resource)\n```\n\nFor more details, see the [Python SDK documentation](https://github.com/modelcontextprotocol/python-sdk).\n\n You can see the complete C# project in the sample repository.\nTo set up authorization in your MCP server using the MCP C# SDK, yo",
"chunk_index": 119,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__120",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "zation in your MCP server using the MCP C# SDK, you can lean on the standard ASP.NET Core builder pattern. Instead of using the introspection endpoint provided by Keycloak, we will use built-in ASP.NET Core capabilities for token validation.\n\n```csharp theme={null}\nusing Microsoft.AspNetCore.Authent",
"chunk_index": 120,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__121",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "rp theme={null}\nusing Microsoft.AspNetCore.Authentication.JwtBearer;\nusing Microsoft.IdentityModel.Tokens;\nusing ModelContextProtocol.AspNetCore.Authentication;\nusing ProtectedMcpServer.Tools;\nusing System.Security.Claims;\n\nvar builder = WebApplication.CreateBuilder(args);\n\nvar serverUrl = \"http://l",
"chunk_index": 121,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__122",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "on.CreateBuilder(args);\n\nvar serverUrl = \"http://localhost:3000/\";\nvar authorizationServerUrl = \"http://localhost:8080/realms/master/\";\n\nbuilder.Services.AddAuthentication(options =>\n{\n options.DefaultChallengeScheme = McpAuthenticationDefaults.AuthenticationScheme;\n options.DefaultAuthenticateSchem",
"chunk_index": 122,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__123",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "nticationScheme;\n options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;\n})\n.AddJwtBearer(options =>\n{\n options.Authority = authorizationServerUrl;\n var normalizedServerAudience = serverUrl.TrimEnd('/');\n options.TokenValidationParameters = new TokenValidationParameters\n {\n Vali",
"chunk_index": 123,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__124",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "arameters = new TokenValidationParameters\n {\n ValidIssuer = authorizationServerUrl,\n ValidAudiences = new[] { normalizedServerAudience, serverUrl },\n AudienceValidator = (audiences, securityToken, validationParameters) =>\n {\n if (audiences == null) return false;\n foreach (var aud in audiences)\n {\n i",
"chunk_index": 124,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__125",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "eturn false;\n foreach (var aud in audiences)\n {\n if (string.Equals(aud.TrimEnd('/'), normalizedServerAudience, StringComparison.OrdinalIgnoreCase))\n {\n return true;\n }\n }\n return false;\n }\n };\n\n options.RequireHttpsMetadata = false; // Set to true in production\n\n options.Events = new JwtBearerEvents",
"chunk_index": 125,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__126",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "production\n\n options.Events = new JwtBearerEvents\n {\n OnTokenValidated = context =>\n {\n var name = context.Principal?.Identity?.Name ?? \"unknown\";\n var email = context.Principal?.FindFirstValue(\"preferred_username\") ?? \"unknown\";\n Console.WriteLine($\"Token validated for: {name} ({email})\");\n return",
"chunk_index": 126,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__127",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "$\"Token validated for: {name} ({email})\");\n return Task.CompletedTask;\n },\n OnAuthenticationFailed = context =>\n {\n Console.WriteLine($\"Authentication failed: {context.Exception.Message}\");\n return Task.CompletedTask;\n },\n };\n})\n.AddMcp(options =>\n{\n options.ResourceMetadata = new()\n {\n Resource = n",
"chunk_index": 127,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__128",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "options.ResourceMetadata = new()\n {\n Resource = new Uri(serverUrl),\n ResourceDocumentation = new Uri(\"https://docs.example.com/api/math\"),\n AuthorizationServers = { new Uri(authorizationServerUrl) },\n ScopesSupported = [\"mcp:tools\"]\n };\n});\n\nbuilder.Services.AddAuthorization();\n\nbuilder.Services.Ad",
"chunk_index": 128,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__129",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": ".Services.AddAuthorization();\n\nbuilder.Services.AddHttpContextAccessor();\nbuilder.Services.AddMcpServer()\n .WithTools()\n .WithHttpTransport();\n\nvar app = builder.Build();\n\napp.UseAuthentication();\napp.UseAuthorization();\n\napp.MapMcp().RequireAuthorization();\n\nConsole.WriteLine($\"Starting",
"chunk_index": 129,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__130",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ireAuthorization();\n\nConsole.WriteLine($\"Starting MCP server with authorization at {serverUrl}\");\nConsole.WriteLine($\"Using Keycloak server at {authorizationServerUrl}\");\nConsole.WriteLine($\"Protected Resource Metadata URL: {serverUrl}.well-known/oauth-protected-resource\");\nConsole.WriteLine(\"Expose",
"chunk_index": 130,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__131",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "th-protected-resource\");\nConsole.WriteLine(\"Exposed Math tools: Add, Multiply\");\nConsole.WriteLine(\"Press Ctrl+C to stop the server\");\n\napp.Run(serverUrl);\n```\n\nFor more details, see the [C# SDK documentation](https://github.com/modelcontextprotocol/csharp-sdk).\n\nTesting the MCP Server\nFor testing p",
"chunk_index": 131,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__132",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "csharp-sdk).\n\nTesting the MCP Server\nFor testing purposes, we will be using Visual Studio Code, but any client that supports MCP and the new authorization specification will fit.\nPress Cmd + Shift + P and select MCP: Add server.... Select HTTP and enter http://localhost:3000. Give the server a uniqu",
"chunk_index": 132,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__133",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ter http://localhost:3000. Give the server a unique name to be used inside Visual Studio Code. In mcp.json you should now see an entry like this:\njson theme={null}\n\"my-mcp-server-18676652\": {\n \"url\": \"http://localhost:3000\",\n \"type\": \"http\"\n}\nOn connection, you will be taken to the browser, where yo",
"chunk_index": 133,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__134",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ection, you will be taken to the browser, where you will be prompted to consent to Visual Studio Code having access to the mcp:tools scope.\n\nAfter consenting, you will see the tools listed right above the server entry in mcp.json.\n\nYou will be able to invoke individual tools with the help of the # s",
"chunk_index": 134,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__135",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "o invoke individual tools with the help of the # sign in the chat view.\n\nCommon Pitfalls and How to Avoid Them\nFor comprehensive security guidance, including attack vectors, mitigation strategies, and implementation best practices, make sure to read through Security Best Practices. A few key issues",
"chunk_index": 135,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__136",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "through Security Best Practices. A few key issues are called out below.\n\nDo not implement token validation or authorization logic by yourself. Use off-the-shelf, well-tested, and secure libraries for things like token validation or authorization decisions. Doing everything from scratch means that yo",
"chunk_index": 136,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__137",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "sions. Doing everything from scratch means that you're more likely to implement things incorrectly unless you are a security expert.\nUse short-lived access tokens. Depending on the authorization server used, this setting might be customizable. We recommend to not use long-lived tokens - if a malicio",
"chunk_index": 137,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__138",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "ommend to not use long-lived tokens - if a malicious actor steals them, they will be able to maintain their access for longer periods.\nAlways validate tokens. Just because your server received a token does not mean that the token is valid or that it's meant for your server. Always verify that what y",
"chunk_index": 138,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__139",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "s meant for your server. Always verify that what your MCP server is getting from the client matches the required constraints.\nStore tokens in secure, encrypted storage. In certain scenarios, you might need to cache tokens server-side. If that is the case, ensure that the storage has the right access",
"chunk_index": 139,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__140",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "case, ensure that the storage has the right access controls and cannot be easily exfiltrated by malicious parties with access to your server. You should also implement robust cache eviction policies to ensure that your MCP server is not re-using expired or otherwise invalid tokens.\nEnforce HTTPS in",
"chunk_index": 140,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__141",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "red or otherwise invalid tokens.\nEnforce HTTPS in production. Do not accept tokens or redirect callbacks over plain HTTP except for localhost during development.\nLeast-privilege scopes. Don't use catch‑all scopes. Split access per tool or capability where possible and verify required scopes per rout",
"chunk_index": 141,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__142",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "where possible and verify required scopes per route/tool on the resource server.\nDon't log credentials. Never log Authorization headers, tokens, codes, or secrets. Scrub query strings and headers. Redact sensitive fields in structured logs.\nSeparate app vs. resource server credentials. Don't reuse y",
"chunk_index": 142,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__143",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "app vs. resource server credentials. Don't reuse your MCP server's client secret for end‑user flows. Store all secrets in a proper secret manager, not in source control.\nReturn proper challenges. On 401, include WWW-Authenticate with Bearer, realm, and resource_metadata so clients can discover how t",
"chunk_index": 143,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__144",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "nd resource_metadata so clients can discover how to authenticate.\nDCR (Dynamic Client Registration) controls. If enabled, be aware of constraints specific to your organization, such as trusted hosts, required vetting, and audited registrations. Unauthenticated DCR means that anyone can register any",
"chunk_index": 144,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__145",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "henticated DCR means that anyone can register any client with your authorization server.\nMulti‑tenant/realm mix-ups. Pin to a single issuer/tenant unless explicitly multi‑tenant. Reject tokens from other realms even if signed by the same authorization server.\nAudience/resource indicator misuse. Don'",
"chunk_index": 145,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__146",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "n server.\nAudience/resource indicator misuse. Don't configure or accept generic audiences (like api) or unrelated resources. Require the audience/resource to match your configured server.\nError detail leakage. Return generic messages to clients, but log detailed reasons with correlation IDs internal",
"chunk_index": 146,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__147",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "log detailed reasons with correlation IDs internally to aid troubleshooting without exposing internals.\nSession identifier hardening. Treat Mcp-Session-Id as untrusted input; never tie authorization to it. Regenerate on auth changes and validate lifecycle server‑side.\n\nRelated Standards and Document",
"chunk_index": 147,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__148",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "cycle server‑side.\n\nRelated Standards and Documentation\nMCP authorization builds on these well-established standards:\n\nOAuth 2.1: The core authorization framework\nRFC 8414: Authorization Server Metadata discovery\nRFC 7591: Dynamic Client Registration\nRFC 9728: Protected Resource Metadata\nRFC 8707: R",
"chunk_index": 148,
"total_chunks": 150
},
{
"chunk_id": "md_authorization_8784292d__149",
"doc_id": "md_authorization_8784292d",
"title": "Understanding Authorization in MCP",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\authorization.md",
"filename": "authorization.md",
"file_path": "authorization.md",
"updated_at": "1760788399.6907165",
"text": "RFC 9728: Protected Resource Metadata\nRFC 8707: Resource Indicators\n\nFor additional details, refer to:\n\nAuthorization Specification\nSecurity Best Practices\nAvailable MCP SDKs\n\nUnderstanding these standards will help you implement authorization correctly and troubleshoot issues when they arise.",
"chunk_index": 149,
"total_chunks": 150
},
{
"chunk_id": "md_build-client_2e39af9f__0",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "Build an MCP client\n\nGet started building your own client that can integrate with all MCP servers.\n\nIn this tutorial, you'll learn how to build an LLM-powered chatbot client that connects to MCP servers.\nBefore you begin, it helps to have gone through our Build an MCP Server tutorial so you can unde",
"chunk_index": 0,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__1",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "h our Build an MCP Server tutorial so you can understand how clients and servers communicate.\n\nYou can find the complete code for this tutorial here.\n## System Requirements\n\nBefore starting, ensure your system meets these requirements:\n\n* Mac or Windows computer\n* Latest Python version installed\n* L",
"chunk_index": 1,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__2",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ows computer\n* Latest Python version installed\n* Latest version of `uv` installed\n\n## Setting Up Your Environment\n\nFirst, create a new Python project with `uv`:\n\n\n ```bash macOS/Linux theme={null}\n # Create project directory\n uv init mcp-client\n cd mcp-client\n\n # Create virtual environmen",
"chunk_index": 2,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__3",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "lient\n cd mcp-client\n\n # Create virtual environment\n uv venv\n\n # Activate virtual environment\n source .venv/bin/activate\n\n # Install required packages\n uv add mcp anthropic python-dotenv\n\n # Remove boilerplate files\n rm main.py\n\n # Create our main file\n touch client.py\n ```\n\n ```powershell Windows t",
"chunk_index": 3,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__4",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "le\n touch client.py\n ```\n\n ```powershell Windows theme={null}\n # Create project directory\n uv init mcp-client\n cd mcp-client\n\n # Create virtual environment\n uv venv\n\n # Activate virtual environment\n .venv\\Scripts\\activate\n\n # Install required packages\n uv add mcp anthropic python-dotenv\n\n # Remove b",
"chunk_index": 4,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__5",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "s\n uv add mcp anthropic python-dotenv\n\n # Remove boilerplate files\n del main.py\n\n # Create our main file\n new-item client.py\n ```\n\n\n## Setting Up Your API Key\n\nYou'll need an Anthropic API key from the [Anthropic Console](https://console.anthropic.com/settings/keys).\n\nCreate a `.env` fil",
"chunk_index": 5,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__6",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "anthropic.com/settings/keys).\n\nCreate a `.env` file to store it:\n\n```bash theme={null}\necho \"ANTHROPIC_API_KEY=\" > .env\n```\n\nAdd `.env` to your `.gitignore`:\n\n```bash theme={null}\necho \".env\" >> .gitignore\n```\n\n\n Make sure you keep your `ANTHROPIC_API_KEY` secure!\n",
"chunk_index": 6,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__7",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "keep your `ANTHROPIC_API_KEY` secure!\n\n\n## Creating the Client\n\n### Basic Client Structure\n\nFirst, let's set up our imports and create the basic client class:\n\n```python theme={null}\nimport asyncio\nfrom typing import Optional\nfrom contextlib import AsyncExitStack\n\nfrom mcp import ClientSe",
"chunk_index": 7,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__8",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ib import AsyncExitStack\n\nfrom mcp import ClientSession, StdioServerParameters\nfrom mcp.client.stdio import stdio_client\n\nfrom anthropic import Anthropic\nfrom dotenv import load_dotenv\n\nload_dotenv() # load environment variables from .env\n\nclass MCPClient:\n def __init__(self):\n # Initialize session",
"chunk_index": 8,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__9",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "lient:\n def __init__(self):\n # Initialize session and client objects\n self.session: Optional[ClientSession] = None\n self.exit_stack = AsyncExitStack()\n self.anthropic = Anthropic()\n # methods will go here\n```\n\n### Server Connection Management\n\nNext, we'll implement the method to connect to an MCP se",
"chunk_index": 9,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__10",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "we'll implement the method to connect to an MCP server:\n\n```python theme={null}\nasync def connect_to_server(self, server_script_path: str):\n \"\"\"Connect to an MCP server\n\n Args:\n server_script_path: Path to the server script (.py or .js)\n \"\"\"\n is_python = server_script_path.endswith('.py')\n is_js = s",
"chunk_index": 10,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__11",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "on = server_script_path.endswith('.py')\n is_js = server_script_path.endswith('.js')\n if not (is_python or is_js):\n raise ValueError(\"Server script must be a .py or .js file\")\n\n command = \"python\" if is_python else \"node\"\n server_params = StdioServerParameters(\n command=command,\n args=[server_script_",
"chunk_index": 11,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__12",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "arameters(\n command=command,\n args=[server_script_path],\n env=None\n )\n\n stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))\n self.stdio, self.write = stdio_transport\n self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))",
"chunk_index": 12,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__13",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "nc_context(ClientSession(self.stdio, self.write))\n\n await self.session.initialize()\n\n # List available tools\n response = await self.session.list_tools()\n tools = response.tools\n print(\"\\nConnected to server with tools:\", [tool.name for tool in tools])\n```\n\n### Query Processing Logic\n\nNow let's add t",
"chunk_index": 13,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__14",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": ")\n```\n\n### Query Processing Logic\n\nNow let's add the core functionality for processing queries and handling tool calls:\n\n```python theme={null}\nasync def process_query(self, query: str) -> str:\n \"\"\"Process a query using Claude and available tools\"\"\"\n messages = [\n {\n \"role\": \"user\",\n \"content\": quer",
"chunk_index": 14,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__15",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "messages = [\n {\n \"role\": \"user\",\n \"content\": query\n }\n ]\n\n response = await self.session.list_tools()\n available_tools = [{\n \"name\": tool.name,\n \"description\": tool.description,\n \"input_schema\": tool.inputSchema\n } for tool in response.tools]\n\n # Initial Claude API call\n response = self.anthropic.m",
"chunk_index": 15,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__16",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "itial Claude API call\n response = self.anthropic.messages.create(\n model=\"claude-3-5-sonnet-20241022\",\n max_tokens=1000,\n messages=messages,\n tools=available_tools\n )\n\n # Process response and handle tool calls\n final_text = []\n\n assistant_message_content = []\n for content in response.content:\n if co",
"chunk_index": 16,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__17",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "tent = []\n for content in response.content:\n if content.type == 'text':\n final_text.append(content.text)\n assistant_message_content.append(content)\n elif content.type == 'tool_use':\n tool_name = content.name\n tool_args = content.input\n\n # Execute tool call\n result = await self.session.call_tool(tool",
"chunk_index": 17,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__18",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "l call\n result = await self.session.call_tool(tool_name, tool_args)\n final_text.append(f\"[Calling tool {tool_name} with args {tool_args}]\")\n\n assistant_message_content.append(content)\n messages.append({\n \"role\": \"assistant\",\n \"content\": assistant_message_content\n })\n messages.append({\n \"role\": \"user",
"chunk_index": 18,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__19",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "sage_content\n })\n messages.append({\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"tool_result\",\n \"tool_use_id\": content.id,\n \"content\": result.content\n }\n ]\n })\n\n # Get next response from Claude\n response = self.anthropic.messages.create(\n model=\"claude-3-5-sonnet-20241022\",\n max_tokens=1000,\n message",
"chunk_index": 19,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__20",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "e-3-5-sonnet-20241022\",\n max_tokens=1000,\n messages=messages,\n tools=available_tools\n )\n\n final_text.append(response.content[0].text)\n\n return \"\\n\".join(final_text)\n```\n\n### Interactive Chat Interface\n\nNow we'll add the chat loop and cleanup functionality:\n\n```python theme={null}\nasync def chat_loop",
"chunk_index": 20,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__21",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ality:\n\n```python theme={null}\nasync def chat_loop(self):\n \"\"\"Run an interactive chat loop\"\"\"\n print(\"\\nMCP Client Started!\")\n print(\"Type your queries or 'quit' to exit.\")\n\n while True:\n try:\n query = input(\"\\nQuery: \").strip()\n\n if query.lower() == 'quit':\n break\n\n response = await self.process_qu",
"chunk_index": 21,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__22",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "'quit':\n break\n\n response = await self.process_query(query)\n print(\"\\n\" + response)\n\n except Exception as e:\n print(f\"\\nError: {str(e)}\")\n\nasync def cleanup(self):\n \"\"\"Clean up resources\"\"\"\n await self.exit_stack.aclose()\n```\n\n### Main Entry Point\n\nFinally, we'll add the main execution logic:\n\n```p",
"chunk_index": 22,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__23",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "Finally, we'll add the main execution logic:\n\n```python theme={null}\nasync def main():\n if len(sys.argv) < 2:\n print(\"Usage: python client.py \")\n sys.exit(1)\n\n client = MCPClient()\n try:\n await client.connect_to_server(sys.argv[1])\n await client.chat_loop()\n finally:\n await cl",
"chunk_index": 23,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__24",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "[1])\n await client.chat_loop()\n finally:\n await client.cleanup()\n\nif __name__ == \"__main__\":\n import sys\n asyncio.run(main())\n```\n\nYou can find the complete `client.py` file [here](https://github.com/modelcontextprotocol/quickstart-resources/blob/main/mcp-client-python/client.py).\n\n## Key Components",
"chunk_index": 24,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__25",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "n/mcp-client-python/client.py).\n\n## Key Components Explained\n\n### 1. Client Initialization\n\n* The `MCPClient` class initializes with session management and API clients\n* Uses `AsyncExitStack` for proper resource management\n* Configures the Anthropic client for Claude interactions\n\n### 2. Server Conn",
"chunk_index": 25,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__26",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "client for Claude interactions\n\n### 2. Server Connection\n\n* Supports both Python and Node.js servers\n* Validates server script type\n* Sets up proper communication channels\n* Initializes the session and lists available tools\n\n### 3. Query Processing\n\n* Maintains conversation context\n* Handles Claude'",
"chunk_index": 26,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__27",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "* Maintains conversation context\n* Handles Claude's responses and tool calls\n* Manages the message flow between Claude and tools\n* Combines results into a coherent response\n\n### 4. Interactive Interface\n\n* Provides a simple command-line interface\n* Handles user input and displays responses\n* Include",
"chunk_index": 27,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__28",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "andles user input and displays responses\n* Includes basic error handling\n* Allows graceful exit\n\n### 5. Resource Management\n\n* Proper cleanup of resources\n* Error handling for connection issues\n* Graceful shutdown procedures\n\n## Common Customization Points\n\n1. **Tool Handling**\n * Modify `process_qu",
"chunk_index": 28,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__29",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "Points\n\n1. **Tool Handling**\n * Modify `process_query()` to handle specific tool types\n * Add custom error handling for tool calls\n * Implement tool-specific response formatting\n\n2. **Response Processing**\n * Customize how tool results are formatted\n * Add response filtering or transformation\n * Imp",
"chunk_index": 29,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__30",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "* Add response filtering or transformation\n * Implement custom logging\n\n3. **User Interface**\n * Add a GUI or web interface\n * Implement rich console output\n * Add command history or auto-completion\n\n## Running the Client\n\nTo run your client with any MCP server:\n\n```bash theme={null}\nuv run client.",
"chunk_index": 30,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__31",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "y MCP server:\n\n```bash theme={null}\nuv run client.py path/to/server.py # python server\nuv run client.py path/to/build/index.js # node server\n```\n\n\n If you're continuing [the weather tutorial from the server quickstart](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weat",
"chunk_index": 31,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__32",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ontextprotocol/quickstart-resources/tree/main/weather-server-python), your command might look something like this: `python client.py .../quickstart-resources/weather-server-python/weather.py`\n\n\nThe client will:\n\n1. Connect to the specified server\n2. List available tools\n3. Start an interactiv",
"chunk_index": 32,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__33",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ver\n2. List available tools\n3. Start an interactive chat session where you can:\n * Enter queries\n * See tool executions\n * Get responses from Claude\n\nHere's an example of what it should look like if connected to the weather server from the server quickstart:\n\n\n ![](\"https://mintcdn.com/m",)
\n ![](\"https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/client-claude-cli-python.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=686d6e0ae7c54f807827db111eaed7d4\")
\n\n\n## How It Works\n\nWhen you submit a query:\n\n1. The client gets the list of available tools from the server\n2. Your query is sent to Claude along with tool descriptions\n3. Claude",
"chunk_index": 39,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__40",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "to Claude along with tool descriptions\n3. Claude decides which tools (if any) to use\n4. The client executes any requested tool calls through the server\n5. Results are sent back to Claude\n6. Claude provides a natural language response\n7. The response is displayed to you\n\n## Best practices\n\n1. **Erro",
"chunk_index": 40,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__41",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "is displayed to you\n\n## Best practices\n\n1. **Error Handling**\n * Always wrap tool calls in try-catch blocks\n * Provide meaningful error messages\n * Gracefully handle connection issues\n\n2. **Resource Management**\n * Use `AsyncExitStack` for proper cleanup\n * Close connections when done\n * Handle ser",
"chunk_index": 41,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__42",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "eanup\n * Close connections when done\n * Handle server disconnections\n\n3. **Security**\n * Store API keys securely in `.env`\n * Validate server responses\n * Be cautious with tool permissions\n\n4. **Tool Names**\n * Tool names can be validated according to the format specified [here](/specification/draft",
"chunk_index": 42,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__43",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "o the format specified [here](/specification/draft/server/tools#tool-names)\n * If a tool name conforms to the specified format, it should not fail validation by an MCP client\n\n## Troubleshooting\n\n### Server Path Issues\n\n* Double-check the path to your server script is correct\n* Use the absolute path",
"chunk_index": 43,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__44",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "r server script is correct\n* Use the absolute path if the relative path isn't working\n* For Windows users, make sure to use forward slashes (/) or escaped backslashes (\\\\) in the path\n* Verify the server file has the correct extension (.py for Python or .js for Node.js)\n\nExample of correct path usag",
"chunk_index": 44,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__45",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "or .js for Node.js)\n\nExample of correct path usage:\n\n```bash theme={null}\n# Relative path\nuv run client.py ./server/weather.py\n\n# Absolute path\nuv run client.py /Users/username/projects/mcp-server/weather.py\n\n# Windows path (either format works)\nuv run client.py C:/projects/mcp-server/weather.py\nuv",
"chunk_index": 45,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__46",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "run client.py C:/projects/mcp-server/weather.py\nuv run client.py C:\\\\projects\\\\mcp-server\\\\weather.py\n```\n\n### Response Timing\n\n* The first response might take up to 30 seconds to return\n* This is normal and happens while:\n * The server initializes\n * Claude processes the query\n * Tools are being ex",
"chunk_index": 46,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__47",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "* Claude processes the query\n * Tools are being executed\n* Subsequent responses are typically faster\n* Don't interrupt the process during this initial waiting period\n\n### Common Error Messages\n\nIf you see:\n\n* `FileNotFoundError`: Check your server path\n* `Connection refused`: Ensure the server is ru",
"chunk_index": 47,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__48",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "th\n* `Connection refused`: Ensure the server is running and the path is correct\n* `Tool execution failed`: Verify the tool's required environment variables are set\n* `Timeout error`: Consider increasing the timeout in your client configuration\n\nYou can find the complete code for this tutorial here.",
"chunk_index": 48,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__49",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "an find the complete code for this tutorial here.\n## System Requirements\n\nBefore starting, ensure your system meets these requirements:\n\n* Mac or Windows computer\n* Node.js 17 or higher installed\n* Latest version of `npm` installed\n* Anthropic API key (Claude)\n\n## Setting Up Your Environment\n\nFirst,",
"chunk_index": 49,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__50",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "y (Claude)\n\n## Setting Up Your Environment\n\nFirst, let's create and set up our project:\n\n\n ```bash macOS/Linux theme={null}\n # Create project directory\n mkdir mcp-client-typescript\n cd mcp-client-typescript\n\n # Initialize npm project\n npm init -y\n\n # Install dependencies\n npm install @ant",
"chunk_index": 50,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__51",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "init -y\n\n # Install dependencies\n npm install @anthropic-ai/sdk @modelcontextprotocol/sdk dotenv\n\n # Install dev dependencies\n npm install -D @types/node typescript\n\n # Create source file\n touch index.ts\n ```\n\n ```powershell Windows theme={null}\n # Create project directory\n md mcp-client-typescript",
"chunk_index": 51,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__52",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "reate project directory\n md mcp-client-typescript\n cd mcp-client-typescript\n\n # Initialize npm project\n npm init -y\n\n # Install dependencies\n npm install @anthropic-ai/sdk @modelcontextprotocol/sdk dotenv\n\n # Install dev dependencies\n npm install -D @types/node typescript\n\n # Create source file\n new",
"chunk_index": 52,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__53",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "@types/node typescript\n\n # Create source file\n new-item index.ts\n ```\n\n\nUpdate your `package.json` to set `type: \"module\"` and a build script:\n\n```json package.json theme={null}\n{\n \"type\": \"module\",\n \"scripts\": {\n \"build\": \"tsc && chmod 755 build/index.js\"\n }\n}\n```\n\nCreate a `tsconfig.js",
"chunk_index": 53,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__54",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "55 build/index.js\"\n }\n}\n```\n\nCreate a `tsconfig.json` in the root of your project:\n\n```json tsconfig.json theme={null}\n{\n \"compilerOptions\": {\n \"target\": \"ES2022\",\n \"module\": \"Node16\",\n \"moduleResolution\": \"Node16\",\n \"outDir\": \"./build\",\n \"rootDir\": \"./\",\n \"strict\": true,\n \"esModuleInterop\": true,",
"chunk_index": 54,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__55",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "\"./\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true,\n \"forceConsistentCasingInFileNames\": true\n },\n \"include\": [\"index.ts\"],\n \"exclude\": [\"node_modules\"]\n}\n```\n\n## Setting Up Your API Key\n\nYou'll need an Anthropic API key from the [Anthropic Console](https://console.anthropic.com/",
"chunk_index": 55,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__56",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "[Anthropic Console](https://console.anthropic.com/settings/keys).\n\nCreate a `.env` file to store it:\n\n```bash theme={null}\necho \"ANTHROPIC_API_KEY=\" > .env\n```\n\nAdd `.env` to your `.gitignore`:\n\n```bash theme={null}\necho \".env\" >> .gitignore\n```\n\n\n Make sure you keep your `AN",
"chunk_index": 56,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__57",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ignore\n```\n\n\n Make sure you keep your `ANTHROPIC_API_KEY` secure!\n\n\n## Creating the Client\n\n### Basic Client Structure\n\nFirst, let's set up our imports and create the basic client class in `index.ts`:\n\n```typescript theme={null}\nimport { Anthropic } from \"@anthropic-ai/sdk\";\nimpor",
"chunk_index": 57,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__58",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "port { Anthropic } from \"@anthropic-ai/sdk\";\nimport {\n MessageParam,\n Tool,\n} from \"@anthropic-ai/sdk/resources/messages/messages.mjs\";\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\";\nimport readlin",
"chunk_index": 58,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__59",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ntextprotocol/sdk/client/stdio.js\";\nimport readline from \"readline/promises\";\nimport dotenv from \"dotenv\";\n\ndotenv.config();\n\nconst ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;\nif (!ANTHROPIC_API_KEY) {\n throw new Error(\"ANTHROPIC_API_KEY is not set\");\n}\n\nclass MCPClient {\n private mcp: Client",
"chunk_index": 59,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__60",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "t set\");\n}\n\nclass MCPClient {\n private mcp: Client;\n private anthropic: Anthropic;\n private transport: StdioClientTransport | null = null;\n private tools: Tool[] = [];\n\n constructor() {\n this.anthropic = new Anthropic({\n apiKey: ANTHROPIC_API_KEY,\n });\n this.mcp = new Client({ name: \"mcp-client-cli\"",
"chunk_index": 60,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__61",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": ");\n this.mcp = new Client({ name: \"mcp-client-cli\", version: \"1.0.0\" });\n }\n // methods will go here\n}\n```\n\n### Server Connection Management\n\nNext, we'll implement the method to connect to an MCP server:\n\n```typescript theme={null}\nasync connectToServer(serverScriptPath: string) {\n try {\n const isJs",
"chunk_index": 61,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__62",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ver(serverScriptPath: string) {\n try {\n const isJs = serverScriptPath.endsWith(\".js\");\n const isPy = serverScriptPath.endsWith(\".py\");\n if (!isJs && !isPy) {\n throw new Error(\"Server script must be a .js or .py file\");\n }\n const command = isPy\n ? process.platform === \"win32\"\n ? \"python\"\n : \"python3\"",
"chunk_index": 62,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__63",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "cess.platform === \"win32\"\n ? \"python\"\n : \"python3\"\n : process.execPath;\n\n this.transport = new StdioClientTransport({\n command,\n args: [serverScriptPath],\n });\n await this.mcp.connect(this.transport);\n\n const toolsResult = await this.mcp.listTools();\n this.tools = toolsResult.tools.map((tool) => {",
"chunk_index": 63,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__64",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "this.tools = toolsResult.tools.map((tool) => {\n return {\n name: tool.name,\n description: tool.description,\n input_schema: tool.inputSchema,\n };\n });\n console.log(\n \"Connected to server with tools:\",\n this.tools.map(({ name }) => name)\n );\n } catch (e) {\n console.log(\"Failed to connect to MCP serve",
"chunk_index": 64,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__65",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "(e) {\n console.log(\"Failed to connect to MCP server: \", e);\n throw e;\n }\n}\n```\n\n### Query Processing Logic\n\nNow let's add the core functionality for processing queries and handling tool calls:\n\n```typescript theme={null}\nasync processQuery(query: string) {\n const messages: MessageParam[] = [\n {\n rol",
"chunk_index": 65,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__66",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ing) {\n const messages: MessageParam[] = [\n {\n role: \"user\",\n content: query,\n },\n ];\n\n const response = await this.anthropic.messages.create({\n model: \"claude-3-5-sonnet-20241022\",\n max_tokens: 1000,\n messages,\n tools: this.tools,\n });\n\n const finalText = [];\n\n for (const content of response.conten",
"chunk_index": 66,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__67",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "Text = [];\n\n for (const content of response.content) {\n if (content.type === \"text\") {\n finalText.push(content.text);\n } else if (content.type === \"tool_use\") {\n const toolName = content.name;\n const toolArgs = content.input as { [x: string]: unknown } | undefined;\n\n const result = await this.mcp.ca",
"chunk_index": 67,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__68",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "} | undefined;\n\n const result = await this.mcp.callTool({\n name: toolName,\n arguments: toolArgs,\n });\n finalText.push(\n `[Calling tool ${toolName} with args ${JSON.stringify(toolArgs)}]`\n );\n\n messages.push({\n role: \"user\",\n content: result.content as string,\n });\n\n const response = await this.anth",
"chunk_index": 68,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__69",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "as string,\n });\n\n const response = await this.anthropic.messages.create({\n model: \"claude-3-5-sonnet-20241022\",\n max_tokens: 1000,\n messages,\n });\n\n finalText.push(\n response.content[0].type === \"text\" ? response.content[0].text : \"\"\n );\n }\n }\n\n return finalText.join(\"\\n\");\n}\n```\n\n### Interactive Ch",
"chunk_index": 69,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__70",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "rn finalText.join(\"\\n\");\n}\n```\n\n### Interactive Chat Interface\n\nNow we'll add the chat loop and cleanup functionality:\n\n```typescript theme={null}\nasync chatLoop() {\n const rl = readline.createInterface({\n input: process.stdin,\n output: process.stdout,\n });\n\n try {\n console.log(\"\\nMCP Client Started",
"chunk_index": 70,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__71",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "t,\n });\n\n try {\n console.log(\"\\nMCP Client Started!\");\n console.log(\"Type your queries or 'quit' to exit.\");\n\n while (true) {\n const message = await rl.question(\"\\nQuery: \");\n if (message.toLowerCase() === \"quit\") {\n break;\n }\n const response = await this.processQuery(message);\n console.log(\"\\n\" + r",
"chunk_index": 71,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__72",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "this.processQuery(message);\n console.log(\"\\n\" + response);\n }\n } finally {\n rl.close();\n }\n}\n\nasync cleanup() {\n await this.mcp.close();\n}\n```\n\n### Main Entry Point\n\nFinally, we'll add the main execution logic:\n\n```typescript theme={null}\nasync function main() {\n if (process.argv.length < 3) {\n con",
"chunk_index": 72,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__73",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "tion main() {\n if (process.argv.length < 3) {\n console.log(\"Usage: node index.ts \");\n return;\n }\n const mcpClient = new MCPClient();\n try {\n await mcpClient.connectToServer(process.argv[2]);\n await mcpClient.chatLoop();\n } finally {\n await mcpClient.cleanup();\n process.exit(0)",
"chunk_index": 73,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__74",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "lly {\n await mcpClient.cleanup();\n process.exit(0);\n }\n}\n\nmain();\n```\n\n## Running the Client\n\nTo run your client with any MCP server:\n\n```bash theme={null}\n# Build TypeScript\nnpm run build\n\n# Run the client\nnode build/index.js path/to/server.py # python server\nnode build/index.js path/to/build/index",
"chunk_index": 74,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__75",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "hon server\nnode build/index.js path/to/build/index.js # node server\n```\n\n\n If you're continuing [the weather tutorial from the server quickstart](https://github.com/modelcontextprotocol/quickstart-resources/tree/main/weather-server-typescript), your command might look something like this: `nod",
"chunk_index": 75,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__76",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "your command might look something like this: `node build/index.js .../quickstart-resources/weather-server-typescript/build/index.js`\n\n\n**The client will:**\n\n1. Connect to the specified server\n2. List available tools\n3. Start an interactive chat session where you can:\n * Enter queries\n * See",
"chunk_index": 76,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__77",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "at session where you can:\n * Enter queries\n * See tool executions\n * Get responses from Claude\n\n## How It Works\n\nWhen you submit a query:\n\n1. The client gets the list of available tools from the server\n2. Your query is sent to Claude along with tool descriptions\n3. Claude decides which tools (if any",
"chunk_index": 77,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__78",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "descriptions\n3. Claude decides which tools (if any) to use\n4. The client executes any requested tool calls through the server\n5. Results are sent back to Claude\n6. Claude provides a natural language response\n7. The response is displayed to you\n\n## Best practices\n\n1. **Error Handling**\n * Use TypeScr",
"chunk_index": 78,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__79",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "st practices\n\n1. **Error Handling**\n * Use TypeScript's type system for better error detection\n * Wrap tool calls in try-catch blocks\n * Provide meaningful error messages\n * Gracefully handle connection issues\n\n2. **Security**\n * Store API keys securely in `.env`\n * Validate server responses\n * Be c",
"chunk_index": 79,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__80",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ely in `.env`\n * Validate server responses\n * Be cautious with tool permissions\n\n## Troubleshooting\n\n### Server Path Issues\n\n* Double-check the path to your server script is correct\n* Use the absolute path if the relative path isn't working\n* For Windows users, make sure to use forward slashes (/) o",
"chunk_index": 80,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__81",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "dows users, make sure to use forward slashes (/) or escaped backslashes (\\\\) in the path\n* Verify the server file has the correct extension (.js for Node.js or .py for Python)\n\nExample of correct path usage:\n\n```bash theme={null}\n# Relative path\nnode build/index.js ./server/build/index.js\n\n# Absolut",
"chunk_index": 81,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__82",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "build/index.js ./server/build/index.js\n\n# Absolute path\nnode build/index.js /Users/username/projects/mcp-server/build/index.js\n\n# Windows path (either format works)\nnode build/index.js C:/projects/mcp-server/build/index.js\nnode build/index.js C:\\\\projects\\\\mcp-server\\\\build\\\\index.js\n```\n\n### Respo",
"chunk_index": 82,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__83",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ojects\\\\mcp-server\\\\build\\\\index.js\n```\n\n### Response Timing\n\n* The first response might take up to 30 seconds to return\n* This is normal and happens while:\n * The server initializes\n * Claude processes the query\n * Tools are being executed\n* Subsequent responses are typically faster\n* Don't interru",
"chunk_index": 83,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__84",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ent responses are typically faster\n* Don't interrupt the process during this initial waiting period\n\n### Common Error Messages\n\nIf you see:\n\n* `Error: Cannot find module`: Check your build folder and ensure TypeScript compilation succeeded\n* `Connection refused`: Ensure the server is running and the",
"chunk_index": 84,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__85",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ion refused`: Ensure the server is running and the path is correct\n* `Tool execution failed`: Verify the tool's required environment variables are set\n* `ANTHROPIC_API_KEY is not set`: Check your .env file and environment variables\n* `TypeError`: Ensure you're using the correct types for tool argume",
"chunk_index": 85,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__86",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ure you're using the correct types for tool arguments\n\n This is a quickstart demo based on Spring AI MCP auto-configuration and boot starters.\n To learn how to create sync and async MCP Clients manually, consult the Java SDK Client documentation\n \nThis example demonstrates how to build an interactiv",
"chunk_index": 86,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__87",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "is 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-archived/tree/main/src/brave-search). The application creates a conversational interface powered by An",
"chunk_index": 87,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__88",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "n 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.\n[You can find the complete code for this tutorial here.](https://github.com/spring-projects/spring-ai-e",
"chunk_index": 88,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__89",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "e.](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/web-search/brave-chatbot)\n\n## System Requirements\n\nBefore starting, ensure your system meets these requirements:\n\n* Java 17 or higher\n* Maven 3.6+\n* npx package manager\n* Anthropic API key (Claude)\n* Brave Sea",
"chunk_index": 89,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__90",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "e manager\n* Anthropic API key (Claude)\n* Brave Search API key\n\n## Setting Up Your Environment\n\n1. Install npx (Node Package eXecute):\n First, make sure to install [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)\n and then run:\n\n ```bash theme={null}\n npm install -g npx\n ```",
"chunk_index": 90,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__91",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "```bash theme={null}\n npm install -g npx\n ```\n\n2. Clone the repository:\n\n ```bash theme={null}\n git clone https://github.com/spring-projects/spring-ai-examples.git\n cd model-context-protocol/brave-chatbot\n ```\n\n3. Set up your API keys:\n\n ```bash theme={null}\n export ANTHROPIC_API_KEY='your-anthro",
"chunk_index": 91,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__92",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "heme={null}\n export ANTHROPIC_API_KEY='your-anthropic-api-key-here'\n export BRAVE_API_KEY='your-brave-api-key-here'\n ```\n\n4. Build the application:\n\n ```bash theme={null}\n ./mvnw clean install\n ```\n\n5. Run the application using Maven:\n ```bash theme={null}\n ./mvnw spring-boot:run\n ```\n\n\n Ma",
"chunk_index": 92,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__93",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "{null}\n ./mvnw spring-boot:run\n ```\n\n\n Make sure you keep your `ANTHROPIC_API_KEY` and `BRAVE_API_KEY` keys secure!\n\n\n## How it Works\n\nThe application integrates Spring AI with the Brave Search MCP server through several components:\n\n### MCP Client Configuration\n\n1. Required depen",
"chunk_index": 93,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__94",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": ":\n\n### MCP Client Configuration\n\n1. Required dependencies in pom.xml:\n\n```xml theme={null}\n\n org.springframework.ai\n spring-ai-starter-mcp-client\n\n\n org.springframework.ai\n spring-ai-start",
"chunk_index": 94,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__95",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ramework.ai\n spring-ai-starter-model-anthropic\n\n```\n\n2. Application properties (application.yml):\n\n```yml theme={null}\nspring:\n ai:\n mcp:\n client:\n enabled: true\n name: brave-search-client\n version: 1.0.0\n type: SYNC\n request-timeout: 20s\n stdio:\n root",
"chunk_index": 95,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__96",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": ".0\n type: SYNC\n request-timeout: 20s\n stdio:\n root-change-notification: true\n servers-configuration: classpath:/mcp-servers-config.json\n toolcallback:\n enabled: true\n anthropic:\n api-key: ${ANTHROPIC_API_KEY}\n```\n\nThis activates the `spring-ai-starter-mcp-client` to create one or more `McpClient`s b",
"chunk_index": 96,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__97",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "r-mcp-client` to create one or more `McpClient`s based on the provided server configuration.\nThe `spring.ai.mcp.client.toolcallback.enabled=true` property enables the tool callback mechanism, that automatically registers all MCP tool as spring ai tools.\nIt is disabled by default.\n\n3. MCP Server Conf",
"chunk_index": 97,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__98",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ls.\nIt is disabled by default.\n\n3. MCP Server Configuration (`mcp-servers-config.json`):\n\n```json theme={null}\n{\n \"mcpServers\": {\n \"brave-search\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-brave-search\"],\n \"env\": {\n \"BRAVE_API_KEY\": \"\"\n }\n }\n }\n}\n```",
"chunk_index": 98,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__99",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "I_KEY\": \"\"\n }\n }\n }\n}\n```\n\n### Chat Implementation\n\nThe chatbot is implemented using Spring AI's ChatClient with MCP tool integration:\n\n```java theme={null}\nvar chatClient = chatClientBuilder\n .defaultSystem(\"You are useful assistant, expert in AI and Java.\")\n .defaultToolCal",
"chunk_index": 99,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__100",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "sistant, expert in AI and Java.\")\n .defaultToolCallbacks((Object[]) mcpToolAdapter.toolCallbacks())\n .defaultAdvisors(new MessageChatMemoryAdvisor(new InMemoryChatMemory()))\n .build();\n```\n\nKey features:\n\n* Uses Claude AI model for natural language understanding\n* Integrates Brave Search through MCP",
"chunk_index": 100,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__101",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "nderstanding\n* Integrates Brave Search through MCP for real-time web search capabilities\n* Maintains conversation memory using InMemoryChatMemory\n* Runs as an interactive command-line application\n\n### Build and run\n\n```bash theme={null}\n./mvnw clean install\njava -jar ./target/ai-mcp-brave-chatbot-0.",
"chunk_index": 101,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__102",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "install\njava -jar ./target/ai-mcp-brave-chatbot-0.0.1-SNAPSHOT.jar\n```\n\nor\n\n```bash theme={null}\n./mvnw spring-boot:run\n```\n\nThe 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 an",
"chunk_index": 102,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__103",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "needs to find information from the internet to answer your queries.\n\nThe chatbot can:\n\n* Answer questions using its built-in knowledge\n* Perform web searches when needed using Brave Search\n* Remember context from previous messages in the conversation\n* Combine information from multiple sources to p",
"chunk_index": 103,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__104",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "n\n* Combine information from multiple sources to provide comprehensive answers\n\n### Advanced Configuration\n\nThe MCP client supports additional configuration options:\n\n* Client customization through `McpSyncClientCustomizer` or `McpAsyncClientCustomizer`\n* Multiple clients with multiple transport typ",
"chunk_index": 104,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__105",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "er`\n* Multiple clients with multiple transport types: `STDIO` and `SSE` (Server-Sent Events)\n* Integration with Spring AI's tool execution framework\n* Automatic client initialization and lifecycle management\n\nFor WebFlux-based applications, you can use the WebFlux starter instead:\n\n```xml theme={nul",
"chunk_index": 105,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__106",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "se the WebFlux starter instead:\n\n```xml theme={null}\n\n org.springframework.ai\n spring-ai-mcp-client-webflux-spring-boot-starter\n\n```\n\nThis provides similar functionality but uses a WebFlux-based SSE transport implementation, recomm",
"chunk_index": 106,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__107",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "WebFlux-based SSE transport implementation, recommended for production deployments.\n\nYou can find the complete code for this tutorial here.\n## System Requirements\n\nBefore starting, ensure your system meets these requirements:\n\n* Java 17 or higher\n* Anthropic API key (Claude)\n\n## Setting up your envi",
"chunk_index": 107,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__108",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "nthropic API key (Claude)\n\n## Setting up your environment\n\nFirst, let's install `java` and `gradle` if you haven't already.\nYou can download `java` from [official Oracle JDK website](https://www.oracle.com/java/technologies/downloads/).\nVerify your `java` installation:\n\n```bash theme={null}\njava --v",
"chunk_index": 108,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__109",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "java` installation:\n\n```bash theme={null}\njava --version\n```\n\nNow, let's create and set up your project:\n\n\n ```bash macOS/Linux theme={null}\n # Create a new directory for our project\n mkdir kotlin-mcp-client\n cd kotlin-mcp-client\n\n # Initialize a new kotlin project\n gradle init\n ```\n\n ```",
"chunk_index": 109,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__110",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "alize a new kotlin project\n gradle init\n ```\n\n ```powershell Windows theme={null}\n # Create a new directory for our project\n md kotlin-mcp-client\n cd kotlin-mcp-client\n # Initialize a new kotlin project\n gradle init\n ```\n\n\nAfter running `gradle init`, you will be presented with options f",
"chunk_index": 110,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__111",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "gradle init`, you will be presented with options for creating your project.\nSelect **Application** as the project type, **Kotlin** as the programming language, and **Java 17** as the Java version.\n\nAlternatively, you can create a Kotlin application using the [IntelliJ IDEA project wizard](https://ko",
"chunk_index": 111,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__112",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "sing the [IntelliJ IDEA project wizard](https://kotlinlang.org/docs/jvm-get-started.html).\n\nAfter creating the project, add the following dependencies:\n\n\n ```kotlin build.gradle.kts theme={null}\n val mcpVersion = \"0.4.0\"\n val slf4jVersion = \"2.0.9\"\n val anthropicVersion = \"0.8.0\"\n\n depend",
"chunk_index": 112,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__113",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "= \"2.0.9\"\n val anthropicVersion = \"0.8.0\"\n\n dependencies {\n implementation(\"io.modelcontextprotocol:kotlin-sdk:$mcpVersion\")\n implementation(\"org.slf4j:slf4j-nop:$slf4jVersion\")\n implementation(\"com.anthropic:anthropic-java:$anthropicVersion\")\n }\n ```\n\n ```groovy build.gradle theme={null}\n def mcpVe",
"chunk_index": 113,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__114",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "`\n\n ```groovy build.gradle theme={null}\n def mcpVersion = '0.3.0'\n def slf4jVersion = '2.0.9'\n def anthropicVersion = '0.8.0'\n dependencies {\n implementation \"io.modelcontextprotocol:kotlin-sdk:$mcpVersion\"\n implementation \"org.slf4j:slf4j-nop:$slf4jVersion\"\n implementation \"com.anthropic:anthropic-",
"chunk_index": 114,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__115",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "Version\"\n implementation \"com.anthropic:anthropic-java:$anthropicVersion\"\n }\n ```\n\n\nAlso, add the following plugins to your build script:\n\n\n ```kotlin build.gradle.kts theme={null}\n plugins {\n id(\"com.github.johnrengelman.shadow\") version \"8.1.1\"\n }\n ```\n\n ```groovy build.grad",
"chunk_index": 115,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__116",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "w\") version \"8.1.1\"\n }\n ```\n\n ```groovy build.gradle theme={null}\n plugins {\n id 'com.github.johnrengelman.shadow' version '8.1.1'\n }\n ```\n\n\n## Setting up your API key\n\nYou'll need an Anthropic API key from the [Anthropic Console](https://console.anthropic.com/settings/keys).\n\nSet up you",
"chunk_index": 116,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__117",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "/console.anthropic.com/settings/keys).\n\nSet up your API key:\n\n```bash theme={null}\nexport ANTHROPIC_API_KEY='your-anthropic-api-key-here'\n```\n\n\n Make sure your keep your `ANTHROPIC_API_KEY` secure!\n\n\n## Creating the Client\n\n### Basic Client Structure\n\nFirst, let's create the basic",
"chunk_index": 117,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__118",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ic Client Structure\n\nFirst, let's create the basic client class:\n\n```kotlin theme={null}\nclass MCPClient : AutoCloseable {\n private val anthropic = AnthropicOkHttpClient.fromEnv()\n private val mcp: Client = Client(clientInfo = Implementation(name = \"mcp-client-cli\", version = \"1.0.0\"))\n private late",
"chunk_index": 118,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__119",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "mcp-client-cli\", version = \"1.0.0\"))\n private lateinit var tools: List\n\n // methods will go here\n\n override fun close() {\n runBlocking {\n mcp.close()\n anthropic.close()\n }\n }\n```\n\n### Server connection management\n\nNext, we'll implement the method to connect to an MCP server:\n\n```kotlin th",
"chunk_index": 119,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__120",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "method to connect to an MCP server:\n\n```kotlin theme={null}\nsuspend fun connectToServer(serverScriptPath: String) {\n try {\n val command = buildList {\n when (serverScriptPath.substringAfterLast(\".\")) {\n \"js\" -> add(\"node\")\n \"py\" -> add(if (System.getProperty(\"os.name\").lowercase().contains(\"win\")) \"",
"chunk_index": 120,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__121",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "Property(\"os.name\").lowercase().contains(\"win\")) \"python\" else \"python3\")\n \"jar\" -> addAll(listOf(\"java\", \"-jar\"))\n else -> throw IllegalArgumentException(\"Server script must be a .js, .py or .jar file\")\n }\n add(serverScriptPath)\n }\n\n val process = ProcessBuilder(command).start()\n val transport = St",
"chunk_index": 121,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__122",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "rocessBuilder(command).start()\n val transport = StdioClientTransport(\n input = process.inputStream.asSource().buffered(),\n output = process.outputStream.asSink().buffered()\n )\n\n mcp.connect(transport)\n\n val toolsResult = mcp.listTools()\n tools = toolsResult?.tools?.map { tool ->\n ToolUnion.ofTool(",
"chunk_index": 122,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__123",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "sResult?.tools?.map { tool ->\n ToolUnion.ofTool(\n Tool.builder()\n .name(tool.name)\n .description(tool.description ?: \"\")\n .inputSchema(\n Tool.InputSchema.builder()\n .type(JsonValue.from(tool.inputSchema.type))\n .properties(tool.inputSchema.properties.toJsonValue())\n .putAdditionalProperty(\"required\"",
"chunk_index": 123,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__124",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": ".toJsonValue())\n .putAdditionalProperty(\"required\", JsonValue.from(tool.inputSchema.required))\n .build()\n )\n .build()\n )\n } ?: emptyList()\n println(\"Connected to server with tools: ${tools.joinToString(\", \") { it.tool().get().name() }}\")\n } catch (e: Exception) {\n println(\"Failed to connect to MCP s",
"chunk_index": 124,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__125",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "Exception) {\n println(\"Failed to connect to MCP server: $e\")\n throw e\n }\n}\n```\n\nAlso create a helper function to convert from `JsonObject` to `JsonValue` for Anthropic:\n\n```kotlin theme={null}\nprivate fun JsonObject.toJsonValue(): JsonValue {\n val mapper = ObjectMapper()\n val node = mapper.readTree",
"chunk_index": 125,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__126",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "apper = ObjectMapper()\n val node = mapper.readTree(this.toString())\n return JsonValue.fromJsonNode(node)\n}\n```\n\n### Query processing logic\n\nNow let's add the core functionality for processing queries and handling tool calls:\n\n```kotlin theme={null}\nprivate val messageParamsBuilder: MessageCreatePara",
"chunk_index": 126,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__127",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "rivate val messageParamsBuilder: MessageCreateParams.Builder = MessageCreateParams.builder()\n .model(Model.CLAUDE_3_5_SONNET_20241022)\n .maxTokens(1024)\n\nsuspend fun processQuery(query: String): String {\n val messages = mutableListOf(\n MessageParam.builder()\n .role(MessageParam.Role.USER)\n .content(",
"chunk_index": 127,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__128",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "uilder()\n .role(MessageParam.Role.USER)\n .content(query)\n .build()\n )\n\n val response = anthropic.messages().create(\n messageParamsBuilder\n .messages(messages)\n .tools(tools)\n .build()\n )\n\n val finalText = mutableListOf()\n response.content().forEach { content ->\n when {\n content.isText() -> f",
"chunk_index": 128,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__129",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "orEach { content ->\n when {\n content.isText() -> finalText.add(content.text().getOrNull()?.text() ?: \"\")\n\n content.isToolUse() -> {\n val toolName = content.toolUse().get().name()\n val toolArgs =\n content.toolUse().get()._input().convert(object : TypeReference>() {})\n\n val resu",
"chunk_index": 129,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__130",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "Reference>() {})\n\n val result = mcp.callTool(\n name = toolName,\n arguments = toolArgs ?: emptyMap()\n )\n finalText.add(\"[Calling tool $toolName with args $toolArgs]\")\n\n messages.add(\n MessageParam.builder()\n .role(MessageParam.Role.USER)\n .content(\n \"\"\"\n \"type\": \"tool_result\",",
"chunk_index": 130,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__131",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ole.USER)\n .content(\n \"\"\"\n \"type\": \"tool_result\",\n \"tool_name\": $toolName,\n \"result\": ${result?.content?.joinToString(\"\\n\") { (it as TextContent).text ?: \"\" }}\n \"\"\".trimIndent()\n )\n .build()\n )\n\n val aiResponse = anthropic.messages().create(\n messageParamsBuilder\n .messages(messages)\n .build()\n )",
"chunk_index": 131,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__132",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ParamsBuilder\n .messages(messages)\n .build()\n )\n\n finalText.add(aiResponse.content().first().text().getOrNull()?.text() ?: \"\")\n }\n }\n }\n\n return finalText.joinToString(\"\\n\", prefix = \"\", postfix = \"\")\n}\n```\n\n### Interactive chat\n\nWe'll add the chat loop:\n\n```kotlin theme={null}\nsuspend fun chatLoop(",
"chunk_index": 132,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__133",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "oop:\n\n```kotlin theme={null}\nsuspend fun chatLoop() {\n println(\"\\nMCP Client Started!\")\n println(\"Type your queries or 'quit' to exit.\")\n\n while (true) {\n print(\"\\nQuery: \")\n val message = readLine() ?: break\n if (message.lowercase() == \"quit\") break\n val response = processQuery(message)\n println(\"\\",
"chunk_index": 133,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__134",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "val response = processQuery(message)\n println(\"\\n$response\")\n }\n}\n```\n\n### Main entry point\n\nFinally, we'll add the main execution function:\n\n```kotlin theme={null}\nfun main(args: Array) = runBlocking {\n if (args.isEmpty()) throw IllegalArgumentException(\"Usage: java -jar /build",
"chunk_index": 134,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__135",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "umentException(\"Usage: java -jar /build/libs/kotlin-mcp-client-0.1.0-all.jar \")\n val serverPath = args.first()\n val client = MCPClient()\n client.use {\n client.connectToServer(serverPath)\n client.chatLoop()\n }\n}\n```\n\n## Running the client\n\nTo run your client with any",
"chunk_index": 135,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__136",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "## Running the client\n\nTo run your client with any MCP server:\n\n```bash theme={null}\n./gradlew build\n\n# Run the client\njava -jar build/libs/.jar path/to/server.jar # jvm server\njava -jar build/libs/.jar path/to/server.py # python server\njava -jar build/libs/.jar path/to/build/index.js # node server\n```\n\n\n 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-std",
"chunk_index": 137,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__138",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "n-mcp-client-0.1.0-all.jar .../samples/weather-stdio-server/build/libs/weather-stdio-server-0.1.0-all.jar`\n\n\n**The client will:**\n\n1. Connect to the specified server\n2. List available tools\n3. Start an interactive chat session where you can:\n * Enter queries\n * See tool executions\n * Get resp",
"chunk_index": 138,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__139",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "* Enter queries\n * See tool executions\n * Get responses from Claude\n\n## How it works\n\nHere's a high-level workflow schema:\n\n```mermaid theme={null}\n---\nconfig:\n theme: neutral\n---\nsequenceDiagram\n actor User\n participant Client\n participant Claude\n participant MCP_Server as MCP Server\n participant T",
"chunk_index": 139,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__140",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "articipant MCP_Server as MCP Server\n participant Tools\n\n User->>Client: Send query\n Client<<->>MCP_Server: Get available tools\n Client->>Claude: Send query with tool descriptions\n Claude-->>Client: Decide tool execution\n Client->>MCP_Server: Request tool execution\n MCP_Server->>Tools: Execute chosen",
"chunk_index": 140,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__141",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "tool execution\n MCP_Server->>Tools: Execute chosen tools\n Tools-->>MCP_Server: Return results\n MCP_Server-->>Client: Send results\n Client->>Claude: Send tool results\n Claude-->>Client: Provide final response\n Client-->>User: Display response\n```\n\nWhen you submit a query:\n\n1. The client gets the list",
"chunk_index": 141,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__142",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "n you submit a query:\n\n1. The client gets the list of available tools from the server\n2. Your query is sent to Claude along with tool descriptions\n3. Claude decides which tools (if any) to use\n4. The client executes any requested tool calls through the server\n5. Results are sent back to Claude\n6. Cl",
"chunk_index": 142,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__143",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "he server\n5. Results are sent back to Claude\n6. Claude provides a natural language response\n7. The response is displayed to you\n\n## Best practices\n\n1. **Error Handling**\n * Leverage Kotlin's type system to model errors explicitly\n * Wrap external tool and API calls in `try-catch` blocks when excepti",
"chunk_index": 143,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__144",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "l and API calls in `try-catch` blocks when exceptions are possible\n * Provide clear and meaningful error messages\n * Handle network timeouts and connection issues gracefully\n\n2. **Security**\n * Store API keys and secrets securely in `local.properties`, environment variables, or secret managers\n * Va",
"chunk_index": 144,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__145",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "`, environment variables, or secret managers\n * Validate all external responses to avoid unexpected or unsafe data usage\n * Be cautious with permissions and trust boundaries when using tools\n\n## Troubleshooting\n\n### Server Path Issues\n\n* Double-check the path to your server script is correct\n* Use t",
"chunk_index": 145,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__146",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "the path to your server script is correct\n* Use the absolute path if the relative path isn't working\n* For Windows users, make sure to use forward slashes (/) or escaped backslashes (\\\\) in the path\n* Make sure that the required runtime is installed (java for Java, npm for Node.js, or uv for Python",
"chunk_index": 146,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__147",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "(java for Java, npm for Node.js, or uv for Python)\n* Verify the server file has the correct extension (.jar for Java, .js for Node.js or .py for Python)\n\nExample of correct path usage:\n\n```bash theme={null}\n# Relative path\njava -jar build/libs/client.jar ./server/build/libs/server.jar\n\n# Absolute p",
"chunk_index": 147,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__148",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "t.jar ./server/build/libs/server.jar\n\n# Absolute path\njava -jar build/libs/client.jar /Users/username/projects/mcp-server/build/libs/server.jar\n\n# Windows path (either format works)\njava -jar build/libs/client.jar C:/projects/mcp-server/build/libs/server.jar\njava -jar build/libs/client.jar C:\\\\proje",
"chunk_index": 148,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__149",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "rver.jar\njava -jar build/libs/client.jar C:\\\\projects\\\\mcp-server\\\\build\\\\libs\\\\server.jar\n```\n\n### Response Timing\n\n* The first response might take up to 30 seconds to return\n* This is normal and happens while:\n * The server initializes\n * Claude processes the query\n * Tools are being executed\n* Su",
"chunk_index": 149,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__150",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ocesses the query\n * Tools are being executed\n* Subsequent responses are typically faster\n* Don't interrupt the process during this initial waiting period\n\n### Common Error Messages\n\nIf you see:\n\n* `Connection refused`: Ensure the server is running and the path is correct\n* `Tool execution failed`:",
"chunk_index": 150,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__151",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "nd the path is correct\n* `Tool execution failed`: Verify the tool's required environment variables are set\n* `ANTHROPIC_API_KEY is not set`: Check your environment variables\n\nYou can find the complete code for this tutorial here.\n## System Requirements\n\nBefore starting, ensure your system meets thes",
"chunk_index": 151,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__152",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ts\n\nBefore starting, ensure your system meets these requirements:\n\n* .NET 8.0 or higher\n* Anthropic API key (Claude)\n* Windows, Linux, or macOS\n\n## Setting up your environment\n\nFirst, create a new .NET project:\n\n```bash theme={null}\ndotnet new console -n QuickstartClient\ncd QuickstartClient\n```\n\nThe",
"chunk_index": 152,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__153",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "e -n QuickstartClient\ncd QuickstartClient\n```\n\nThen, add the required dependencies to your project:\n\n```bash theme={null}\ndotnet add package ModelContextProtocol --prerelease\ndotnet add package Anthropic.SDK\ndotnet add package Microsoft.Extensions.Hosting\ndotnet add package Microsoft.Extensions.AI\n`",
"chunk_index": 153,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__154",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "sting\ndotnet add package Microsoft.Extensions.AI\n```\n\n## Setting up your API key\n\nYou'll need an Anthropic API key from the [Anthropic Console](https://console.anthropic.com/settings/keys).\n\n```bash theme={null}\ndotnet user-secrets init\ndotnet user-secrets set \"ANTHROPIC_API_KEY\" \"\"\n`",
"chunk_index": 154,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__155",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ecrets set \"ANTHROPIC_API_KEY\" \"\"\n```\n\n## Creating the Client\n\n### Basic Client Structure\n\nFirst, let's setup the basic client class in the file `Program.cs`:\n\n```csharp theme={null}\nusing Anthropic.SDK;\nusing Microsoft.Extensions.AI;\nusing Microsoft.Extensions.Configuration;\nusing Mi",
"chunk_index": 155,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__156",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "using Microsoft.Extensions.Configuration;\nusing Microsoft.Extensions.Hosting;\nusing ModelContextProtocol.Client;\nusing ModelContextProtocol.Protocol.Transport;\n\nvar builder = Host.CreateApplicationBuilder(args);\n\nbuilder.Configuration\n .AddEnvironmentVariables()\n .AddUserSecrets();\n```\n\nThi",
"chunk_index": 156,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__157",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "tVariables()\n .AddUserSecrets();\n```\n\nThis creates the beginnings of a .NET console application that can read the API key from user secrets.\n\nNext, we'll setup the MCP Client:\n\n```csharp theme={null}\nvar (command, arguments) = GetCommandAndArguments(args);\n\nvar clientTransport = new StdioCl",
"chunk_index": 157,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__158",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "rguments(args);\n\nvar clientTransport = new StdioClientTransport(new()\n{\n Name = \"Demo Server\",\n Command = command,\n Arguments = arguments,\n});\n\nawait using var mcpClient = await McpClientFactory.CreateAsync(clientTransport);\n\nvar tools = await mcpClient.ListToolsAsync();\nforeach (var tool in tools)",
"chunk_index": 158,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__159",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ent.ListToolsAsync();\nforeach (var tool in tools)\n{\n Console.WriteLine($\"Connected to server with tools: {tool.Name}\");\n}\n```\n\nAdd this function at the end of the `Program.cs` file:\n\n```csharp theme={null}\nstatic (string command, string[] arguments) GetCommandAndArguments(string[] args)\n{\n return ar",
"chunk_index": 159,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__160",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "GetCommandAndArguments(string[] args)\n{\n return args switch\n {\n [var script] when script.EndsWith(\".py\") => (\"python\", args),\n [var script] when script.EndsWith(\".js\") => (\"node\", args),\n [var script] when Directory.Exists(script) || (File.Exists(script) && script.EndsWith(\".csproj\")) => (\"dotnet\",",
"chunk_index": 160,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__161",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ipt) && script.EndsWith(\".csproj\")) => (\"dotnet\", [\"run\", \"--project\", script, \"--no-build\"]),\n _ => throw new NotSupportedException(\"An unsupported server script was provided. Supported scripts are .py, .js, or .csproj\")\n };\n}\n```\n\nThis creates an MCP client that will connect to a server that is pr",
"chunk_index": 161,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__162",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "CP 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.\n\n### Query processing logic\n\nNow let's add the core functionality for processing queries and handling tool calls:\n\n```csharp theme={null}\nusing var anthro",
"chunk_index": 162,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__163",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ol calls:\n\n```csharp theme={null}\nusing var anthropicClient = new AnthropicClient(new APIAuthentication(builder.Configuration[\"ANTHROPIC_API_KEY\"]))\n .Messages\n .AsBuilder()\n .UseFunctionInvocation()\n .Build();\n\nvar options = new ChatOptions\n{\n MaxOutputTokens = 1000,\n ModelId = \"claude-3-5-sonnet-2",
"chunk_index": 163,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__164",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "tputTokens = 1000,\n ModelId = \"claude-3-5-sonnet-20241022\",\n Tools = [.. tools]\n};\n\nConsole.ForegroundColor = ConsoleColor.Green;\nConsole.WriteLine(\"MCP Client Started!\");\nConsole.ResetColor();\n\nPromptForInput();\nwhile(Console.ReadLine() is string query && !\"exit\".Equals(query, StringComparison.Ordi",
"chunk_index": 164,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__165",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ery && !\"exit\".Equals(query, StringComparison.OrdinalIgnoreCase))\n{\n if (string.IsNullOrWhiteSpace(query))\n {\n PromptForInput();\n continue;\n }\n\n await foreach (var message in anthropicClient.GetStreamingResponseAsync(query, options))\n {\n Console.Write(message);\n }\n Console.WriteLine();\n\n PromptForIn",
"chunk_index": 165,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__166",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "e(message);\n }\n Console.WriteLine();\n\n PromptForInput();\n}\n\nstatic void PromptForInput()\n{\n Console.WriteLine(\"Enter a command (or 'exit' to quit):\");\n Console.ForegroundColor = ConsoleColor.Cyan;\n Console.Write(\"> \");\n Console.ResetColor();\n}\n```\n\n## Key Components Explained\n\n### 1. Client Initiali",
"chunk_index": 166,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__167",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "# Key Components Explained\n\n### 1. Client Initialization\n\n* The client is initialized using `McpClientFactory.CreateAsync()`, which sets up the transport type and command to run the server.\n\n### 2. Server Connection\n\n* Supports Python, Node.js, and .NET servers.\n* The server is started using the com",
"chunk_index": 167,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__168",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "NET servers.\n* The server is started using the command specified in the arguments.\n* Configures to use stdio for communication with the server.\n* Initializes the session and available tools.\n\n### 3. Query Processing\n\n* Leverages [Microsoft.Extensions.AI](https://learn.microsoft.com/dotnet/ai/ai-exte",
"chunk_index": 168,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__169",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": ".AI](https://learn.microsoft.com/dotnet/ai/ai-extensions) for the chat client.\n* Configures the `IChatClient` to use automatic tool (function) invocation.\n* The client reads user input and sends it to the server.\n* The server processes the query and returns a response.\n* The response is displayed to",
"chunk_index": 169,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__170",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "returns a response.\n* The response is displayed to the user.\n\n## Running the Client\n\nTo run your client with any MCP server:\n\n```bash theme={null}\ndotnet run -- path/to/server.csproj # dotnet server\ndotnet run -- path/to/server.py # python server\ndotnet run -- path/to/server.js # node server\n```\n\n\n If you're continuing the weather tutorial from the server quickstart, your command might look something like this: `dotnet run -- path/to/QuickstartWeatherServer`.\n\n\nThe client will:\n\n1. Connect to the specified server\n2. List available",
"chunk_index": 171,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__172",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "Connect to the specified server\n2. List available tools\n3. Start an interactive chat session where you can:\n * Enter queries\n * See tool executions\n * Get responses from Claude\n4. Exit the session when done\n\nHere's an example of what it should look like it connected to a weather server quickstart:",
"chunk_index": 172,
"total_chunks": 179
},
{
"chunk_id": "md_build-client_2e39af9f__173",
"doc_id": "md_build-client_2e39af9f",
"title": "Build an MCP client",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-client.md",
"filename": "build-client.md",
"file_path": "build-client.md",
"updated_at": "1760788520.8554032",
"text": "ike it connected to a weather server quickstart:\n\n\n ![](\"https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-dotnet-client.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=fcf28dde150d6db879402ad8150c6b23\")
\n\n\nNext steps\n\n Check out our gallery of official MCP servers and implementations\n \n\n View the list of clients that support MCP integrations",
"chunk_index": 178,
"total_chunks": 179
},
{
"chunk_id": "md_build-server_b4682181__0",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "Build an MCP server\n\nGet started building your own server to use in Claude for Desktop and other clients.\n\nIn this tutorial, we'll build a simple MCP weather server and connect it to a host, Claude for Desktop.\nWhat we'll be building\nWe'll build a server that exposes two tools: get_alerts and get_fo",
"chunk_index": 0,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__1",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "rver 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):\n\n 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 as well as a list o",
"chunk_index": 1,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__2",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "es on building your own client as well as a list of other clients here.\n\nCore MCP Concepts\nMCP servers can provide three main types of capabilities:\n\nResources: File-like data that can be read by clients (like API responses or file contents)\nTools: Functions that can be called by the LLM (with user",
"chunk_index": 2,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__3",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "unctions that can be called by the LLM (with user approval)\nPrompts: Pre-written templates that help users accomplish specific tasks\n\nThis tutorial will primarily focus on tools.\n\n Let's get started with building our weather server! You can find the complete code for what we'll be building here.\n###",
"chunk_index": 3,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__4",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "complete code for what we'll be building here.\n### Prerequisite knowledge\n\nThis quickstart assumes you have familiarity with:\n\n* Python\n* LLMs like Claude\n\n### Logging in MCP Servers\n\nWhen implementing MCP servers, be careful about how you handle logging:\n\n**For STDIO-based servers:** Never write to",
"chunk_index": 4,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__5",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ging:\n\n**For STDIO-based servers:** Never write to standard output (stdout). This includes:\n\n* `print()` statements in Python\n* `console.log()` in JavaScript\n* `fmt.Println()` in Go\n* Similar stdout functions in other languages\n\nWriting to stdout will corrupt the JSON-RPC messages and break your ser",
"chunk_index": 5,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__6",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "l corrupt the JSON-RPC messages and break your server.\n\n**For HTTP-based servers:** Standard output logging is fine since it doesn't interfere with HTTP responses.\n\n### Best Practices\n\n1. Use a logging library that writes to stderr or files.\n2. Tool names should follow the format specified [here](/s",
"chunk_index": 6,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__7",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "names should follow the format specified [here](/specification/draft/server/tools#tool-names).\n\n### Quick Examples\n\n```python theme={null}\n# ❌ Bad (STDIO)\nprint(\"Processing request\")\n\n# ✅ Good (STDIO)\nimport logging\nlogging.info(\"Processing request\")\n```\n\n### System requirements\n\n* Python 3.10 or hi",
"chunk_index": 7,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__8",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "```\n\n### System requirements\n\n* Python 3.10 or higher installed.\n* You must use the Python MCP SDK 1.2.0 or higher.\n\n### Set up your environment\n\nFirst, let's install `uv` and set up our Python project and environment:\n\n\n ```bash macOS/Linux theme={null}\n curl -LsSf https://astral.sh/uv/",
"chunk_index": 8,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__9",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "nux theme={null}\n curl -LsSf https://astral.sh/uv/install.sh | sh\n ```\n\n ```powershell Windows theme={null}\n powershell -ExecutionPolicy ByPass -c \"irm https://astral.sh/uv/install.ps1 | iex\"\n ```\n\n\nMake sure to restart your terminal afterwards to ensure that the `uv` command gets picked",
"chunk_index": 9,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__10",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "rwards to ensure that the `uv` command gets picked up.\n\nNow, let's create and set up our project:\n\n\n ```bash macOS/Linux theme={null}\n # Create a new directory for our project\n uv init weather\n cd weather\n\n # Create virtual environment and activate it\n uv venv\n source .venv/bin/activate",
"chunk_index": 10,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__11",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "activate it\n uv venv\n source .venv/bin/activate\n\n # Install dependencies\n uv add \"mcp[cli]\" httpx\n\n # Create our server file\n touch weather.py\n ```\n\n ```powershell Windows theme={null}\n # Create a new directory for our project\n uv init weather\n cd weather\n\n # Create virtual environment and activate",
"chunk_index": 11,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__12",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "eather\n\n # Create virtual environment and activate it\n uv venv\n .venv\\Scripts\\activate\n\n # Install dependencies\n uv add mcp[cli] httpx\n\n # Create our server file\n new-item weather.py\n ```\n\n\nNow let's dive into building your server.\n\n## Building your server\n\n### Importing packages and set",
"chunk_index": 12,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__13",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ilding your server\n\n### Importing packages and setting up the instance\n\nAdd these to the top of your `weather.py`:\n\n```python theme={null}\nfrom typing import Any\nimport httpx\nfrom mcp.server.fastmcp import FastMCP\n\n# Initialize FastMCP server\nmcp = FastMCP(\"weather\")\n\n# Constants\nNWS_API_BASE = \"htt",
"chunk_index": 13,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__14",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "astMCP(\"weather\")\n\n# Constants\nNWS_API_BASE = \"https://api.weather.gov\"\nUSER_AGENT = \"weather-app/1.0\"\n```\n\nThe FastMCP class uses Python type hints and docstrings to automatically generate tool definitions, making it easy to create and maintain MCP tools.\n\n### Helper functions\n\nNext, let's add our",
"chunk_index": 14,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__15",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "tools.\n\n### Helper functions\n\nNext, let's add our helper functions for querying and formatting the data from the National Weather Service API:\n\n```python theme={null}\nasync def make_nws_request(url: str) -> dict[str, Any] | None:\n \"\"\"Make a request to the NWS API with proper error handling.\"\"\"\n head",
"chunk_index": 15,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__16",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "o the NWS API with proper error handling.\"\"\"\n headers = {\n \"User-Agent\": USER_AGENT,\n \"Accept\": \"application/geo+json\"\n }\n async with httpx.AsyncClient() as client:\n try:\n response = await client.get(url, headers=headers, timeout=30.0)\n response.raise_for_status()\n return response.json()\n except Exc",
"chunk_index": 16,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__17",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "e_for_status()\n return response.json()\n except Exception:\n return None\n\ndef format_alert(feature: dict) -> str:\n \"\"\"Format an alert feature into a readable string.\"\"\"\n props = feature[\"properties\"]\n return f\"\"\"\nEvent: {props.get('event', 'Unknown')}\nArea: {props.get('areaDesc', 'Unknown')}\nSeverity:",
"chunk_index": 17,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__18",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "Area: {props.get('areaDesc', 'Unknown')}\nSeverity: {props.get('severity', 'Unknown')}\nDescription: {props.get('description', 'No description available')}\nInstructions: {props.get('instruction', 'No specific instructions provided')}\n\"\"\"\n```\n\n### Implementing tool execution\n\nThe tool execution handler",
"chunk_index": 18,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__19",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "menting tool execution\n\nThe tool execution handler is responsible for actually executing the logic of each tool. Let's add it:\n\n```python theme={null}\n@mcp.tool()\nasync def get_alerts(state: str) -> str:\n \"\"\"Get weather alerts for a US state.\n\n Args:\n state: Two-letter US state code (e.g. CA, NY)\n \"",
"chunk_index": 19,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__20",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "state: Two-letter US state code (e.g. CA, NY)\n \"\"\"\n url = f\"{NWS_API_BASE}/alerts/active/area/{state}\"\n data = await make_nws_request(url)\n\n if not data or \"features\" not in data:\n return \"Unable to fetch alerts or no alerts found.\"\n\n if not data[\"features\"]:\n return \"No active alerts for this sta",
"chunk_index": 20,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__21",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "features\"]:\n return \"No active alerts for this state.\"\n\n alerts = [format_alert(feature) for feature in data[\"features\"]]\n return \"\\n---\\n\".join(alerts)\n\n@mcp.tool()\nasync def get_forecast(latitude: float, longitude: float) -> str:\n \"\"\"Get weather forecast for a location.\n\n Args:\n latitude: Latitude",
"chunk_index": 21,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__22",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "recast for a location.\n\n Args:\n latitude: Latitude of the location\n longitude: Longitude of the location\n \"\"\"\n # First get the forecast grid endpoint\n points_url = f\"{NWS_API_BASE}/points/{latitude},{longitude}\"\n points_data = await make_nws_request(points_url)\n\n if not points_data:\n return \"Unable",
"chunk_index": 22,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__23",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "points_url)\n\n if not points_data:\n return \"Unable to fetch forecast data for this location.\"\n\n # Get the forecast URL from the points response\n forecast_url = points_data[\"properties\"][\"forecast\"]\n forecast_data = await make_nws_request(forecast_url)\n\n if not forecast_data:\n return \"Unable to fetch",
"chunk_index": 23,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__24",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "if not forecast_data:\n return \"Unable to fetch detailed forecast.\"\n\n # Format the periods into a readable forecast\n periods = forecast_data[\"properties\"][\"periods\"]\n forecasts = []\n for period in periods[:5]: # Only show next 5 periods\n forecast = f\"\"\"\n{period['name']}:\nTemperature: {period['temp",
"chunk_index": 24,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__25",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "f\"\"\"\n{period['name']}:\nTemperature: {period['temperature']}°{period['temperatureUnit']}\nWind: {period['windSpeed']} {period['windDirection']}\nForecast: {period['detailedForecast']}\n\"\"\"\n forecasts.append(forecast)\n\n return \"\\n---\\n\".join(forecasts)\n```\n\n### Running the server\n\nFinally, let's initial",
"chunk_index": 25,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__26",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "``\n\n### Running the server\n\nFinally, let's initialize and run the server:\n\n```python theme={null}\ndef main():\n # Initialize and run the server\n mcp.run(transport='stdio')\n\nif __name__ == \"__main__\":\n main()\n```\n\nYour server is complete! Run `uv run weather.py` to start the MCP server, which will lis",
"chunk_index": 26,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__27",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "eather.py` to start the MCP server, which will listen for messages from MCP hosts.\n\nLet's now test your server from an existing MCP host, Claude for Desktop.\n\n## Testing your server with Claude for Desktop\n\n\n Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Bui",
"chunk_index": 27,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__28",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "able on Linux. Linux users can proceed to the [Building a client](/docs/develop/build-client) tutorial to build an MCP client that connects to the server we just built.\n\n\nFirst, make sure you have Claude for Desktop installed. [You can install the latest version\nhere.](https://claude.ai/downl",
"chunk_index": 28,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__29",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "the latest version\nhere.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**\n\nWe'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 `~/Lib",
"chunk_index": 29,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__30",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "our 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.\n\nFor example, if you have [VS Code](https://code.visualstudio.com/) installed:\n\n\n ```bash macOS/Linux theme={nu",
"chunk_index": 30,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__31",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "alled:\n\n\n ```bash macOS/Linux theme={null}\n code ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n ```\n\n ```powershell Windows theme={null}\n code $env:AppData\\Claude\\claude_desktop_config.json\n ```\n\n\nYou'll then add your servers in the `mcpServers` key. The MCP",
"chunk_index": 31,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__32",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "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.\n\nIn this case, we'll add our single weather server like so:\n\n\n ```json macOS/Linux theme={null}\n {\n \"mcpServers\": {\n \"weather\": {\n \"command",
"chunk_index": 32,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__33",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "{null}\n {\n \"mcpServers\": {\n \"weather\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather\",\n \"run\",\n \"weather.py\"\n ]\n }\n }\n }\n ```\n\n ```json Windows theme={null}\n {\n \"mcpServers\": {\n \"weather\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"C:\\\\ABSOLUTE\\\\PATH\\",
"chunk_index": 33,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__34",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": ",\n \"args\": [\n \"--directory\",\n \"C:\\\\ABSOLUTE\\\\PATH\\\\TO\\\\PARENT\\\\FOLDER\\\\weather\",\n \"run\",\n \"weather.py\"\n ]\n }\n }\n }\n ```\n\n\n\n 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 Win",
"chunk_index": 34,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__35",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ing `which uv` on macOS/Linux or `where uv` on Windows.\n\n\n\n Make sure you pass in the absolute path to your server. You can get this by running `pwd` on macOS/Linux or `cd` on Windows Command Prompt. On Windows, remember to use double backslashes (`\\\\`) or forward slashes (`/`) in th",
"chunk_index": 35,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__36",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "backslashes (`\\\\`) or forward slashes (`/`) in the JSON path.\n\n\nThis tells Claude for Desktop:\n\n1. There's an MCP server named \"weather\"\n2. To launch it by running `uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather run weather.py`\n\nSave the file, and restart **Claude for Desktop**.\n\n Le",
"chunk_index": 36,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__37",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "the file, and restart **Claude for Desktop**.\n\n Let's get started with building our weather server! You can find the complete code for what we'll be building here.\n### Prerequisite knowledge\n\nThis quickstart assumes you have familiarity with:\n\n* TypeScript\n* LLMs like Claude\n\n### Logging in MCP Serv",
"chunk_index": 37,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__38",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "Script\n* LLMs like Claude\n\n### Logging in MCP Servers\n\nWhen implementing MCP servers, be careful about how you handle logging:\n\n**For STDIO-based servers:** Never write to standard output (stdout). This includes:\n\n* `print()` statements in Python\n* `console.log()` in JavaScript\n* `fmt.Println()` in",
"chunk_index": 38,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__39",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "console.log()` in JavaScript\n* `fmt.Println()` in Go\n* Similar stdout functions in other languages\n\nWriting to stdout will corrupt the JSON-RPC messages and break your server.\n\n**For HTTP-based servers:** Standard output logging is fine since it doesn't interfere with HTTP responses.\n\n### Best Pract",
"chunk_index": 39,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__40",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "n't interfere with HTTP responses.\n\n### Best Practices\n\n1. Use a logging library that writes to stderr or files, such as `logging` in Python.\n2. For JavaScript, be especially careful - `console.log()` writes to stdout by default\n\n### Quick Examples\n\n```javascript theme={null}\n// ❌ Bad (STDIO)\nconsol",
"chunk_index": 40,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__41",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "```javascript theme={null}\n// ❌ Bad (STDIO)\nconsole.log(\"Server started\");\n\n// ✅ Good (STDIO)\nconsole.error(\"Server started\"); // stderr is safe\n```\n\n### System requirements\n\nFor TypeScript, make sure you have the latest version of Node installed.\n\n### Set up your environment\n\nFirst, let's install N",
"chunk_index": 41,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__42",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "## Set up your environment\n\nFirst, let's install Node.js and npm if you haven't already. You can download them from [nodejs.org](https://nodejs.org/).\nVerify your Node.js installation:\n\n```bash theme={null}\nnode --version\nnpm --version\n```\n\nFor this tutorial, you'll need Node.js version 16 or higher",
"chunk_index": 42,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__43",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "tutorial, you'll need Node.js version 16 or higher.\n\nNow, let's create and set up our project:\n\n\n ```bash macOS/Linux theme={null}\n # Create a new directory for our project\n mkdir weather\n cd weather\n\n # Initialize a new npm project\n npm init -y\n\n # Install dependencies\n npm install @mode",
"chunk_index": 43,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__44",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "nit -y\n\n # Install dependencies\n npm install @modelcontextprotocol/sdk zod@3\n npm install -D @types/node typescript\n\n # Create our files\n mkdir src\n touch src/index.ts\n ```\n\n ```powershell Windows theme={null}\n # Create a new directory for our project\n md weather\n cd weather\n\n # Initialize a new npm",
"chunk_index": 44,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__45",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "t\n md weather\n cd weather\n\n # Initialize a new npm project\n npm init -y\n\n # Install dependencies\n npm install @modelcontextprotocol/sdk zod@3\n npm install -D @types/node typescript\n\n # Create our files\n md src\n new-item src\\index.ts\n ```\n\n\nUpdate your package.json to add type: \"module\" a",
"chunk_index": 45,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__46",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "Update your package.json to add type: \"module\" and a build script:\n\n```json package.json theme={null}\n{\n \"type\": \"module\",\n \"bin\": {\n \"weather\": \"./build/index.js\"\n },\n \"scripts\": {\n \"build\": \"tsc && chmod 755 build/index.js\"\n },\n \"files\": [\"build\"]\n}\n```\n\nCreate a `tsconfig.json` in the root of y",
"chunk_index": 46,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__47",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "]\n}\n```\n\nCreate a `tsconfig.json` in the root of your project:\n\n```json tsconfig.json theme={null}\n{\n \"compilerOptions\": {\n \"target\": \"ES2022\",\n \"module\": \"Node16\",\n \"moduleResolution\": \"Node16\",\n \"outDir\": \"./build\",\n \"rootDir\": \"./src\",\n \"strict\": true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": t",
"chunk_index": 47,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__48",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "true,\n \"esModuleInterop\": true,\n \"skipLibCheck\": true,\n \"forceConsistentCasingInFileNames\": true\n },\n \"include\": [\"src/**/*\"],\n \"exclude\": [\"node_modules\"]\n}\n```\n\nNow let's dive into building your server.\n\n## Building your server\n\n### Importing packages and setting up the instance\n\nAdd these to the",
"chunk_index": 48,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__49",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ges and setting up the instance\n\nAdd these to the top of your `src/index.ts`:\n\n```typescript theme={null}\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { z } from \"zod\";\n\nconst NWS_API_BAS",
"chunk_index": 49,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__50",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "o.js\";\nimport { z } from \"zod\";\n\nconst NWS_API_BASE = \"https://api.weather.gov\";\nconst USER_AGENT = \"weather-app/1.0\";\n\n// Create server instance\nconst server = new McpServer({\n name: \"weather\",\n version: \"1.0.0\",\n capabilities: {\n resources: {},\n tools: {},\n },\n});\n```\n\n### Helper functions\n\nNext,",
"chunk_index": 50,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__51",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ols: {},\n },\n});\n```\n\n### Helper functions\n\nNext, let's add our helper functions for querying and formatting the data from the National Weather Service API:\n\n```typescript theme={null}\n// Helper function for making NWS API requests\nasync function makeNWSRequest(url: string): Promise {",
"chunk_index": 51,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__52",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "eNWSRequest(url: string): Promise {\n const headers = {\n \"User-Agent\": USER_AGENT,\n Accept: \"application/geo+json\",\n };\n\n try {\n const response = await fetch(url, { headers });\n if (!response.ok) {\n throw new Error(`HTTP error! status: ${response.status}`);\n }\n return (await response.jso",
"chunk_index": 52,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__53",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "response.status}`);\n }\n return (await response.json()) as T;\n } catch (error) {\n console.error(\"Error making NWS request:\", error);\n return null;\n }\n}\n\ninterface AlertFeature {\n properties: {\n event?: string;\n areaDesc?: string;\n severity?: string;\n status?: string;\n headline?: string;\n };\n}\n\n// For",
"chunk_index": 53,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__54",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "status?: string;\n headline?: string;\n };\n}\n\n// Format alert data\nfunction formatAlert(feature: AlertFeature): string {\n const props = feature.properties;\n return [\n `Event: ${props.event || \"Unknown\"}`,\n `Area: ${props.areaDesc || \"Unknown\"}`,\n `Severity: ${props.severity || \"Unknown\"}`,\n `Status: $",
"chunk_index": 54,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__55",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "rity: ${props.severity || \"Unknown\"}`,\n `Status: ${props.status || \"Unknown\"}`,\n `Headline: ${props.headline || \"No headline\"}`,\n \"---\",\n ].join(\"\\n\");\n}\n\ninterface ForecastPeriod {\n name?: string;\n temperature?: number;\n temperatureUnit?: string;\n windSpeed?: string;\n windDirection?: string;\n short",
"chunk_index": 55,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__56",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "indSpeed?: string;\n windDirection?: string;\n shortForecast?: string;\n}\n\ninterface AlertsResponse {\n features: AlertFeature[];\n}\n\ninterface PointsResponse {\n properties: {\n forecast?: string;\n };\n}\n\ninterface ForecastResponse {\n properties: {\n periods: ForecastPeriod[];\n };\n}\n```\n\n### Implementing to",
"chunk_index": 56,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__57",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": ": ForecastPeriod[];\n };\n}\n```\n\n### Implementing tool execution\n\nThe tool execution handler is responsible for actually executing the logic of each tool. Let's add it:\n\n```typescript theme={null}\n// Register weather tools\nserver.tool(\n \"get_alerts\",\n \"Get weather alerts for a state\",\n {\n state: z.str",
"chunk_index": 57,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__58",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "\"Get weather alerts for a state\",\n {\n state: z.string().length(2).describe(\"Two-letter state code (e.g. CA, NY)\"),\n },\n async ({ state }) => {\n const stateCode = state.toUpperCase();\n const alertsUrl = `${NWS_API_BASE}/alerts?area=${stateCode}`;\n const alertsData = await makeNWSRequest(alertsUrl);\n\n if (!alertsData) {\n return {\n content: [\n {\n type: \"text\",\n text: \"Failed to retrieve alerts data\",\n },\n ],\n };\n }\n\n const features = alertsData.features || [];\n if (features.length === 0) {\n return {\n content: [\n {\n type: \"text\",\n t",
"chunk_index": 59,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__60",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "== 0) {\n return {\n content: [\n {\n type: \"text\",\n text: `No active alerts for ${stateCode}`,\n },\n ],\n };\n }\n\n const formattedAlerts = features.map(formatAlert);\n const alertsText = `Active alerts for ${stateCode}:\\n\\n${formattedAlerts.join(\"\\n\")}`;\n\n return {\n content: [\n {\n type: \"text\",\n text: aler",
"chunk_index": 60,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__61",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "return {\n content: [\n {\n type: \"text\",\n text: alertsText,\n },\n ],\n };\n },\n);\n\nserver.tool(\n \"get_forecast\",\n \"Get weather forecast for a location\",\n {\n latitude: z.number().min(-90).max(90).describe(\"Latitude of the location\"),\n longitude: z\n .number()\n .min(-180)\n .max(180)\n .describe(\"Longitude of",
"chunk_index": 61,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__62",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "()\n .min(-180)\n .max(180)\n .describe(\"Longitude of the location\"),\n },\n async ({ latitude, longitude }) => {\n // Get grid point data\n const pointsUrl = `${NWS_API_BASE}/points/${latitude.toFixed(4)},${longitude.toFixed(4)}`;\n const pointsData = await makeNWSRequest(pointsUrl);\n\n if (",
"chunk_index": 62,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__63",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "makeNWSRequest(pointsUrl);\n\n if (!pointsData) {\n return {\n content: [\n {\n type: \"text\",\n 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).`,\n },\n ],\n };\n }\n\n cons",
"chunk_index": 63,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__64",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "locations are supported).`,\n },\n ],\n };\n }\n\n const forecastUrl = pointsData.properties?.forecast;\n if (!forecastUrl) {\n return {\n content: [\n {\n type: \"text\",\n text: \"Failed to get forecast URL from grid point data\",\n },\n ],\n };\n }\n\n // Get forecast data\n const forecastData = await makeNWSRequest(forecastUrl);\n if (!forecastData) {\n return {\n content: [\n {\n type: \"text\",\n text: \"Failed to retrieve forecast data\",\n },\n ],\n };\n }\n\n const periods = forecastData.properties?.periods || [];\n if (periods.length === 0) {\n return {\n c",
"chunk_index": 65,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__66",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "s || [];\n if (periods.length === 0) {\n return {\n content: [\n {\n type: \"text\",\n text: \"No forecast periods available\",\n },\n ],\n };\n }\n\n // Format forecast periods\n const formattedForecast = periods.map((period: ForecastPeriod) =>\n [\n `${period.name || \"Unknown\"}:`,\n `Temperature: ${period.temperature",
"chunk_index": 66,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__67",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "\"Unknown\"}:`,\n `Temperature: ${period.temperature || \"Unknown\"}°${period.temperatureUnit || \"F\"}`,\n `Wind: ${period.windSpeed || \"Unknown\"} ${period.windDirection || \"\"}`,\n `${period.shortForecast || \"No forecast available\"}`,\n \"---\",\n ].join(\"\\n\"),\n );\n\n const forecastText = `Forecast for ${latitu",
"chunk_index": 67,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__68",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": ");\n\n const forecastText = `Forecast for ${latitude}, ${longitude}:\\n\\n${formattedForecast.join(\"\\n\")}`;\n\n return {\n content: [\n {\n type: \"text\",\n text: forecastText,\n },\n ],\n };\n },\n);\n```\n\n### Running the server\n\nFinally, implement the main function to run the server:\n\n```typescript theme={null}",
"chunk_index": 68,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__69",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "on to run the server:\n\n```typescript theme={null}\nasync function main() {\n const transport = new StdioServerTransport();\n await server.connect(transport);\n console.error(\"Weather MCP Server running on stdio\");\n}\n\nmain().catch((error) => {\n console.error(\"Fatal error in main():\", error);\n process.exi",
"chunk_index": 69,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__70",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ror(\"Fatal error in main():\", error);\n process.exit(1);\n});\n```\n\nMake sure to run `npm run build` to build your server! This is a very important step in getting your server to connect.\n\nLet's now test your server from an existing MCP host, Claude for Desktop.\n\n## Testing your server with Claude for",
"chunk_index": 70,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__71",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "Desktop.\n\n## Testing your server with Claude for Desktop\n\n\n Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/develop/build-client) tutorial to build an MCP client that connects to the server we just built.\n\n\nFirst, make sure you",
"chunk_index": 71,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__72",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "erver we just built.\n\n\nFirst, make sure you have Claude for Desktop installed. [You can install the latest version\nhere.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**\n\nWe'll need to configure Claude for Desktop for which",
"chunk_index": 72,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__73",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "'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.\n\nFor example, if you",
"chunk_index": 73,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__74",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "the file if it doesn't exist.\n\nFor example, if you have [VS Code](https://code.visualstudio.com/) installed:\n\n\n ```bash macOS/Linux theme={null}\n code ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n ```\n\n ```powershell Windows theme={null}\n code $env:AppData\\Claude\\claud",
"chunk_index": 74,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__75",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ndows theme={null}\n code $env:AppData\\Claude\\claude_desktop_config.json\n ```\n\n\nYou'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.\n\nIn this case, we'll add our single weather serv",
"chunk_index": 75,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__76",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": ".\n\nIn this case, we'll add our single weather server like so:\n\n\n ```json macOS/Linux theme={null}\n {\n \"mcpServers\": {\n \"weather\": {\n \"command\": \"node\",\n \"args\": [\"/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js\"]\n }\n }\n }\n ```\n\n ```json Windows theme={null}\n {\n \"mcpServers\": {\n \"we",
"chunk_index": 76,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__77",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "json Windows theme={null}\n {\n \"mcpServers\": {\n \"weather\": {\n \"command\": \"node\",\n \"args\": [\"C:\\\\PATH\\\\TO\\\\PARENT\\\\FOLDER\\\\weather\\\\build\\\\index.js\"]\n }\n }\n }\n ```\n\n\nThis tells Claude for Desktop:\n\n1. There's an MCP server named \"weather\"\n2. Launch it by running `node /ABSOLUTE/PATH/TO/PAR",
"chunk_index": 77,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__78",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": ". Launch it by running `node /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js`\n\nSave the file, and restart **Claude for Desktop**.\n\n This is a quickstart demo based on Spring AI MCP auto-configuration and boot starters.\n To learn how to create sync and async MCP Servers, manually, consult the",
"chunk_index": 78,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__79",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "sync and async MCP Servers, manually, consult the Java SDK Server documentation.\n \nLet's get started with building our weather server!\n[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/star",
"chunk_index": 79,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__80",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ples/tree/main/model-context-protocol/weather/starter-stdio-server)\n\nFor 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.\nFor manual MCP Server implementation, refer to the [MCP Server J",
"chunk_index": 80,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__81",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "Server implementation, refer to the [MCP Server Java SDK documentation](/sdk/java/mcp-server).\n\n### Logging in MCP Servers\n\nWhen implementing MCP servers, be careful about how you handle logging:\n\n**For STDIO-based servers:** Never write to standard output (stdout). This includes:\n\n* `print()` stat",
"chunk_index": 81,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__82",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "output (stdout). This includes:\n\n* `print()` statements in Python\n* `console.log()` in JavaScript\n* `fmt.Println()` in Go\n* Similar stdout functions in other languages\n\nWriting to stdout will corrupt the JSON-RPC messages and break your server.\n\n**For HTTP-based servers:** Standard output logging i",
"chunk_index": 82,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__83",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "or HTTP-based servers:** Standard output logging is fine since it doesn't interfere with HTTP responses.\n\n### Best Practices\n\n1. Use a logging library that writes to stderr or files.\n2. Ensure any configured logging library will not write to STDOUT\n\n### System requirements\n\n* Java 17 or higher insta",
"chunk_index": 83,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__84",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "### System requirements\n\n* Java 17 or higher installed.\n* [Spring Boot 3.3.x](https://docs.spring.io/spring-boot/installing.html) or higher\n\n### Set up your environment\n\nUse the [Spring Initializer](https://start.spring.io/) to bootstrap the project.\n\nYou will need to add the following dependencies:",
"chunk_index": 84,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__85",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "You will need to add the following dependencies:\n\n\n ```xml Maven theme={null}\n \n \n org.springframework.ai\n spring-ai-starter-mcp-server\n \n\n \n org.springframework\n org.springframework\n spring-web\n \n \n ```\n\n ```groovy Gradle theme={null}\n dependencies {\n implementation platform(\"org.springframework.ai:spring-ai-starter-mcp-server\")\n implementation platform(\"org.springframework:spring-web\")",
"chunk_index": 86,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__87",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "tation platform(\"org.springframework:spring-web\")\n }\n ```\n\n\nThen configure your application by setting the application properties:\n\n\n ```bash application.properties theme={null}\n spring.main.bannerMode=off\n logging.pattern.console=\n ```\n\n ```yaml application.yml theme={null}",
"chunk_index": 87,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__88",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ole=\n ```\n\n ```yaml application.yml theme={null}\n logging:\n pattern:\n console:\n spring:\n main:\n banner-mode: off\n ```\n\n\nThe [Server Configuration Properties](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html#_configuration_properties) documents all avai",
"chunk_index": 88,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__89",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "html#_configuration_properties) documents all available properties.\n\nNow let's dive into building your server.\n\n## Building your server\n\n### Weather Service\n\nLet's implement a [WeatherService.java](https://github.com/spring-projects/spring-ai-examples/blob/main/model-context-protocol/weather/starter",
"chunk_index": 89,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__90",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "s/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:\n\n```java theme={null}\n@Service\npublic class WeatherService {\n\n private final Re",
"chunk_index": 90,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__91",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "e\npublic class WeatherService {\n\n private final RestClient restClient;\n\n public WeatherService() {\n this.restClient = RestClient.builder()\n .baseUrl(\"https://api.weather.gov\")\n .defaultHeader(\"Accept\", \"application/geo+json\")\n .defaultHeader(\"User-Agent\", \"WeatherApiClient/1.0 (your@email.com)\")\n .b",
"chunk_index": 91,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__92",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ent\", \"WeatherApiClient/1.0 (your@email.com)\")\n .build();\n }\n\n @Tool(description = \"Get weather forecast for a specific latitude/longitude\")\n public String getWeatherForecastByLocation(\n double latitude, // Latitude coordinate\n double longitude // Longitude coordinate\n ) {\n // Returns detailed forec",
"chunk_index": 92,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__93",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ngitude coordinate\n ) {\n // Returns detailed forecast including:\n // - Temperature and unit\n // - Wind speed and direction\n // - Detailed forecast description\n }\n\n @Tool(description = \"Get weather alerts for a US state\")\n public String getAlerts(\n @ToolParam(description = \"Two-letter US state code (",
"chunk_index": 93,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__94",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "oolParam(description = \"Two-letter US state code (e.g. CA, NY)\") String state\n ) {\n // Returns active alerts including:\n // - Event type\n // - Affected area\n // - Severity\n // - Description\n // - Safety instructions\n }\n\n // ......\n}\n```\n\nThe `@Service` annotation with auto-register the service in yo",
"chunk_index": 94,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__95",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "e` annotation with auto-register the service in your application context.\nThe Spring AI `@Tool` annotation, making it easy to create and maintain MCP tools.\n\nThe auto-configuration will automatically register these tools with the MCP server.\n\n### Create your Boot Application\n\n```java theme={null}\n@S",
"chunk_index": 95,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__96",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ate your Boot Application\n\n```java theme={null}\n@SpringBootApplication\npublic class McpServerApplication {\n\n public static void main(String[] args) {\n SpringApplication.run(McpServerApplication.class, args);\n }\n\n @Bean\n public ToolCallbackProvider weatherTools(WeatherService weatherService) {\n retur",
"chunk_index": 96,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__97",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "atherTools(WeatherService weatherService) {\n return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();\n }\n}\n```\n\nUses the `MethodToolCallbackProvider` utils to convert the `@Tools` into actionable callbacks used by the MCP server.\n\n### Running the server\n\nFinally, let's build",
"chunk_index": 97,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__98",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "er.\n\n### Running the server\n\nFinally, let's build the server:\n\n```bash theme={null}\n./mvnw clean install\n```\n\nThis will generate a `mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar` file within the `target` folder.\n\nLet's now test your server from an existing MCP host, Claude for Desktop.\n\n## Testing you",
"chunk_index": 98,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__99",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ting MCP host, Claude for Desktop.\n\n## Testing your server with Claude for Desktop\n\n\n Claude for Desktop is not yet available on Linux.\n\n\nFirst, make sure you have Claude for Desktop installed.\n[You can install the latest version here.](https://claude.ai/download) If you already have Cl",
"chunk_index": 99,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__100",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**\n\nWe'll need to configure Claude for Desktop for whichever MCP servers you want to use.\nTo do this, open your Claude for Desktop App configuration at `~/Library/Application Support/Cl",
"chunk_index": 100,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__101",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "configuration at `~/Library/Application Support/Claude/claude_desktop_config.json` in a text editor.\nMake sure to create the file if it doesn't exist.\n\nFor example, if you have [VS Code](https://code.visualstudio.com/) installed:\n\n\n ```bash macOS/Linux theme={null}\n code ~/Library/Applica",
"chunk_index": 101,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__102",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "h macOS/Linux theme={null}\n code ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n ```\n\n ```powershell Windows theme={null}\n code $env:AppData\\Claude\\claude_desktop_config.json\n ```\n\n\nYou'll then add your servers in the `mcpServers` key.\nThe MCP UI elements will only show",
"chunk_index": 102,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__103",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "cpServers` key.\nThe MCP UI elements will only show up in Claude for Desktop if at least one server is properly configured.\n\nIn this case, we'll add our single weather server like so:\n\n\n ```json macOS/Linux theme={null}\n {\n \"mcpServers\": {\n \"spring-ai-mcp-weather\": {\n \"command\": \"java\",\n \"",
"chunk_index": 103,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__104",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "\"spring-ai-mcp-weather\": {\n \"command\": \"java\",\n \"args\": [\n \"-Dspring.ai.mcp.server.stdio=true\",\n \"-jar\",\n \"/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar\"\n ]\n }\n }\n }\n ```\n\n ```json Windows theme={null}\n {\n \"mcpServers\": {\n \"spring-ai-mcp-weather\": {\n \"command\": \"java\",",
"chunk_index": 104,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__105",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "{\n \"spring-ai-mcp-weather\": {\n \"command\": \"java\",\n \"args\": [\n \"-Dspring.ai.mcp.server.transport=STDIO\",\n \"-jar\",\n \"C:\\\\ABSOLUTE\\\\PATH\\\\TO\\\\PARENT\\\\FOLDER\\\\weather\\\\mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar\"\n ]\n }\n }\n }\n ```\n\n\n\n Make sure you pass in the absolute path to your ser",
"chunk_index": 105,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__106",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ake sure you pass in the absolute path to your server.\n\n\nThis tells Claude for Desktop:\n\n1. There's an MCP server named \"my-weather-server\"\n2. To launch it by running `java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar`\n\nSave the file, and restart **Claude f",
"chunk_index": 106,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__107",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "APSHOT.jar`\n\nSave the file, and restart **Claude for Desktop**.\n\n## Testing your server with Java client\n\n### Create an MCP Client manually\n\nUse the `McpClient` to connect to the server:\n\n```java theme={null}\nvar stdioParams = ServerParameters.builder(\"java\")\n .args(\"-jar\", \"/ABSOLUTE/PATH/TO/PARENT",
"chunk_index": 107,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__108",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "r(\"java\")\n .args(\"-jar\", \"/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar\")\n .build();\n\nvar stdioTransport = new StdioClientTransport(stdioParams);\n\nvar mcpClient = McpClient.sync(stdioTransport).build();\n\nmcpClient.initialize();\n\nListToolsResult toolsList = mcpClient.lis",
"chunk_index": 108,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__109",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "lize();\n\nListToolsResult toolsList = mcpClient.listTools();\n\nCallToolResult weather = mcpClient.callTool(\n new CallToolRequest(\"getWeatherForecastByLocation\",\n Map.of(\"latitude\", \"47.6062\", \"longitude\", \"-122.3321\")));\n\nCallToolResult alert = mcpClient.callTool(\n new CallToolRequest(\"getAlerts\", Map",
"chunk_index": 109,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__110",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "nt.callTool(\n new CallToolRequest(\"getAlerts\", Map.of(\"state\", \"NY\")));\n\nmcpClient.closeGracefully();\n```\n\n### Use MCP Client Boot Starter\n\nCreate a new boot starter application using the `spring-ai-starter-mcp-client` dependency:\n\n```xml theme={null}\n\n org.springframework.ai\n org.springframework.ai\n spring-ai-starter-mcp-client\n\n```\n\nand set the `spring.ai.mcp.client.stdio.servers-configuration` property to point to your `claude_desktop_config.json`.\nYou can reuse the existing Anthropic Desktop conf",
"chunk_index": 111,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__112",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "You can reuse the existing Anthropic Desktop configuration:\n\n```properties theme={null}\nspring.ai.mcp.client.stdio.servers-configuration=file:PATH/TO/claude_desktop_config.json\n```\n\nWhen you start your client application, the auto-configuration will create, automatically MCP clients from the claude",
"chunk_index": 112,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__113",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "create, automatically MCP clients from the claude\\_desktop\\_config.json.\n\nFor 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.\n\n## More Java MCP Server examples\n\nThe [starter-webflux-se",
"chunk_index": 113,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__114",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "Java MCP Server examples\n\nThe [starter-webflux-server](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-webflux-server) demonstrates how to create an MCP server using SSE transport.\nIt showcases how to define and register MCP Tools, Resources, a",
"chunk_index": 114,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__115",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "how to define and register MCP Tools, Resources, and Prompts, using the Spring Boot's auto-configuration capabilities.\n\n Let's get started with building our weather server! You can find the complete code for what we'll be building here.\n### Prerequisite knowledge\n\nThis quickstart assumes you have fa",
"chunk_index": 115,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__116",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ite knowledge\n\nThis quickstart assumes you have familiarity with:\n\n* Kotlin\n* LLMs like Claude\n\n### System requirements\n\n* Java 17 or higher installed.\n\n### Set up your environment\n\nFirst, let's install `java` and `gradle` if you haven't already.\nYou can download `java` from [official Oracle JDK web",
"chunk_index": 116,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__117",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "can download `java` from [official Oracle JDK website](https://www.oracle.com/java/technologies/downloads/).\nVerify your `java` installation:\n\n```bash theme={null}\njava --version\n```\n\nNow, let's create and set up your project:\n\n\n ```bash macOS/Linux theme={null}\n # Create a new directory",
"chunk_index": 117,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__118",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "macOS/Linux theme={null}\n # Create a new directory for our project\n mkdir weather\n cd weather\n\n # Initialize a new kotlin project\n gradle init\n ```\n\n ```powershell Windows theme={null}\n # Create a new directory for our project\n md weather\n cd weather\n\n # Initialize a new kotlin project\n gradle init",
"chunk_index": 118,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__119",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "# Initialize a new kotlin project\n gradle init\n ```\n\n\nAfter running `gradle init`, you will be presented with options for creating your project.\nSelect **Application** as the project type, **Kotlin** as the programming language, and **Java 17** as the Java version.\n\nAlternatively, you",
"chunk_index": 119,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__120",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "Java 17** as the Java version.\n\nAlternatively, you can create a Kotlin application using the [IntelliJ IDEA project wizard](https://kotlinlang.org/docs/jvm-get-started.html).\n\nAfter creating the project, add the following dependencies:\n\n\n ```kotlin build.gradle.kts theme={null}\n val mcpVe",
"chunk_index": 120,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__121",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "```kotlin build.gradle.kts theme={null}\n val mcpVersion = \"0.4.0\"\n val slf4jVersion = \"2.0.9\"\n val ktorVersion = \"3.1.1\"\n\n dependencies {\n implementation(\"io.modelcontextprotocol:kotlin-sdk:$mcpVersion\")\n implementation(\"org.slf4j:slf4j-nop:$slf4jVersion\")\n implementation(\"io.ktor:ktor-client-conten",
"chunk_index": 121,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__122",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "sion\")\n implementation(\"io.ktor:ktor-client-content-negotiation:$ktorVersion\")\n implementation(\"io.ktor:ktor-serialization-kotlinx-json:$ktorVersion\")\n }\n ```\n\n ```groovy build.gradle theme={null}\n def mcpVersion = '0.3.0'\n def slf4jVersion = '2.0.9'\n def ktorVersion = '3.1.1'\n\n dependencies {\n impl",
"chunk_index": 122,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__123",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "def ktorVersion = '3.1.1'\n\n dependencies {\n implementation \"io.modelcontextprotocol:kotlin-sdk:$mcpVersion\"\n implementation \"org.slf4j:slf4j-nop:$slf4jVersion\"\n implementation \"io.ktor:ktor-client-content-negotiation:$ktorVersion\"\n implementation \"io.ktor:ktor-serialization-kotlinx-json:$ktorVersi",
"chunk_index": 123,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__124",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "io.ktor:ktor-serialization-kotlinx-json:$ktorVersion\"\n }\n ```\n\n\nAlso, add the following plugins to your build script:\n\n\n ```kotlin build.gradle.kts theme={null}\n plugins {\n kotlin(\"plugin.serialization\") version \"your_version_of_kotlin\"\n id(\"com.github.johnrengelman.shadow\") v",
"chunk_index": 124,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__125",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "f_kotlin\"\n id(\"com.github.johnrengelman.shadow\") version \"8.1.1\"\n }\n ```\n\n ```groovy build.gradle theme={null}\n plugins {\n id 'org.jetbrains.kotlin.plugin.serialization' version 'your_version_of_kotlin'\n id 'com.github.johnrengelman.shadow' version '8.1.1'\n }\n ```\n\n\nNow let’s dive into b",
"chunk_index": 125,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__126",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "8.1.1'\n }\n ```\n\n\nNow let’s dive into building your server.\n\n## Building your server\n\n### Setting up the instance\n\nAdd a server initialization function:\n\n```kotlin theme={null}\n// Main function to run the MCP server\nfun `run mcp server`() {\n // Create the MCP Server instance with a basic",
"chunk_index": 126,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__127",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "{\n // Create the MCP Server instance with a basic implementation\n val server = Server(\n Implementation(\n name = \"weather\", // Tool name is \"weather\"\n version = \"1.0.0\" // Version of the implementation\n ),\n ServerOptions(\n capabilities = ServerCapabilities(tools = ServerCapabilities.Tools(listChanged",
"chunk_index": 127,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__128",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ities(tools = ServerCapabilities.Tools(listChanged = true))\n )\n )\n\n // Create a transport using standard IO for server communication\n val transport = StdioServerTransport(\n System.`in`.asInput(),\n System.out.asSink().buffered()\n )\n\n runBlocking {\n server.connect(transport)\n val done = Job()\n server.",
"chunk_index": 128,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__129",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "rver.connect(transport)\n val done = Job()\n server.onClose {\n done.complete()\n }\n done.join()\n }\n}\n```\n\n### Weather API helper functions\n\nNext, let's add functions and data classes for querying and converting responses from the National Weather Service API:\n\n```kotlin theme={null}\n// Extension functi",
"chunk_index": 129,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__130",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "e API:\n\n```kotlin theme={null}\n// Extension function to fetch forecast information for given latitude and longitude\nsuspend fun HttpClient.getForecast(latitude: Double, longitude: Double): List {\n val points = this.get(\"/points/$latitude,$longitude\").body()\n val forecast = this.get(p",
"chunk_index": 130,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__131",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "gitude\").body()\n val forecast = this.get(points.properties.forecast).body()\n return forecast.properties.periods.map { period ->\n \"\"\"\n ${period.name}:\n Temperature: ${period.temperature} ${period.temperatureUnit}\n Wind: ${period.windSpeed} ${period.windDirection}\n Forecast: ${period",
"chunk_index": 131,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__132",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "Speed} ${period.windDirection}\n Forecast: ${period.detailedForecast}\n \"\"\".trimIndent()\n }\n}\n\n// Extension function to fetch weather alerts for a given state\nsuspend fun HttpClient.getAlerts(state: String): List {\n val alerts = this.get(\"/alerts/active/area/$state\").body()\n return aler",
"chunk_index": 132,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__133",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ts/active/area/$state\").body()\n return alerts.features.map { feature ->\n \"\"\"\n Event: ${feature.properties.event}\n Area: ${feature.properties.areaDesc}\n Severity: ${feature.properties.severity}\n Description: ${feature.properties.description}\n Instruction: ${feature.properties.instruction}\n \"\"\"",
"chunk_index": 133,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__134",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "nstruction: ${feature.properties.instruction}\n \"\"\".trimIndent()\n }\n}\n\n@Serializable\ndata class Points(\n val properties: Properties\n) {\n @Serializable\n data class Properties(val forecast: String)\n}\n\n@Serializable\ndata class Forecast(\n val properties: Properties\n) {\n @Serializable\n data class Properti",
"chunk_index": 134,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__135",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "Properties\n) {\n @Serializable\n data class Properties(val periods: List)\n\n @Serializable\n data class Period(\n val number: Int, val name: String, val startTime: String, val endTime: String,\n val isDaytime: Boolean, val temperature: Int, val temperatureUnit: String,\n val temperatureTrend: Strin",
"chunk_index": 135,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__136",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "peratureUnit: String,\n val temperatureTrend: String, val probabilityOfPrecipitation: JsonObject,\n val windSpeed: String, val windDirection: String,\n val shortForecast: String, val detailedForecast: String,\n )\n}\n\n@Serializable\ndata class Alert(\n val features: List\n) {\n @Serializable\n data cl",
"chunk_index": 136,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__137",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "eatures: List\n) {\n @Serializable\n data class Feature(\n val properties: Properties\n )\n\n @Serializable\n data class Properties(\n val event: String, val areaDesc: String, val severity: String,\n val description: String, val instruction: String?,\n )\n}\n```\n\n### Implementing tool execution\n\nThe too",
"chunk_index": 137,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__138",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": ")\n}\n```\n\n### Implementing tool execution\n\nThe tool execution handler is responsible for actually executing the logic of each tool. Let's add it:\n\n```kotlin theme={null}\n// Create an HTTP client with a default request configuration and JSON content negotiation\nval httpClient = HttpClient {\n defaultR",
"chunk_index": 138,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__139",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "egotiation\nval httpClient = HttpClient {\n defaultRequest {\n url(\"https://api.weather.gov\")\n headers {\n append(\"Accept\", \"application/geo+json\")\n append(\"User-Agent\", \"WeatherApiClient/1.0\")\n }\n contentType(ContentType.Application.Json)\n }\n // Install content negotiation plugin for JSON serialization",
"chunk_index": 139,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__140",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "content negotiation plugin for JSON serialization/deserialization\n install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) }\n}\n\n// Register a tool to fetch weather alerts by state\nserver.addTool(\n name = \"get_alerts\",\n description = \"\"\"\n Get weather alerts for a US state. Input is Two",
"chunk_index": 140,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__141",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "\"\n Get weather alerts for a US state. Input is Two-letter US state code (e.g. CA, NY)\n \"\"\".trimIndent(),\n inputSchema = Tool.Input(\n properties = buildJsonObject {\n putJsonObject(\"state\") {\n put(\"type\", \"string\")\n put(\"description\", \"Two-letter US state code (e.g. CA, NY)\")\n }\n },\n required = listOf",
"chunk_index": 141,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__142",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ate code (e.g. CA, NY)\")\n }\n },\n required = listOf(\"state\")\n )\n) { request ->\n val state = request.arguments[\"state\"]?.jsonPrimitive?.content\n if (state == null) {\n return@addTool CallToolResult(\n content = listOf(TextContent(\"The 'state' parameter is required.\"))\n )\n }\n\n val alerts = httpClient.get",
"chunk_index": 142,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__143",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "s required.\"))\n )\n }\n\n val alerts = httpClient.getAlerts(state)\n\n CallToolResult(content = alerts.map { TextContent(it) })\n}\n\n// Register a tool to fetch weather forecast by latitude and longitude\nserver.addTool(\n name = \"get_forecast\",\n description = \"\"\"\n Get weather forecast for a specific latitud",
"chunk_index": 143,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__144",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "= \"\"\"\n Get weather forecast for a specific latitude/longitude\n \"\"\".trimIndent(),\n inputSchema = Tool.Input(\n properties = buildJsonObject {\n putJsonObject(\"latitude\") { put(\"type\", \"number\") }\n putJsonObject(\"longitude\") { put(\"type\", \"number\") }\n },\n required = listOf(\"latitude\", \"longitude\")\n )\n)",
"chunk_index": 144,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__145",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "required = listOf(\"latitude\", \"longitude\")\n )\n) { request ->\n val latitude = request.arguments[\"latitude\"]?.jsonPrimitive?.doubleOrNull\n val longitude = request.arguments[\"longitude\"]?.jsonPrimitive?.doubleOrNull\n if (latitude == null || longitude == null) {\n return@addTool CallToolResult(\n conten",
"chunk_index": 145,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__146",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "== null) {\n return@addTool CallToolResult(\n content = listOf(TextContent(\"The 'latitude' and 'longitude' parameters are required.\"))\n )\n }\n\n val forecast = httpClient.getForecast(latitude, longitude)\n\n CallToolResult(content = forecast.map { TextContent(it) })\n}\n```\n\n### Running the server\n\nFinally,",
"chunk_index": 146,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__147",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ent(it) })\n}\n```\n\n### Running the server\n\nFinally, implement the main function to run the server:\n\n```kotlin theme={null}\nfun main() = `run mcp server`()\n```\n\nMake sure to run `./gradlew build` to build your server. This is a very important step in getting your server to connect.\n\nLet's now test you",
"chunk_index": 147,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__148",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "etting your server to connect.\n\nLet's now test your server from an existing MCP host, Claude for Desktop.\n\n## Testing your server with Claude for Desktop\n\n\n Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/develop/build-client) tutorial",
"chunk_index": 148,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__149",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ing a client](/docs/develop/build-client) tutorial to build an MCP client that connects to the server we just built.\n\n\nFirst, make sure you have Claude for Desktop installed. [You can install the latest version\nhere.](https://claude.ai/download) If you already have Claude for Desktop, **make",
"chunk_index": 149,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__150",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "d) If you already have Claude for Desktop, **make sure it's updated to the latest version.**\n\nWe'll need to configure Claude for Desktop for whichever MCP servers you want to use.\nTo do this, open your Claude for Desktop App configuration at `~/Library/Application Support/Claude/claude_desktop_confi",
"chunk_index": 150,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__151",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ry/Application Support/Claude/claude_desktop_config.json` in a text editor.\nMake sure to create the file if it doesn't exist.\n\nFor example, if you have [VS Code](https://code.visualstudio.com/) installed:\n\n\n ```bash macOS/Linux theme={null}\n code ~/Library/Application\\ Support/Claude/clau",
"chunk_index": 151,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__152",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "}\n code ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n ```\n\n ```powershell Windows theme={null}\n code $env:AppData\\Claude\\claude_desktop_config.json\n ```\n\n\nYou'll then add your servers in the `mcpServers` key.\nThe MCP UI elements will only show up in Claude for Desktop",
"chunk_index": 152,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__153",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "I elements will only show up in Claude for Desktop if at least one server is properly configured.\n\nIn this case, we'll add our single weather server like so:\n\n\n ```json macOS/Linux theme={null}\n {\n \"mcpServers\": {\n \"weather\": {\n \"command\": \"java\",\n \"args\": [\n \"-jar\",\n \"/ABSOLUTE/PATH/TO/P",
"chunk_index": 153,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__154",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "\"java\",\n \"args\": [\n \"-jar\",\n \"/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/libs/weather-0.1.0-all.jar\"\n ]\n }\n }\n }\n ```\n\n ```json Windows theme={null}\n {\n \"mcpServers\": {\n \"weather\": {\n \"command\": \"java\",\n \"args\": [\n \"-jar\",\n \"C:\\\\PATH\\\\TO\\\\PARENT\\\\FOLDER\\\\weather\\\\build\\\\libs\\\\weather-0.1.0-all.j",
"chunk_index": 154,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__155",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "\\FOLDER\\\\weather\\\\build\\\\libs\\\\weather-0.1.0-all.jar\"\n ]\n }\n }\n }\n ```\n\n\nThis tells Claude for Desktop:\n\n1. There's an MCP server named \"weather\"\n2. Launch it by running `java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/libs/weather-0.1.0-all.jar`\n\nSave the file, and restart **Cla",
"chunk_index": 155,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__156",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "r-0.1.0-all.jar`\n\nSave the file, and restart **Claude for Desktop**.\n\n Let's get started with building our weather server! You can find the complete code for what we'll be building here.\n### Prerequisite knowledge\n\nThis quickstart assumes you have familiarity with:\n\n* C#\n* LLMs like Claude\n* .NET 8",
"chunk_index": 156,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__157",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "miliarity with:\n\n* C#\n* LLMs like Claude\n* .NET 8 or higher\n\n### Logging in MCP Servers\n\nWhen implementing MCP servers, be careful about how you handle logging:\n\n**For STDIO-based servers:** Never write to standard output (stdout). This includes:\n\n* `print()` statements in Python\n* `console.log()` i",
"chunk_index": 157,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__158",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "`print()` statements in Python\n* `console.log()` in JavaScript\n* `fmt.Println()` in Go\n* Similar stdout functions in other languages\n\nWriting to stdout will corrupt the JSON-RPC messages and break your server.\n\n**For HTTP-based servers:** Standard output logging is fine since it doesn't interfere wi",
"chunk_index": 158,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__159",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "tput logging is fine since it doesn't interfere with HTTP responses.\n\n### Best Practices\n\n1. Use a logging library that writes to stderr or files\n\n### System requirements\n\n* [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0) or higher installed.\n\n### Set up your environment\n\nFirst, let's",
"chunk_index": 159,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__160",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "talled.\n\n### Set up your environment\n\nFirst, 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:\n\n```bash theme={null}\ndotnet --version\n```\n\nNow, let's create and s",
"chunk_index": 160,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__161",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ull}\ndotnet --version\n```\n\nNow, let's create and set up your project:\n\n\n ```bash macOS/Linux theme={null}\n # Create a new directory for our project\n mkdir weather\n cd weather\n # Initialize a new C# project\n dotnet new console\n ```\n\n ```powershell Windows theme={null}\n # Create a new direc",
"chunk_index": 161,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__162",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ershell Windows theme={null}\n # Create a new directory for our project\n mkdir weather\n cd weather\n # Initialize a new C# project\n dotnet new console\n ```\n\n\nAfter running `dotnet new console`, you will be presented with a new C# project.\nYou can open the project in your favorite IDE, such",
"chunk_index": 162,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__163",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ou can open the project in your favorite IDE, such as [Visual Studio](https://visualstudio.microsoft.com/) or [Rider](https://www.jetbrains.com/rider/).\nAlternatively, you can create a C# application using the [Visual Studio project wizard](https://learn.microsoft.com/en-us/visualstudio/get-started/",
"chunk_index": 163,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__164",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "earn.microsoft.com/en-us/visualstudio/get-started/csharp/tutorial-console?view=vs-2022).\nAfter creating the project, add NuGet package for the Model Context Protocol SDK and hosting:\n\n```bash theme={null}\n# Add the Model Context Protocol SDK NuGet package\ndotnet add package ModelContextProtocol --pr",
"chunk_index": 164,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__165",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ckage\ndotnet add package ModelContextProtocol --prerelease\n# Add the .NET Hosting NuGet package\ndotnet add package Microsoft.Extensions.Hosting\n```\n\nNow let’s dive into building your server.\n\n## Building your server\n\nOpen the `Program.cs` file in your project and replace its contents with the follow",
"chunk_index": 165,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__166",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "r project and replace its contents with the following code:\n\n```csharp theme={null}\nusing Microsoft.Extensions.DependencyInjection;\nusing Microsoft.Extensions.Hosting;\nusing ModelContextProtocol;\nusing System.Net.Http.Headers;\n\nvar builder = Host.CreateEmptyApplicationBuilder(settings: null);\n\nbuild",
"chunk_index": 166,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__167",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ateEmptyApplicationBuilder(settings: null);\n\nbuilder.Services.AddMcpServer()\n .WithStdioServerTransport()\n .WithToolsFromAssembly();\n\nbuilder.Services.AddSingleton(_ =>\n{\n var client = new HttpClient() { BaseAddress = new Uri(\"https://api.weather.gov\") };\n client.DefaultRequestHeaders.UserAgent.Add(",
"chunk_index": 167,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__168",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "\") };\n client.DefaultRequestHeaders.UserAgent.Add(new ProductInfoHeaderValue(\"weather-tool\", \"1.0\"));\n return client;\n});\n\nvar app = builder.Build();\n\nawait app.RunAsync();\n```\n\n\n When creating the `ApplicationHostBuilder`, ensure you use `CreateEmptyApplicationBuilder` instead of `CreateDefau",
"chunk_index": 168,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__169",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "teEmptyApplicationBuilder` instead of `CreateDefaultBuilder`. This ensures that the server does not write any additional messages to the console. This is only necessary for servers using STDIO transport.\n\n\nThis code sets up a basic console application that uses the Model Context Protocol SDK",
"chunk_index": 169,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__170",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "lication that uses the Model Context Protocol SDK to create an MCP server with standard I/O transport.\n\n### Weather API helper functions\n\nCreate an extension class for `HttpClient` which helps simplify JSON request handling:\n\n```csharp theme={null}\nusing System.Text.Json;\n\ninternal static class Http",
"chunk_index": 170,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__171",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "sing System.Text.Json;\n\ninternal static class HttpClientExt\n{\n public static async Task ReadJsonDocumentAsync(this HttpClient client, string requestUri)\n {\n using var response = await client.GetAsync(requestUri);\n response.EnsureSuccessStatusCode();\n return await JsonDocument.ParseAsyn",
"chunk_index": 171,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__172",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "StatusCode();\n return await JsonDocument.ParseAsync(await response.Content.ReadAsStreamAsync());\n }\n}\n```\n\nNext, define a class with the tool execution handlers for querying and converting responses from the National Weather Service API:\n\n```csharp theme={null}\nusing ModelContextProtocol.Server;\nusi",
"chunk_index": 172,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__173",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "heme={null}\nusing ModelContextProtocol.Server;\nusing System.ComponentModel;\nusing System.Globalization;\nusing System.Text.Json;\n\nnamespace QuickstartWeatherServer.Tools;\n\n[McpServerToolType]\npublic static class WeatherTools\n{\n [McpServerTool, Description(\"Get weather alerts for a US state.\")]\n publi",
"chunk_index": 173,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__174",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "tion(\"Get weather alerts for a US state.\")]\n public static async Task GetAlerts(\n HttpClient client,\n [Description(\"The US state to get alerts for.\")] string state)\n {\n using var jsonDocument = await client.ReadJsonDocumentAsync($\"/alerts/active/area/{state}\");\n var jsonElement = jsonDocumen",
"chunk_index": 174,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__175",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ive/area/{state}\");\n var jsonElement = jsonDocument.RootElement;\n var alerts = jsonElement.GetProperty(\"features\").EnumerateArray();\n\n if (!alerts.Any())\n {\n return \"No active alerts for this state.\";\n }\n\n return string.Join(\"\\n--\\n\", alerts.Select(alert =>\n {\n JsonElement properties = alert.GetProp",
"chunk_index": 175,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__176",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "lert =>\n {\n JsonElement properties = alert.GetProperty(\"properties\");\n return $\"\"\"\n Event: {properties.GetProperty(\"event\").GetString()}\n Area: {properties.GetProperty(\"areaDesc\").GetString()}\n Severity: {properties.GetProperty(\"severity\").GetString()}\n Description: {properties.GetProperty(\"descript",
"chunk_index": 176,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__177",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": ")}\n Description: {properties.GetProperty(\"description\").GetString()}\n Instruction: {properties.GetProperty(\"instruction\").GetString()}\n \"\"\";\n }));\n }\n\n [McpServerTool, Description(\"Get weather forecast for a location.\")]\n public static async Task GetForecast(\n HttpClient client,\n [Descriptio",
"chunk_index": 177,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__178",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ing> GetForecast(\n HttpClient client,\n [Description(\"Latitude of the location.\")] double latitude,\n [Description(\"Longitude of the location.\")] double longitude)\n {\n var pointUrl = string.Create(CultureInfo.InvariantCulture, $\"/points/{latitude},{longitude}\");\n using var jsonDocument = await client.",
"chunk_index": 178,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__179",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "gitude}\");\n using var jsonDocument = await client.ReadJsonDocumentAsync(pointUrl);\n var forecastUrl = jsonDocument.RootElement.GetProperty(\"properties\").GetProperty(\"forecast\").GetString()\n ?? throw new Exception($\"No forecast URL provided by {client.BaseAddress}points/{latitude},{longitude}\");\n\n us",
"chunk_index": 179,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__180",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": ".BaseAddress}points/{latitude},{longitude}\");\n\n using var forecastDocument = await client.ReadJsonDocumentAsync(forecastUrl);\n var periods = forecastDocument.RootElement.GetProperty(\"properties\").GetProperty(\"periods\").EnumerateArray();\n\n return string.Join(\"\\n---\\n\", periods.Select(period => $\"\"\"",
"chunk_index": 180,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__181",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ng.Join(\"\\n---\\n\", periods.Select(period => $\"\"\"\n {period.GetProperty(\"name\").GetString()}\n Temperature: {period.GetProperty(\"temperature\").GetInt32()}°F\n Wind: {period.GetProperty(\"windSpeed\").GetString()} {period.GetProperty(\"windDirection\").GetString()}\n Forecast: {period.GetProperty(\"detailedFor",
"chunk_index": 181,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__182",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ing()}\n Forecast: {period.GetProperty(\"detailedForecast\").GetString()}\n \"\"\"));\n }\n}\n```\n\n### Running the server\n\nFinally, run the server using the following command:\n\n```bash theme={null}\ndotnet run\n```\n\nThis will start the server and listen for incoming requests on standard input/output.\n\n## Testin",
"chunk_index": 182,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__183",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ming requests on standard input/output.\n\n## Testing your server with Claude for Desktop\n\n\n Claude for Desktop is not yet available on Linux. Linux users can proceed to the [Building a client](/docs/develop/build-client) tutorial to build an MCP client that connects to the server we just built.",
"chunk_index": 183,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__184",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "client that connects to the server we just built.\n\n\nFirst, make sure you have Claude for Desktop installed. [You can install the latest version\nhere.](https://claude.ai/download) If you already have Claude for Desktop, **make sure it's updated to the latest version.**\nWe'll need to configure",
"chunk_index": 184,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__185",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "d to the latest version.**\nWe'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'",
"chunk_index": 185,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__186",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "editor. Make sure to create the file if it doesn't exist.\nFor example, if you have [VS Code](https://code.visualstudio.com/) installed:\n\n\n ```bash macOS/Linux theme={null}\n code ~/Library/Application\\ Support/Claude/claude_desktop_config.json\n ```\n\n ```powershell Windows theme={null}\n co",
"chunk_index": 186,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__187",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "json\n ```\n\n ```powershell Windows theme={null}\n code $env:AppData\\Claude\\claude_desktop_config.json\n ```\n\n\nYou'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.\nIn this case, we'll",
"chunk_index": 187,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__188",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "erver is properly configured.\nIn this case, we'll add our single weather server like so:\n\n\n ```json macOS/Linux theme={null}\n {\n \"mcpServers\": {\n \"weather\": {\n \"command\": \"dotnet\",\n \"args\": [\"run\", \"--project\", \"/ABSOLUTE/PATH/TO/PROJECT\", \"--no-build\"]\n }\n }\n }\n ```\n\n ```json Windows the",
"chunk_index": 188,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__189",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "\"--no-build\"]\n }\n }\n }\n ```\n\n ```json Windows theme={null}\n {\n \"mcpServers\": {\n \"weather\": {\n \"command\": \"dotnet\",\n \"args\": [\n \"run\",\n \"--project\",\n \"C:\\\\ABSOLUTE\\\\PATH\\\\TO\\\\PROJECT\",\n \"--no-build\"\n ]\n }\n }\n }\n ```\n\n\nThis tells Claude for Desktop:\n\n1. There's an MCP server named \"weathe",
"chunk_index": 189,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__190",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "r Desktop:\n\n1. There's an MCP server named \"weather\"\n2. Launch it by running `dotnet run /ABSOLUTE/PATH/TO/PROJECT`\n Save the file, and restart **Claude for Desktop**.\n\nTest with commands\nLet's make sure Claude for Desktop is picking up the two tools we've exposed in our weather server. You can do t",
"chunk_index": 190,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__191",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "we've exposed in our weather server. You can do this by looking for the \"Search and tools\" icon:\n\nAfter clicking on the slider icon, you should see two tools listed:\n\nIf your server isn't being picked up by Claude for Desktop, proceed to the Troubleshooting section for debugging tips.\nIf the tool s",
"chunk_index": 191,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__192",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "shooting section for debugging tips.\nIf the tool settings icon has shown up, you can now test your server by running the following commands in Claude for Desktop:\n\nWhat's the weather in Sacramento?\nWhat are the active weather alerts in Texas?\n\n Since this is the US National Weather service, the quer",
"chunk_index": 192,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__193",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "this is the US National Weather service, the queries will only work for US locations.\n\nWhat's happening under the hood\nWhen you ask a question:\n\nThe client sends your question to Claude\nClaude analyzes the available tools and decides which one(s) to use\nThe client executes the chosen tool(s) throug",
"chunk_index": 193,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__194",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "use\nThe client executes the chosen tool(s) through the MCP server\nThe results are sent back to Claude\nClaude formulates a natural language response\nThe response is displayed to you!\n\nTroubleshooting\n\nGetting logs from Claude for Desktop\nClaude.app logging related to MCP is written to log files in `",
"chunk_index": 194,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__195",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ogging related to MCP is written to log files in `~/Library/Logs/Claude`:\n\n* `mcp.log` will contain general logging about MCP connections and connection failures.\n* Files named `mcp-server-SERVERNAME.log` will contain error (stderr) logging from the named server.\n\nYou can run the following command t",
"chunk_index": 195,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__196",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "named server.\n\nYou can run the following command to list recent logs and follow along with any new ones:\n\n```bash theme={null}\n# Check Claude's logs for errors\ntail -n 20 -f ~/Library/Logs/Claude/mcp*.log\n```\n\n**Server not showing up in Claude**\n\n1. Check your `claude_desktop_config.json` file synta",
"chunk_index": 196,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__197",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "Check your `claude_desktop_config.json` file syntax\n2. Make sure the path to your project is absolute and not relative\n3. Restart Claude for Desktop completely\n\n\n To properly restart Claude for Desktop, you must fully quit the application:\n\n * **Windows**: Right-click the Claude icon in the",
"chunk_index": 197,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__198",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "* **Windows**: Right-click the Claude icon in the system tray (which may be hidden in the \"hidden icons\" menu) and select \"Quit\" or \"Exit\".\n * **macOS**: Use Cmd+Q or select \"Quit Claude\" from the menu bar.\n\n Simply closing the window does not fully quit the application, and your MCP server configu",
"chunk_index": 198,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__199",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "quit the application, and your MCP server configuration changes will not take effect.\n\n\n**Tool calls failing silently**\n\nIf Claude attempts to use the tools but they fail:\n\n1. Check Claude's logs for errors\n2. Verify your server builds and runs without errors\n3. Try restarting Claude for",
"chunk_index": 199,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__200",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "runs without errors\n3. Try restarting Claude for Desktop\n\n**None of this is working. What do I do?**\n\nPlease refer to our [debugging guide](/legacy/tools/debugging) for better debugging tools and more detailed guidance.\n\nError: Failed to retrieve grid point data\nThis usually means either:\n\n1. The c",
"chunk_index": 200,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__201",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "id point data\nThis usually means either:\n\n1. The coordinates are outside the US\n2. The NWS API is having issues\n3. You're being rate limited\n\nFix:\n\n* Verify you're using US coordinates\n* Add a small delay between requests\n* Check the NWS API status page\n\n**Error: No active alerts for \\[STATE]**\n\nThi",
"chunk_index": 201,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__202",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "age\n\n**Error: No active alerts for \\[STATE]**\n\nThis 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.\n\n For more advanced troubleshooting, check out our guide on Debugging MCP\n\nNext steps\n\n Learn how to build your",
"chunk_index": 202,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__203",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "ebugging MCP\n\nNext steps\n\n Learn how to build your own MCP client that can connect to your server\n \n\n Check out our gallery of official MCP servers and implementations\n \n\n Learn how to effectively debug MCP servers and integrations\n \n\n Learn how to use LLMs like Claude to speed up your MCP developme",
"chunk_index": 203,
"total_chunks": 205
},
{
"chunk_id": "md_build-server_b4682181__204",
"doc_id": "md_build-server_b4682181",
"title": "Build an MCP server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\build-server.md",
"filename": "build-server.md",
"file_path": "build-server.md",
"updated_at": "1760788520.8599238",
"text": "se LLMs like Claude to speed up your MCP development",
"chunk_index": 204,
"total_chunks": 205
},
{
"chunk_id": "md_client-concepts_66f702b4__0",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "Understanding MCP clients\nMCP clients are instantiated by host applications to communicate with particular MCP servers. The host application, like Claude.ai or an IDE, manages the overall user experience and coordinates multiple clients. Each client handles one direct communication with one server.",
"chunk_index": 0,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__1",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "handles one direct communication with one server.\nUnderstanding the distinction is important: the host is the application users interact with, while clients are the protocol-level components that enable server connections.\nCore Client Features\nIn addition to making use of context provided by servers",
"chunk_index": 1,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__2",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ition to making use of context provided by servers, clients may provide several features to servers. These client features allow server authors to build richer interactions.\n| Feature | Explanation | Example |\n| --------------- | ----------------------------------------------------------------------",
"chunk_index": 2,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__3",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------",
"chunk_index": 3,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__4",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "------------------------------------------------------------ |\n| Sampling | Sampling allows servers to request LLM completions through the client, enabling an agentic workflow. This approach puts the client in complete control of user permissions and security measures. | A server for booking travel",
"chunk_index": 4,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__5",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "security measures. | A server for booking travel may send a list of flights to an LLM and request that the LLM pick the best flight for the user. |\n| Roots | Roots allow clients to specify which directories servers should focus on, communicating intended scope through a coordination mechanism. | A",
"chunk_index": 5,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__6",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ended scope through a coordination mechanism. | A server for booking travel may be given access to a specific directory, from which it can read a user's calendar. |\n| Elicitation | Elicitation enables servers to request specific information from users during interactions, providing a structured way",
"chunk_index": 6,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__7",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "s during interactions, providing a structured way for servers to gather information on demand. | A server booking travel may ask for the user's preferences on airplane seats, room type or their contact number to finalise a booking. |\nElicitation\nElicitation enables servers to request specific inform",
"chunk_index": 7,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__8",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "itation enables servers to request specific information from users during interactions, creating more dynamic and responsive workflows.\nOverview\nElicitation provides a structured way for servers to gather necessary information on demand. Instead of requiring all information up front or failing when",
"chunk_index": 8,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__9",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "equiring all information up front or failing when data is missing, servers can pause their operations to request specific inputs from users. This creates more flexible interactions where servers adapt to user needs rather than following rigid patterns.\nElicitation flow:\n```mermaid theme={null}\nseque",
"chunk_index": 9,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__10",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "s.\nElicitation flow:\n```mermaid theme={null}\nsequenceDiagram\n participant User\n participant Client\n participant Server\nNote over Server,Client: Server initiates elicitation\nServer->>Client: elicitation/create\n\nNote over Client,User: Human interaction\nClient->>User: Present elicitation UI\nUser-->>Cli",
"chunk_index": 10,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__11",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "Client->>User: Present elicitation UI\nUser-->>Client: Provide requested information\n\nNote over Server,Client: Complete request\nClient-->>Server: Return user response\n\nNote over Server: Continue processing with new information\n\n```\nThe flow enables dynamic information gathering. Servers can request",
"chunk_index": 11,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__12",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ynamic information gathering. Servers can request specific data when needed, users provide information through appropriate UI, and servers continue processing with the newly acquired context.\nElicitation components example:\ntypescript theme={null}\n{\n method: \"elicitation/requestInput\",\n params: {\n m",
"chunk_index": 12,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__13",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "method: \"elicitation/requestInput\",\n params: {\n message: \"Please confirm your Barcelona vacation booking details:\",\n schema: {\n type: \"object\",\n properties: {\n confirmBooking: {\n type: \"boolean\",\n description: \"Confirm the booking (Flights + Hotel = $3,000)\"\n },\n seatPreference: {\n type: \"string\",",
"chunk_index": 13,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__14",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "$3,000)\"\n },\n seatPreference: {\n type: \"string\",\n enum: [\"window\", \"aisle\", \"no preference\"],\n description: \"Preferred seat type for flights\"\n },\n roomType: {\n type: \"string\",\n enum: [\"sea view\", \"city view\", \"garden view\"],\n description: \"Preferred room type at hotel\"\n },\n travelInsurance: {\n type",
"chunk_index": 14,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__15",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "room type at hotel\"\n },\n travelInsurance: {\n type: \"boolean\",\n default: false,\n description: \"Add travel insurance ($150)\"\n }\n },\n required: [\"confirmBooking\"]\n }\n }\n}\nExample: Holiday Booking Approval\nA travel booking server demonstrates elicitation's power through the final booking confirmation p",
"chunk_index": 15,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__16",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "n's power through the final booking confirmation process. When a user has selected their ideal vacation package to Barcelona, the server needs to gather final approval and any missing details before proceeding.\nThe server elicits booking confirmation with a structured request that includes the trip",
"chunk_index": 16,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__17",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "with a structured request that includes the trip summary (Barcelona flights June 15-22, beachfront hotel, total \\$3,000) and fields for any additional preferences—such as seat selection, room type, or travel insurance options.\nAs the booking progresses, the server elicits contact information needed",
"chunk_index": 17,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__18",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ses, the server elicits contact information needed to complete the reservation. It might ask for traveler details for flight bookings, special requests for the hotel, or emergency contact information.\nUser Interaction Model\nElicitation interactions are designed to be clear, contextual, and respectfu",
"chunk_index": 18,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__19",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "re designed to be clear, contextual, and respectful of user autonomy:\nRequest presentation: Clients display elicitation requests with clear context about which server is asking, why the information is needed, and how it will be used. The request message explains the purpose while the schema provides",
"chunk_index": 19,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__20",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "age explains the purpose while the schema provides structure and validation.\nResponse options: Users can provide the requested information through appropriate UI controls (text fields, dropdowns, checkboxes), decline to provide information with optional explanation, or cancel the entire operation. C",
"chunk_index": 20,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__21",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "nal explanation, or cancel the entire operation. Clients validate responses against the provided schema before returning them to servers.\nPrivacy considerations: Elicitation never requests passwords or API keys. Clients warn about suspicious requests and let users review data before sending.\nRoots\nR",
"chunk_index": 21,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__22",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "and let users review data before sending.\nRoots\nRoots define filesystem boundaries for server operations, allowing clients to specify which directories servers should focus on.\nOverview\nRoots are a mechanism for clients to communicate filesystem access boundaries to servers. They consist of file UR",
"chunk_index": 22,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__23",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ess boundaries to servers. They consist of file URIs that indicate directories where servers can operate, helping servers understand the scope of available files and folders. While roots communicate intended boundaries, they do not enforce security restrictions. Actual security must be enforced at t",
"chunk_index": 23,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__24",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "estrictions. Actual security must be enforced at the operating system level, via file permissions and/or sandboxing.\nRoot structure:\njson theme={null}\n{\n \"uri\": \"file:///Users/agent/travel-planning\",\n \"name\": \"Travel Planning Workspace\"\n}\nRoots are exclusively filesystem paths and always use the fil",
"chunk_index": 24,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__25",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "xclusively filesystem paths and always use the file:// URI scheme. They help servers understand project boundaries, workspace organization, and accessible directories. The roots list can be updated dynamically as users work with different projects or folders, with servers receiving notifications thr",
"chunk_index": 25,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__26",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "folders, with servers receiving notifications through roots/list_changed when boundaries change.\nExample: Travel Planning Workspace\nA travel agent working with multiple client trips benefits from roots to organize filesystem access. Consider a workspace with different directories for various aspect",
"chunk_index": 26,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__27",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "pace with different directories for various aspects of travel planning.\nThe client provides filesystem roots to the travel planning server:\n\nfile:///Users/agent/travel-planning - Main workspace containing all travel files\nfile:///Users/agent/travel-templates - Reusable itinerary templates and resour",
"chunk_index": 27,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__28",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "emplates - Reusable itinerary templates and resources\nfile:///Users/agent/client-documents - Client passports and travel documents\n\nWhen the agent creates a Barcelona itinerary, well-behaved servers respect these boundaries—accessing templates, saving the new itinerary, and referencing client docume",
"chunk_index": 28,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__29",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "g the new itinerary, and referencing client documents within the specified roots. Servers typically access files within roots by using relative paths from the root directories or by utilizing file search tools that respect the root boundaries.\nIf the agent opens an archive folder like file:///Users/",
"chunk_index": 29,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__30",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "agent opens an archive folder like file:///Users/agent/archive/2023-trips, the client updates the roots list via roots/list_changed.\nFor a complete implementation of a server that respects roots, see the filesystem server in the official servers repository.\nDesign Philosophy\nRoots serve as a coordi",
"chunk_index": 30,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__31",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ository.\nDesign Philosophy\nRoots serve as a coordination mechanism between clients and servers, not a security boundary. The specification requires that servers \"SHOULD respect root boundaries,\" and not that they \"MUST enforce\" them, because servers run code the client cannot control.\nRoots work bes",
"chunk_index": 31,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__32",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "run code the client cannot control.\nRoots work best when servers are trusted or vetted, users understand their advisory nature, and the goal is preventing accidents rather than stopping malicious behavior. They excel at context scoping (telling servers where to focus), accident prevention (helping w",
"chunk_index": 32,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__33",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "rs where to focus), accident prevention (helping well-behaved servers stay in bounds), and workflow organization (such as managing project boundaries automatically).\nUser Interaction Model\nRoots are typically managed automatically by host applications based on user actions, though some applications",
"chunk_index": 33,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__34",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "s based on user actions, though some applications may expose manual root management:\nAutomatic root detection: When users open folders, clients automatically expose them as roots. Opening a travel workspace allows the client to expose that directory as a root, helping servers understand which itiner",
"chunk_index": 34,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__35",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "as a root, helping servers understand which itineraries and documents are in scope for the current work.\nManual root configuration: Advanced users can specify roots through configuration. For example, adding /travel-templates for reusable resources while excluding directories with financial records.",
"chunk_index": 35,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__36",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "hile excluding directories with financial records.\nSampling\nSampling allows servers to request language model completions through the client, enabling agentic behaviors while maintaining security and user control.\nOverview\nSampling enables servers to perform AI-dependent tasks without directly integ",
"chunk_index": 36,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__37",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "perform AI-dependent tasks without directly integrating with or paying for AI models. Instead, servers can request that the client—which already has AI model access—handle these tasks on their behalf. This approach puts the client in complete control of user permissions and security measures. Becau",
"chunk_index": 37,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__38",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "l of user permissions and security measures. Because sampling requests occur within the context of other operations—like a tool analyzing data—and are processed as separate model calls, they maintain clear boundaries between different contexts, allowing for more efficient use of the context window.",
"chunk_index": 38,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__39",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ing for more efficient use of the context window.\nSampling flow:\n```mermaid theme={null}\nsequenceDiagram\n participant LLM\n participant User\n participant Client\n participant Server\nNote over Server,Client: Server initiates sampling\nServer->>Client: sampling/createMessage\n\nNote over Client,User: Human",
"chunk_index": 39,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__40",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "mpling/createMessage\n\nNote over Client,User: Human-in-the-loop review\nClient->>User: Present request for approval\nUser-->>Client: Review and approve/modify\n\nNote over Client,LLM: Model interaction\nClient->>LLM: Forward approved request\nLLM-->>Client: Return generation\n\nNote over Client,User: Respons",
"chunk_index": 40,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__41",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "Return generation\n\nNote over Client,User: Response review\nClient->>User: Present response for approval\nUser-->>Client: Review and approve/modify\n\nNote over Server,Client: Complete request\nClient-->>Server: Return approved response\n\n```\nThe flow ensures security through multiple human-in-the-loop ch",
"chunk_index": 41,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__42",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "res security through multiple human-in-the-loop checkpoints. Users review and can modify both the initial request and the generated response before it returns to the server.\nRequest parameters example:\ntypescript theme={null}\n{\n messages: [\n {\n role: \"user\",\n content: \"Analyze these flight options a",
"chunk_index": 42,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__43",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "\"user\",\n content: \"Analyze these flight options and recommend the best choice:\\n\" +\n \"[47 flights with prices, times, airlines, and layovers]\\n\" +\n \"User preferences: morning departure, max 1 layover\"\n }\n ],\n modelPreferences: {\n hints: [{\n name: \"claude-3-5-sonnet\" // Suggested model\n }],\n costPri",
"chunk_index": 43,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__44",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "laude-3-5-sonnet\" // Suggested model\n }],\n costPriority: 0.3, // Less concerned about API cost\n speedPriority: 0.2, // Can wait for thorough analysis\n intelligencePriority: 0.9 // Need complex trade-off evaluation\n },\n systemPrompt: \"You are a travel expert helping users find the best flights based",
"chunk_index": 44,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__45",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "expert helping users find the best flights based on their preferences\",\n maxTokens: 1500\n}\nExample: Flight Analysis Tool\nConsider a travel booking server with a tool called findBestFlight that uses sampling to analyze available flights and recommend the optimal choice. When a user asks \"Book me the",
"chunk_index": 45,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__46",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "the optimal choice. When a user asks \"Book me the best flight to Barcelona next month,\" the tool needs AI assistance to evaluate complex trade-offs.\nThe tool queries airline APIs and gathers 47 flight options. It then requests AI assistance to analyze these options: \"Analyze these flight options an",
"chunk_index": 46,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__47",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ze these options: \"Analyze these flight options and recommend the best choice: [47 flights with prices, times, airlines, and layovers] User preferences: morning departure, max 1 layover.\"\nThe client initiates the sampling request, allowing the AI to evaluate trade-offs—like cheaper red-eye flights v",
"chunk_index": 47,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__48",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "evaluate trade-offs—like cheaper red-eye flights versus convenient morning departures. The tool uses this analysis to present the top three recommendations.\nUser Interaction Model\nWhile not a requirement, sampling is designed to allow human-in-the-loop control. Users can maintain oversight through s",
"chunk_index": 48,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__49",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "op control. Users can maintain oversight through several mechanisms:\nApproval controls: Sampling requests may require explicit user consent. Clients can show what the server wants to analyze and why. Users can approve, deny, or modify requests.\nTransparency features: Clients can display the exact pr",
"chunk_index": 49,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__50",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "parency features: Clients can display the exact prompt, model selection, and token limits, allowing users to review AI responses before they return to the server.\nConfiguration options: Users can set model preferences, configure auto-approval for trusted operations, or require approval for everythin",
"chunk_index": 50,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__51",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "sted operations, or require approval for everything. Clients may provide options to redact sensitive information.\nSecurity considerations: Both clients and servers must handle sensitive data appropriately during sampling. Clients should implement rate limiting and validate all message content. The h",
"chunk_index": 51,
"total_chunks": 53
},
{
"chunk_id": "md_client-concepts_66f702b4__52",
"doc_id": "md_client-concepts_66f702b4",
"title": "Understanding MCP clients",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\client-concepts.md",
"filename": "client-concepts.md",
"file_path": "client-concepts.md",
"updated_at": "1760788520.8599238",
"text": "e limiting and validate all message content. The human-in-the-loop design ensures that server-initiated AI interactions cannot compromise security or access sensitive data without explicit user consent.",
"chunk_index": 52,
"total_chunks": 53
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__0",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "Connect to local MCP servers\n\nLearn how to extend Claude Desktop with local MCP servers to enable file system access and other powerful integrations\n\nModel Context Protocol (MCP) servers extend AI applications' capabilities by providing secure, controlled access to local resources and tools. Many cl",
"chunk_index": 0,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__1",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "olled access to local resources and tools. Many clients support MCP, enabling diverse integration possibilities across different platforms and applications.\nThis guide demonstrates how to connect to local MCP servers using Claude Desktop as an example, one of the many clients that support MCP. While",
"chunk_index": 1,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__2",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "e, one of the many clients that support MCP. While we focus on Claude Desktop's implementation, the concepts apply broadly to other MCP-compatible clients. By the end of this tutorial, Claude will be able to interact with files on your computer, create new documents, organize folders, and search thr",
"chunk_index": 2,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__3",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "te new documents, organize folders, and search through your file system—all with your explicit permission for each action.\n\nPrerequisites\nBefore starting this tutorial, ensure you have the following installed on your system:\nClaude Desktop\nDownload and install Claude Desktop for your operating syste",
"chunk_index": 3,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__4",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "nd install Claude Desktop for your operating system. Claude Desktop is available for macOS and Windows.\nIf you already have Claude Desktop installed, verify you're running the latest version by clicking the Claude menu and selecting \"Check for Updates...\"\nNode.js\nThe Filesystem Server and many other",
"chunk_index": 4,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__5",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "s...\"\nNode.js\nThe Filesystem Server and many other MCP servers require Node.js to run. Verify your Node.js installation by opening a terminal or command prompt and running:\nbash theme={null}\nnode --version\nIf Node.js is not installed, download it from nodejs.org. We recommend the LTS (Long Term Supp",
"chunk_index": 5,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__6",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "m nodejs.org. We recommend the LTS (Long Term Support) version for stability.\nUnderstanding MCP Servers\nMCP servers are programs that run on your computer and provide specific capabilities to Claude Desktop through a standardized protocol. Each server exposes tools that Claude can use to perform act",
"chunk_index": 6,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__7",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "r exposes tools that Claude can use to perform actions, with your approval. The Filesystem Server we'll install provides tools for:\n\nReading file contents and directory structures\nCreating new files and directories\nMoving and renaming files\nSearching for files by name or content\n\nAll actions require",
"chunk_index": 7,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__8",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "for files by name or content\n\nAll actions require your explicit approval before execution, ensuring you maintain full control over what Claude can access and modify.\nInstalling the Filesystem Server\nThe process involves configuring Claude Desktop to automatically start the Filesystem Server wheneve",
"chunk_index": 8,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__9",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "automatically start the Filesystem Server whenever you launch the application. This configuration is done through a JSON file that tells Claude Desktop which servers to run and how to connect to them.\n\n Start by accessing the Claude Desktop settings. Click on the Claude menu in your system's menu b",
"chunk_index": 9,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__10",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": ". Click on the Claude menu in your system's menu bar (not the settings within the Claude window itself) and select \"Settings...\"\nOn macOS, this appears in the top menu bar:\n\n\n ![\"Claude](\"https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-menu.png?fit=max",)
\n\n\nThis opens the Claud",
"chunk_index": 15,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__16",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "df94299a0 2500w\" />\n\n\nThis opens the Claude Desktop configuration window, which is separate from your Claude account settings.\n\n In the Settings window, navigate to the \"Developer\" tab in the left sidebar. This section contains options for configuring MCP servers and other developer features",
"chunk_index": 16,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__17",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "nfiguring MCP servers and other developer features.\nClick the \"Edit Config\" button to open the configuration file:\n\n\n ![\"Develop",](\"https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-developer.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=0fb595490a2f9e15c0301e771a57446c\")
\n\n\nThis action creates a new configuration file if one d",
"chunk_index": 22,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__23",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "s action creates a new configuration file if one doesn't exist, or opens your existing configuration. The file is located at:\n\n* **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n* **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n Replace the contents of the con",
"chunk_index": 23,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__24",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "top_config.json`\n\n Replace the contents of the configuration file with the following JSON structure. This configuration tells Claude Desktop to start the Filesystem Server with access to specific directories:\n\n ```json macOS theme={null}\n {\n \"mcpServers\": {\n \"filesystem\": {\n \"command\": \"n",
"chunk_index": 24,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__25",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "{\n \"mcpServers\": {\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@modelcontextprotocol/server-filesystem\",\n \"/Users/username/Desktop\",\n \"/Users/username/Downloads\"\n ]\n }\n }\n }\n ```\n\n ```json Windows theme={null}\n {\n \"mcpServers\": {\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@m",
"chunk_index": 25,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__26",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "stem\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@modelcontextprotocol/server-filesystem\",\n \"C:\\\\Users\\\\username\\\\Desktop\",\n \"C:\\\\Users\\\\username\\\\Downloads\"\n ]\n }\n }\n }\n ```\n\n\nReplace `username` with your actual computer username. The paths listed in the `args` array specify which direct",
"chunk_index": 26,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__27",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "hs listed in the `args` array specify which directories the Filesystem Server can access. You can modify these paths or add additional directories as needed.\n\n\n **Understanding the Configuration**\n\n * `\"filesystem\"`: A friendly name for the server that appears in Claude Desktop\n * `\"command\": \"",
"chunk_index": 27,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__28",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "er that appears in Claude Desktop\n * `\"command\": \"npx\"`: Uses Node.js's npx tool to run the server\n * `\"-y\"`: Automatically confirms the installation of the server package\n * `\"@modelcontextprotocol/server-filesystem\"`: The package name of the Filesystem Server\n * The remaining arguments: Directorie",
"chunk_index": 28,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__29",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "stem Server\n * The remaining arguments: Directories the server is allowed to access\n\n\n\n **Security Consideration**\n\n Only grant access to directories you're comfortable with Claude reading and modifying. The server runs with your user account permissions, so it can perform any file op",
"chunk_index": 29,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__30",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "account permissions, so it can perform any file operations you can perform manually.\n\n\n After saving the configuration file, completely quit Claude Desktop and restart it. The application needs to restart to load the new configuration and start the MCP server.\nUpon successful restart, you'",
"chunk_index": 30,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__31",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "tart the MCP server.\nUpon successful restart, you'll see an MCP server indicator ![](\"https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/claude-desktop-mcp-slider.svg?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=2742ec3fb97067e8591e68546c90221e\")
in the bottom-right corner of the conversation input box:\n\n\n <",
"chunk_index": 36,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__37",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "corner of the conversation input box:\n\n\n ![\"Claude](\"https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-slider.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=f80a38b720fc0519079bae26e2aae312\")
\n\n\nClick on this indicator to view the available tools provided by the Filesystem Server:\n\n\n ![](\"https:",)
\n ![\"Available](\"https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-tools.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=18f045f27f31f40896d3710ce9a4a0a0\")
\n\n\nIf the server indicator doesn't appear, refer to the [Troubleshooting](#troubleshooting) section for debugging steps.\n\nUsing the Filesystem Server\nWith the Filesystem Server connected, Claude",
"chunk_index": 48,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__49",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "rver\nWith the Filesystem Server connected, Claude can now interact with your file system. Try these example requests to explore the capabilities:\nFile Management Examples\n\n\"Can you write a poem and save it to my desktop?\" - Claude will compose a poem and create a new text file on your desktop\n\"What",
"chunk_index": 49,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__50",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "and create a new text file on your desktop\n\"What work-related files are in my downloads folder?\" - Claude will scan your downloads and identify work-related documents\n\"Please organize all images on my desktop into a new folder called 'Images'\" - Claude will create a folder and move image files into",
"chunk_index": 50,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__51",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "ude will create a folder and move image files into it\n\nHow Approval Works\nBefore executing any file system operation, Claude will request your approval. This ensures you maintain control over all actions:\n\nReview each request carefully before approving. You can always deny a request if you're not co",
"chunk_index": 51,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__52",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "ng. You can always deny a request if you're not comfortable with the proposed action.\nTroubleshooting\nIf you encounter issues setting up or using the Filesystem Server, these solutions address common problems:\n\n 1. Restart Claude Desktop completely\n 2. Check your claude_desktop_config.json file synt",
"chunk_index": 52,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__53",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "2. Check your claude_desktop_config.json file syntax\n 3. Make sure the file paths included in claude_desktop_config.json are valid and that they are absolute and not relative\n 4. Look at logs to see why the server is not connecting\n 5. In your command line, try manually running the server (replacing",
"chunk_index": 53,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__54",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "d line, try manually running the server (replacing username as you did in claude_desktop_config.json) to see if you get any errors:\n\n ```bash macOS/Linux theme={null}\n npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads\n ```\n\n ```powershell Win",
"chunk_index": 54,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__55",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "/Users/username/Downloads\n ```\n\n ```powershell Windows theme={null}\n npx -y @modelcontextprotocol/server-filesystem C:\\Users\\username\\Desktop C:\\Users\\username\\Downloads\n ```\n\n\n Claude.app logging related to MCP is written to log files in:\n* macOS: `~/Library/Logs/Claude`\n\n* Windows: `%A",
"chunk_index": 55,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__56",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": ":\n* macOS: `~/Library/Logs/Claude`\n\n* Windows: `%APPDATA%\\Claude\\logs`\n\n* `mcp.log` will contain general logging about MCP connections and connection failures.\n\n* Files named `mcp-server-SERVERNAME.log` will contain error (stderr) logging from the named server.\n\nYou can run the following command to",
"chunk_index": 56,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__57",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "med server.\n\nYou can run the following command to list recent logs and follow along with any new ones (on Windows, it will only show recent logs):\n\n\n ```bash macOS/Linux theme={null}\n tail -n 20 -f ~/Library/Logs/Claude/mcp*.log\n ```\n\n ```powershell Windows theme={null}\n type \"%APPDATA%\\C",
"chunk_index": 57,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__58",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "powershell Windows theme={null}\n type \"%APPDATA%\\Claude\\logs\\mcp*.log\"\n ```\n\n\n If Claude attempts to use the tools but they fail:\n1. Check Claude's logs for errors\n2. Verify your server builds and runs without errors\n3. Try restarting Claude Desktop\n\n Please refer to our debugging guide",
"chunk_index": 58,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__59",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "ude Desktop\n\n Please refer to our debugging guide for better debugging tools and more detailed guidance.\n \n\n 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 cla",
"chunk_index": 59,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__60",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "expanded value of %APPDATA% to your env key in claude_desktop_config.json:\n```json theme={null}\n{\n \"brave-search\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-brave-search\"],\n \"env\": {\n \"APPDATA\": \"C:\\\\Users\\\\user\\\\AppData\\\\Roaming\\\\\",\n \"BRAVE_API_KEY\": \"...\"\n }\n }\n}\n```\n\nWith",
"chunk_index": 60,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__61",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "ming\\\\\",\n \"BRAVE_API_KEY\": \"...\"\n }\n }\n}\n```\n\nWith this change in place, launch Claude Desktop once again.\n\n\n **NPM should be installed globally**\n\n The `npx` command may continue to fail if you have not installed NPM globally. If NPM is already installed globally, you will find `%APPDATA%\\",
"chunk_index": 61,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__62",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "eady installed globally, you will find `%APPDATA%\\npm` exists on your system. If not, you can install NPM globally by running the following command:\n\n ```bash theme={null}\n npm install -g npm\n ```\n\n\nNext Steps\nNow that you've successfully connected Claude Desktop to a local MCP server, exp",
"chunk_index": 62,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__63",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "onnected Claude Desktop to a local MCP server, explore these options to expand your setup:\n\n Browse our collection of official and community-created MCP servers for\n additional capabilities\n \n\n Create custom MCP servers tailored to your specific workflows and\n integrations\n \n\n Learn how to connect C",
"chunk_index": 63,
"total_chunks": 65
},
{
"chunk_id": "md_connect-local-servers_a1bf61de__64",
"doc_id": "md_connect-local-servers_a1bf61de",
"title": "Connect to local MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-local-servers.md",
"filename": "connect-local-servers.md",
"file_path": "connect-local-servers.md",
"updated_at": "1760788520.8599238",
"text": "flows and\n integrations\n \n\n Learn how to connect Claude to remote MCP servers for cloud-based tools and\n services\n \n\n Dive deeper into how MCP works and its architecture",
"chunk_index": 64,
"total_chunks": 65
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__0",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "Connect to remote MCP Servers\n\nLearn how to connect Claude to remote MCP servers and extend its capabilities with internet-hosted tools and data sources\n\nRemote MCP servers extend AI applications' capabilities beyond your local environment, providing access to internet-hosted tools, services, and da",
"chunk_index": 0,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__1",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "access to internet-hosted tools, services, and data sources. By connecting to remote MCP servers, you transform AI assistants from helpful tools into informed teammates capable of handling complex, multi-step projects with real-time access to external resources.\nMany clients now support remote MCP",
"chunk_index": 1,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__2",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "al resources.\nMany clients now support remote MCP servers, enabling a wide range of integration possibilities. This guide demonstrates how to connect to remote MCP servers using Claude as an example, one of the many clients that support MCP. While we focus on Claude's implementation through Custom C",
"chunk_index": 2,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__3",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "focus on Claude's implementation through Custom Connectors, the concepts apply broadly to other MCP-compatible clients.\nUnderstanding Remote MCP Servers\nRemote MCP servers function similarly to local MCP servers but are hosted on the internet rather than your local machine. They expose tools, promp",
"chunk_index": 3,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__4",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "than your local machine. They expose tools, prompts, and resources that Claude can use to perform tasks on your behalf. These servers can integrate with various services such as project management tools, documentation systems, code repositories, and any other API-enabled service.\nThe key advantage",
"chunk_index": 4,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__5",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "any other API-enabled service.\nThe key advantage of remote MCP servers is their accessibility. Unlike local servers that require installation and configuration on each device, remote servers are available from any MCP client with an internet connection. This makes them ideal for web-based AI applic",
"chunk_index": 5,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__6",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "ion. This makes them ideal for web-based AI applications, integrations that emphasize ease-of-use and services that require server-side processing or authentication.\nWhat are Custom Connectors?\nCustom Connectors serve as the bridge between Claude and remote MCP servers. They allow you to connect Cla",
"chunk_index": 6,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__7",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "remote MCP servers. They allow you to connect Claude directly to the tools and data sources that matter most to your workflows, enabling Claude to operate within your favorite software and draw insights from the complete context of your external tools.\nWith Custom Connectors, you can:\n\nConnect Clau",
"chunk_index": 7,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__8",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "ls.\nWith Custom Connectors, you can:\n\nConnect Claude to existing remote MCP servers provided by third-party developers\nBuild your own remote MCP servers to connect with any tool\n\nConnecting to a Remote MCP Server\nThe process of connecting Claude to a remote MCP server involves adding a Custom Connec",
"chunk_index": 8,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__9",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "remote MCP server involves adding a Custom Connector through the Claude interface. This establishes a secure connection between Claude and your chosen remote server.\n\n Open Claude in your browser and navigate to the settings page. You can access this by clicking on your profile icon and selecting \"",
"chunk_index": 9,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__10",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "s by clicking on your profile icon and selecting \"Settings\" from the dropdown menu. Once in settings, locate and click on the \"Connectors\" section in the sidebar.\nThis will display your currently configured connectors and provide options to add new ones.\n\n In the Connectors section, scroll to the bo",
"chunk_index": 10,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__11",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "nes.\n\n In the Connectors section, scroll to the bottom where you'll find the \"Add custom connector\" button. Click this button to begin the connection process.\n\n ![\"Add](\"https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-remote/1-add-connector.png?fit=max&auto=format&n=4ZXF1PrDkEaJvX",)
\n\n\nA dialog will appear prompting you to enter the remote MCP server URL. This URL should be provided by the server developer or administrator. Enter the comp",
"chunk_index": 17,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__18",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "server developer or administrator. Enter the complete URL, ensuring it includes the proper protocol (https\\://) and any necessary path components.\n\n\n ![\"Dialog](\"https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-remote/2-connect.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=0934f1",)
\n\n\nAfter entering the URL, click \"Add\" to proceed with the connection.\n\n Most remote MCP servers require authentication to ensure secure access to their resources. The authentication process varies depending on the server",
"chunk_index": 24,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__25",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "hentication process varies depending on the server implementation but commonly involves OAuth, API keys, or username/password combinations.\n\n ![\"Authentication](\"https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-remote/3-auth.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=89af6e1b8571863723",)
\n\n\nF",
"chunk_index": 30,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__31",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "70901a76a3209267b2078f9f8011 2500w\" />\n\n\nFollow the authentication prompts provided by the server. This may redirect you to a third-party authentication provider or display a form within Claude. Once authentication is complete, Claude will establish a secure connection to the remote server.",
"chunk_index": 31,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__32",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "tablish a secure connection to the remote server.\n\n After successful connection, the remote server's resources and prompts become available in your Claude conversations. You can access these by clicking the paperclip icon in the message input area, which opens the attachment menu.\n\n 
\n ![\"Attachment](\"https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-remote/4-select-resources-menu.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=ecc6234b0fe5625e24cc2b02b7893c67\")
\n\n\nThe menu displays all available resources and prompts from your connected servers. Select the items you want to include in your conversation. These resources provide Claude with context and information from your external to",
"chunk_index": 39,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__40",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "with context and information from your external tools.\n\n\n ![\"Selecting](\"https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-remote/5-select-prompts-resources.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=30c522540c7ff5abd8617d20b329eca2\")
\n\n\n Remote MCP servers often expose multiple tools with varying capabilities. You can control which tools Claude is allowed to use by configuring permissions in the co",
"chunk_index": 46,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__47",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "llowed to use by configuring permissions in the connector settings. This ensures Claude only performs actions you've explicitly authorized.\n\n ![\"Tool](\"https://mintcdn.com/mcp/4ZXF1PrDkEaJvXpn/images/quickstart-remote/6-configure-tools.png?fit=max&auto=format&n=4ZXF1PrDkEaJvXpn&q=85&s=1e55fd2",)
\n\n\nNavigate back to the Connectors settings and click on your connected server. Here you can enable or disable specific tools, set usage limits, and configure other secur",
"chunk_index": 53,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__54",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "tools, set usage limits, and configure other security parameters according to your needs.\n\nBest Practices for Using Remote MCP Servers\nWhen working with remote MCP servers, consider these recommendations to ensure a secure and efficient experience:\nSecurity considerations: Always verify the authenti",
"chunk_index": 54,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__55",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "ecurity considerations: Always verify the authenticity of remote MCP servers before connecting. Only connect to servers from trusted sources, and review the permissions requested during authentication. Be cautious about granting access to sensitive data or systems.\nManaging multiple connectors: You",
"chunk_index": 55,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__56",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "ata or systems.\nManaging multiple connectors: You can connect to multiple remote MCP servers simultaneously. Organize your connectors by purpose or project to maintain clarity. Regularly review and remove connectors you no longer use to keep your workspace organized and secure.\nNext Steps\nNow that y",
"chunk_index": 56,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__57",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "kspace organized and secure.\nNext Steps\nNow that you've connected Claude to a remote MCP server, you can explore its capabilities in your conversations. Try using the connected tools to automate tasks, access external data, or integrate with your existing workflows.\n\n Create custom remote MCP server",
"chunk_index": 57,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__58",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "sting workflows.\n\n Create custom remote MCP servers to integrate with proprietary tools and\n services\n \n\n Browse our collection of official and community-created MCP servers\n \n\n Learn how to connect Claude Desktop to local MCP servers for direct system\n access\n \n\n Dive deeper into how MCP works and",
"chunk_index": 58,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__59",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "em\n access\n \n\n Dive deeper into how MCP works and its architecture\n \n\nRemote MCP servers unlock powerful possibilities for extending Claude's capabilities. As you become familiar with these integrations, you'll discover new ways to streamline your workflows and accomplish complex tasks more efficien",
"chunk_index": 59,
"total_chunks": 61
},
{
"chunk_id": "md_connect-remote-servers_30c418e6__60",
"doc_id": "md_connect-remote-servers_30c418e6",
"title": "Connect to remote MCP Servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\connect-remote-servers.md",
"filename": "connect-remote-servers.md",
"file_path": "connect-remote-servers.md",
"updated_at": "1760788520.8599238",
"text": "rkflows and accomplish complex tasks more efficiently.",
"chunk_index": 60,
"total_chunks": 61
},
{
"chunk_id": "md_DEPLOYMENT_2fc501e0__0",
"doc_id": "md_DEPLOYMENT_2fc501e0",
"title": "Deployment Guide for MCP Documentation Server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\DEPLOYMENT.md",
"filename": "DEPLOYMENT.md",
"file_path": "DEPLOYMENT.md",
"updated_at": "1760792472.636914",
"text": "Deployment Guide for MCP Documentation Server\nPrerequisites\n\nHugging Face Account: Create an account at huggingface.co\nGit: Ensure Git is installed on your system\nDocker: Required for local testing (optional)\n\nStep 1: Create Hugging Face Space\n\nGo to Hugging Face Spaces\nClick \"Create new Space\"\nFill",
"chunk_index": 0,
"total_chunks": 10
},
{
"chunk_id": "md_DEPLOYMENT_2fc501e0__1",
"doc_id": "md_DEPLOYMENT_2fc501e0",
"title": "Deployment Guide for MCP Documentation Server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\DEPLOYMENT.md",
"filename": "DEPLOYMENT.md",
"file_path": "DEPLOYMENT.md",
"updated_at": "1760792472.636914",
"text": "Hugging Face Spaces\nClick \"Create new Space\"\nFill in the details:\nSpace name: mcp-docs-server (or your preferred name)\nLicense: MIT\nSDK: Docker\nHardware: CPU Basic (free tier)\nVisibility: Public or Private\n\nStep 2: Clone and Setup\n```bash\nClone your space (replace with your username)\ngit clone http",
"chunk_index": 1,
"total_chunks": 10
},
{
"chunk_id": "md_DEPLOYMENT_2fc501e0__2",
"doc_id": "md_DEPLOYMENT_2fc501e0",
"title": "Deployment Guide for MCP Documentation Server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\DEPLOYMENT.md",
"filename": "DEPLOYMENT.md",
"file_path": "DEPLOYMENT.md",
"updated_at": "1760792472.636914",
"text": "space (replace with your username)\ngit clone https://huggingface.co/spaces/YOUR_USERNAME/mcp-docs-server\ncd mcp-docs-server\nCopy all files from this directory to the cloned space\n(Copy all files from mcp-docs-hf-space/ to the cloned directory)\n```\nStep 3: Test Locally (Optional)\n```bash\nInstall dep",
"chunk_index": 2,
"total_chunks": 10
},
{
"chunk_id": "md_DEPLOYMENT_2fc501e0__3",
"doc_id": "md_DEPLOYMENT_2fc501e0",
"title": "Deployment Guide for MCP Documentation Server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\DEPLOYMENT.md",
"filename": "DEPLOYMENT.md",
"file_path": "DEPLOYMENT.md",
"updated_at": "1760792472.636914",
"text": "tep 3: Test Locally (Optional)\n```bash\nInstall dependencies\npip install -r requirements.txt\nTest the application\npython test_app.py\nRun the server locally\npython app.py\n```\nStep 4: Deploy to Hugging Face\n```bash\nAdd all files to git\ngit add .\nCommit changes\ngit commit -m \"Initial MCP Documentation S",
"chunk_index": 3,
"total_chunks": 10
},
{
"chunk_id": "md_DEPLOYMENT_2fc501e0__4",
"doc_id": "md_DEPLOYMENT_2fc501e0",
"title": "Deployment Guide for MCP Documentation Server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\DEPLOYMENT.md",
"filename": "DEPLOYMENT.md",
"file_path": "DEPLOYMENT.md",
"updated_at": "1760792472.636914",
"text": "changes\ngit commit -m \"Initial MCP Documentation Server deployment\"\nPush to Hugging Face\ngit push origin main\n```\nStep 5: Verify Deployment\n\nGo to your Space URL: https://huggingface.co/spaces/YOUR_USERNAME/mcp-docs-server\nWait for the build to complete (usually 2-5 minutes)\nTest the API endpoints:",
"chunk_index": 4,
"total_chunks": 10
},
{
"chunk_id": "md_DEPLOYMENT_2fc501e0__5",
"doc_id": "md_DEPLOYMENT_2fc501e0",
"title": "Deployment Guide for MCP Documentation Server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\DEPLOYMENT.md",
"filename": "DEPLOYMENT.md",
"file_path": "DEPLOYMENT.md",
"updated_at": "1760792472.636914",
"text": "ete (usually 2-5 minutes)\nTest the API endpoints:\nGET / - Health check\nPOST /search - Search documentation\n\nAPI Usage Examples\nHealth Check\nbash\ncurl https://YOUR_SPACE_URL.hf.space/\nSearch Documentation\nbash\ncurl -X POST \"https://YOUR_SPACE_URL.hf.space/search\" \\\n -H \"Content-Type: application/json",
"chunk_index": 5,
"total_chunks": 10
},
{
"chunk_id": "md_DEPLOYMENT_2fc501e0__6",
"doc_id": "md_DEPLOYMENT_2fc501e0",
"title": "Deployment Guide for MCP Documentation Server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\DEPLOYMENT.md",
"filename": "DEPLOYMENT.md",
"file_path": "DEPLOYMENT.md",
"updated_at": "1760792472.636914",
"text": "pace/search\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"query\": \"MCP architecture\", \"limit\": 5}'\nGet Specific Chunk\nbash\ncurl \"https://YOUR_SPACE_URL.hf.space/chunks/md_architecture_b82bfe7e__0\"\nTroubleshooting\nBuild Failures\n\nCheck the logs in the Hugging Face Space interface\nEnsure all files",
"chunk_index": 6,
"total_chunks": 10
},
{
"chunk_id": "md_DEPLOYMENT_2fc501e0__7",
"doc_id": "md_DEPLOYMENT_2fc501e0",
"title": "Deployment Guide for MCP Documentation Server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\DEPLOYMENT.md",
"filename": "DEPLOYMENT.md",
"file_path": "DEPLOYMENT.md",
"updated_at": "1760792472.636914",
"text": "the Hugging Face Space interface\nEnsure all files are properly committed\nVerify the Dockerfile syntax\n\nRuntime Errors\n\nCheck the application logs\nVerify all data files are present\nTest locally first\n\nPerformance Issues\n\nConsider upgrading to a paid tier for better performance\nOptimize the search alg",
"chunk_index": 7,
"total_chunks": 10
},
{
"chunk_id": "md_DEPLOYMENT_2fc501e0__8",
"doc_id": "md_DEPLOYMENT_2fc501e0",
"title": "Deployment Guide for MCP Documentation Server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\DEPLOYMENT.md",
"filename": "DEPLOYMENT.md",
"file_path": "DEPLOYMENT.md",
"updated_at": "1760792472.636914",
"text": "ier for better performance\nOptimize the search algorithm if needed\n\nNext Steps\n\nIntegrate with MCP Clients: Use this server as a data source for MCP clients\nAdd Authentication: Implement API keys or OAuth if needed\nEnhance Search: Implement semantic search using the FAISS index\nAdd More Features: Im",
"chunk_index": 8,
"total_chunks": 10
},
{
"chunk_id": "md_DEPLOYMENT_2fc501e0__9",
"doc_id": "md_DEPLOYMENT_2fc501e0",
"title": "Deployment Guide for MCP Documentation Server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\DEPLOYMENT.md",
"filename": "DEPLOYMENT.md",
"file_path": "DEPLOYMENT.md",
"updated_at": "1760792472.636914",
"text": "search using the FAISS index\nAdd More Features: Implement additional endpoints as needed\n\nSupport\nFor issues or questions:\n1. Check the Hugging Face Space logs\n2. Review the application code\n3. Test locally first\n4. Check the Hugging Face Spaces documentation",
"chunk_index": 9,
"total_chunks": 10
},
{
"chunk_id": "md_inspector_e7fdfbe6__0",
"doc_id": "md_inspector_e7fdfbe6",
"title": "MCP Inspector",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\inspector.md",
"filename": "inspector.md",
"file_path": "inspector.md",
"updated_at": "1760788520.8554032",
"text": "MCP Inspector\n\nIn-depth guide to using the MCP Inspector for testing and debugging Model Context Protocol servers\n\nThe MCP Inspector is an interactive developer tool for testing and debugging MCP servers. While the Debugging Guide covers the Inspector as part of the overall debugging toolkit, this d",
"chunk_index": 0,
"total_chunks": 12
},
{
"chunk_id": "md_inspector_e7fdfbe6__1",
"doc_id": "md_inspector_e7fdfbe6",
"title": "MCP Inspector",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\inspector.md",
"filename": "inspector.md",
"file_path": "inspector.md",
"updated_at": "1760788520.8554032",
"text": "r as part of the overall debugging toolkit, this document provides a detailed exploration of the Inspector's features and capabilities.\nGetting started\nInstallation and basic usage\nThe Inspector runs directly through npx without requiring installation:\nbash theme={null}\nnpx @modelcontextprotocol/ins",
"chunk_index": 1,
"total_chunks": 12
},
{
"chunk_id": "md_inspector_e7fdfbe6__2",
"doc_id": "md_inspector_e7fdfbe6",
"title": "MCP Inspector",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\inspector.md",
"filename": "inspector.md",
"file_path": "inspector.md",
"updated_at": "1760788520.8554032",
"text": "n:\nbash theme={null}\nnpx @modelcontextprotocol/inspector \nbash theme={null}\nnpx @modelcontextprotocol/inspector \nInspecting servers from NPM or PyPi\nA common way to start server packages from NPM or PyPi.\n\nbash theme={null}\n npx -y @modelcontextprotocol/inspector npx",
"chunk_index": 2,
"total_chunks": 12
},
{
"chunk_id": "md_inspector_e7fdfbe6__3",
"doc_id": "md_inspector_e7fdfbe6",
"title": "MCP Inspector",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\inspector.md",
"filename": "inspector.md",
"file_path": "inspector.md",
"updated_at": "1760788520.8554032",
"text": "null}\n npx -y @modelcontextprotocol/inspector npx \n # For example\n npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem /Users/username/Desktop\n\nbash theme={null}\n npx @modelcontextprotocol/inspector uvx \n # For example\n npx @mo",
"chunk_index": 3,
"total_chunks": 12
},
{
"chunk_id": "md_inspector_e7fdfbe6__4",
"doc_id": "md_inspector_e7fdfbe6",
"title": "MCP Inspector",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\inspector.md",
"filename": "inspector.md",
"file_path": "inspector.md",
"updated_at": "1760788520.8554032",
"text": "uvx \n # For example\n npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git\n\nInspecting locally developed servers\nTo inspect servers locally developed or downloaded as a repository, the most common\nway is:\n\nbash theme={null}\n npx @modelcontex",
"chunk_index": 4,
"total_chunks": 12
},
{
"chunk_id": "md_inspector_e7fdfbe6__5",
"doc_id": "md_inspector_e7fdfbe6",
"title": "MCP Inspector",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\inspector.md",
"filename": "inspector.md",
"file_path": "inspector.md",
"updated_at": "1760788520.8554032",
"text": "ommon\nway is:\n\nbash theme={null}\n npx @modelcontextprotocol/inspector node path/to/server/index.js args...\n\nbash theme={null}\n npx @modelcontextprotocol/inspector \\\n uv \\\n --directory path/to/server \\\n run \\\n package-name \\\n args...\n\nPlease carefully read any attached README for the most accurate in",
"chunk_index": 5,
"total_chunks": 12
},
{
"chunk_id": "md_inspector_e7fdfbe6__6",
"doc_id": "md_inspector_e7fdfbe6",
"title": "MCP Inspector",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\inspector.md",
"filename": "inspector.md",
"file_path": "inspector.md",
"updated_at": "1760788520.8554032",
"text": "read any attached README for the most accurate instructions.\nFeature overview\n\nThe Inspector provides several features for interacting with your MCP server:\nServer connection pane\n\nAllows selecting the transport for connecting to the server\nFor local servers, supports customizing the command-line a",
"chunk_index": 6,
"total_chunks": 12
},
{
"chunk_id": "md_inspector_e7fdfbe6__7",
"doc_id": "md_inspector_e7fdfbe6",
"title": "MCP Inspector",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\inspector.md",
"filename": "inspector.md",
"file_path": "inspector.md",
"updated_at": "1760788520.8554032",
"text": "l servers, supports customizing the command-line arguments and environment\n\nResources tab\n\nLists all available resources\nShows resource metadata (MIME types, descriptions)\nAllows resource content inspection\nSupports subscription testing\n\nPrompts tab\n\nDisplays available prompt templates\nShows prompt",
"chunk_index": 7,
"total_chunks": 12
},
{
"chunk_id": "md_inspector_e7fdfbe6__8",
"doc_id": "md_inspector_e7fdfbe6",
"title": "MCP Inspector",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\inspector.md",
"filename": "inspector.md",
"file_path": "inspector.md",
"updated_at": "1760788520.8554032",
"text": "Displays available prompt templates\nShows prompt arguments and descriptions\nEnables prompt testing with custom arguments\nPreviews generated messages\n\nTools tab\n\nLists available tools\nShows tool schemas and descriptions\nEnables tool testing with custom inputs\nDisplays tool execution results\n\nNotific",
"chunk_index": 8,
"total_chunks": 12
},
{
"chunk_id": "md_inspector_e7fdfbe6__9",
"doc_id": "md_inspector_e7fdfbe6",
"title": "MCP Inspector",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\inspector.md",
"filename": "inspector.md",
"file_path": "inspector.md",
"updated_at": "1760788520.8554032",
"text": "om inputs\nDisplays tool execution results\n\nNotifications pane\n\nPresents all logs recorded from the server\nShows notifications received from the server\n\nBest practices\nDevelopment workflow\n\nStart Development\nLaunch Inspector with your server\nVerify basic connectivity\n\nCheck capability negotiation\n\nIt",
"chunk_index": 9,
"total_chunks": 12
},
{
"chunk_id": "md_inspector_e7fdfbe6__10",
"doc_id": "md_inspector_e7fdfbe6",
"title": "MCP Inspector",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\inspector.md",
"filename": "inspector.md",
"file_path": "inspector.md",
"updated_at": "1760788520.8554032",
"text": "sic connectivity\n\nCheck capability negotiation\n\nIterative testing\n\nMake server changes\nRebuild the server\nReconnect the Inspector\nTest affected features\n\nMonitor messages\n\nTest edge cases\n\nInvalid inputs\nMissing prompt arguments\nConcurrent operations\nVerify error handling and error responses\n\nNext s",
"chunk_index": 10,
"total_chunks": 12
},
{
"chunk_id": "md_inspector_e7fdfbe6__11",
"doc_id": "md_inspector_e7fdfbe6",
"title": "MCP Inspector",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\inspector.md",
"filename": "inspector.md",
"file_path": "inspector.md",
"updated_at": "1760788520.8554032",
"text": "Verify error handling and error responses\n\nNext steps\n\n Check out the MCP Inspector source code\n \n\n Learn about broader debugging strategies",
"chunk_index": 11,
"total_chunks": 12
},
{
"chunk_id": "md_intro_96f49227__0",
"doc_id": "md_intro_96f49227",
"title": "What is the Model Context Protocol (MCP)?",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\intro.md",
"filename": "intro.md",
"file_path": "intro.md",
"updated_at": "1760788413.1773403",
"text": "What is the Model Context Protocol (MCP)?\nMCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems.\nUsing MCP, AI applications like Claude or ChatGPT can connect to data sources (e.g. local files, databases), tools (e.g. search engines, calculators)",
"chunk_index": 0,
"total_chunks": 7
},
{
"chunk_id": "md_intro_96f49227__1",
"doc_id": "md_intro_96f49227",
"title": "What is the Model Context Protocol (MCP)?",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\intro.md",
"filename": "intro.md",
"file_path": "intro.md",
"updated_at": "1760788413.1773403",
"text": "abases), tools (e.g. search engines, calculators) and workflows (e.g. specialized prompts)—enabling them to access key information and perform tasks.\nThink of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect electronic devices, MCP provides a standardiz",
"chunk_index": 1,
"total_chunks": 7
},
{
"chunk_id": "md_intro_96f49227__2",
"doc_id": "md_intro_96f49227",
"title": "What is the Model Context Protocol (MCP)?",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\intro.md",
"filename": "intro.md",
"file_path": "intro.md",
"updated_at": "1760788413.1773403",
"text": "nect electronic devices, MCP provides a standardized way to connect AI applications to external systems.\n\nWhat can MCP enable?\n\nAgents can access your Google Calendar and Notion, acting as a more personalized AI assistant.\nClaude Code can generate an entire web app using a Figma design.\nEnterprise c",
"chunk_index": 2,
"total_chunks": 7
},
{
"chunk_id": "md_intro_96f49227__3",
"doc_id": "md_intro_96f49227",
"title": "What is the Model Context Protocol (MCP)?",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\intro.md",
"filename": "intro.md",
"file_path": "intro.md",
"updated_at": "1760788413.1773403",
"text": "entire web app using a Figma design.\nEnterprise chatbots can connect to multiple databases across an organization, empowering users to analyze data using chat.\nAI models can create 3D designs on Blender and print them out using a 3D printer.\n\nWhy does MCP matter?\nDepending on where you sit in the e",
"chunk_index": 3,
"total_chunks": 7
},
{
"chunk_id": "md_intro_96f49227__4",
"doc_id": "md_intro_96f49227",
"title": "What is the Model Context Protocol (MCP)?",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\intro.md",
"filename": "intro.md",
"file_path": "intro.md",
"updated_at": "1760788413.1773403",
"text": "es MCP matter?\nDepending on where you sit in the ecosystem, MCP can have a range of benefits.\n\nDevelopers: MCP reduces development time and complexity when building, or integrating with, an AI application or agent.\nAI applications or agents: MCP provides access to an ecosystem of data sources, tools",
"chunk_index": 4,
"total_chunks": 7
},
{
"chunk_id": "md_intro_96f49227__5",
"doc_id": "md_intro_96f49227",
"title": "What is the Model Context Protocol (MCP)?",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\intro.md",
"filename": "intro.md",
"file_path": "intro.md",
"updated_at": "1760788413.1773403",
"text": "ides access to an ecosystem of data sources, tools and apps which will enhance capabilities and improve the end-user experience.\nEnd-users: MCP results in more capable AI applications or agents which can access your data and take actions on your behalf when necessary.\n\nStart Building\n\n Create MCP se",
"chunk_index": 5,
"total_chunks": 7
},
{
"chunk_id": "md_intro_96f49227__6",
"doc_id": "md_intro_96f49227",
"title": "What is the Model Context Protocol (MCP)?",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\intro.md",
"filename": "intro.md",
"file_path": "intro.md",
"updated_at": "1760788413.1773403",
"text": "lf when necessary.\n\nStart Building\n\n Create MCP servers to expose your data and tools\n \n\n Develop applications that connect to MCP servers\n \n\nLearn more\n\n Learn the core concepts and architecture of MCP",
"chunk_index": 6,
"total_chunks": 7
},
{
"chunk_id": "md_README_8ec9a00b__0",
"doc_id": "md_README_8ec9a00b",
"title": "MCP Documentation Server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\README.md",
"filename": "README.md",
"file_path": "README.md",
"updated_at": "1760792472.628915",
"text": "MCP Documentation Server\nThis Hugging Face Space hosts an MCP (Model Context Protocol) server that provides access to MCP documentation through semantic search.\nFeatures\n\nSemantic search through MCP documentation\nRESTful API for accessing documentation chunks\nFAISS-based vector search capabilities",
"chunk_index": 0,
"total_chunks": 3
},
{
"chunk_id": "md_README_8ec9a00b__1",
"doc_id": "md_README_8ec9a00b",
"title": "MCP Documentation Server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\README.md",
"filename": "README.md",
"file_path": "README.md",
"updated_at": "1760792472.628915",
"text": "on chunks\nFAISS-based vector search capabilities\n\nAPI Endpoints\n\nGET / - Health check\nPOST /search - Search documentation chunks\nGET /chunks/{chunk_id} - Get specific chunk\nGET /docs - List all documents\n\nUsage\nSend a POST request to /search with:\njson\n{\n \"query\": \"your search query\",\n \"limit\": 5\n}",
"chunk_index": 1,
"total_chunks": 3
},
{
"chunk_id": "md_README_8ec9a00b__2",
"doc_id": "md_README_8ec9a00b",
"title": "MCP Documentation Server",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\README.md",
"filename": "README.md",
"file_path": "README.md",
"updated_at": "1760792472.628915",
"text": "on\n{\n \"query\": \"your search query\",\n \"limit\": 5\n}\nLocal Development\nTo run locally:\nbash\npip install -r requirements.txt\npython app.py\nDeployment\nThis space is configured to run on Hugging Face Spaces with Docker.",
"chunk_index": 2,
"total_chunks": 3
},
{
"chunk_id": "md_sdk_d1ddea8c__0",
"doc_id": "md_sdk_d1ddea8c",
"title": "SDKs",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\sdk.md",
"filename": "sdk.md",
"file_path": "sdk.md",
"updated_at": "1760788520.8554032",
"text": "SDKs\n\nOfficial SDKs for building with Model Context Protocol\n\nBuild MCP servers and clients using our official SDKs. All SDKs provide the same core functionality and full protocol support.\nAvailable SDKs\n\nGetting Started\nEach SDK provides the same functionality but follows the idioms and best practi",
"chunk_index": 0,
"total_chunks": 3
},
{
"chunk_id": "md_sdk_d1ddea8c__1",
"doc_id": "md_sdk_d1ddea8c",
"title": "SDKs",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\sdk.md",
"filename": "sdk.md",
"file_path": "sdk.md",
"updated_at": "1760788520.8554032",
"text": "nctionality but follows the idioms and best practices of its language. All SDKs support:\n\nCreating MCP servers that expose tools, resources, and prompts\nBuilding MCP clients that can connect to any MCP server\nLocal and remote transport protocols\nProtocol compliance with type safety\n\nVisit the SDK pa",
"chunk_index": 1,
"total_chunks": 3
},
{
"chunk_id": "md_sdk_d1ddea8c__2",
"doc_id": "md_sdk_d1ddea8c",
"title": "SDKs",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\sdk.md",
"filename": "sdk.md",
"file_path": "sdk.md",
"updated_at": "1760788520.8554032",
"text": "ocol compliance with type safety\n\nVisit the SDK page for your chosen language to find installation instructions, documentation, and examples.\nNext Steps\nReady to start building with MCP? Choose your path:\n\n Learn how to create your first MCP server\n \n\n Create applications that connect to MCP servers",
"chunk_index": 2,
"total_chunks": 3
},
{
"chunk_id": "md_server-concepts_b2e90da1__0",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "Understanding MCP servers\nMCP servers are programs that expose specific capabilities to AI applications through standardized protocol interfaces.\nCommon examples include file system servers for document access, database servers for data queries, GitHub servers for code management, Slack servers for",
"chunk_index": 0,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__1",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ub servers for code management, Slack servers for team communication, and calendar servers for scheduling.\nCore Server Features\nServers provide functionality through three building blocks:\n| Feature | Explanation | Examples | Who controls it |\n| ------------- | --------------------------------------",
"chunk_index": 1,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__2",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "--------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | --------------- |\n| Tools | Funct",
"chunk_index": 2,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__3",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "-------------- | --------------- |\n| Tools | Functions that your LLM can actively call, and decides when to use them based on user requests. Tools can write to databases, call external APIs, modify files, or trigger other logic. | Search flightsSend messagesCreate calendar events | Model |\n| Resourc",
"chunk_index": 3,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__4",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "messagesCreate calendar events | Model |\n| Resources | Passive data sources that provide read-only access to information for context, such as file contents, database schemas, or API documentation. | Retrieve documentsAccess knowledge basesRead calendars | Application |\n| Prompts | Pre-built instruct",
"chunk_index": 4,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__5",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ars | Application |\n| Prompts | Pre-built instruction templates that tell the model to work with specific tools and resources. | Plan a vacationSummarize my meetingsDraft an email | User |\nWe will use a hypothetical scenario to demonstrate the role of each of these features, and show how they can wo",
"chunk_index": 5,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__6",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "f each of these features, and show how they can work together.\nTools\nTools enable AI models to perform actions. Each tool defines a specific operation with typed inputs and outputs. The model requests tool execution based on context.\nHow Tools Work\nTools are schema-defined interfaces that LLMs can i",
"chunk_index": 6,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__7",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ools are schema-defined interfaces that LLMs can invoke. MCP uses JSON Schema for validation. Each tool performs a single operation with clearly defined inputs and outputs. Tools may require user consent prior to execution, helping to ensure users maintain control over actions taken by a model.\nProt",
"chunk_index": 7,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__8",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "intain control over actions taken by a model.\nProtocol operations:\n| Method | Purpose | Returns |\n| ------------ | ------------------------ | -------------------------------------- |\n| tools/list | Discover available tools | Array of tool definitions with schemas |\n| tools/call | Execute a specific",
"chunk_index": 8,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__9",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "with schemas |\n| tools/call | Execute a specific tool | Tool execution result |\nExample tool definition:\ntypescript theme={null}\n{\n name: \"searchFlights\",\n description: \"Search for available flights\",\n inputSchema: {\n type: \"object\",\n properties: {\n origin: { type: \"string\", description: \"Departure",
"chunk_index": 9,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__10",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "origin: { type: \"string\", description: \"Departure city\" },\n destination: { type: \"string\", description: \"Arrival city\" },\n date: { type: \"string\", format: \"date\", description: \"Travel date\" }\n },\n required: [\"origin\", \"destination\", \"date\"]\n }\n}\nExample: Travel Booking\nTools enable AI applications",
"chunk_index": 10,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__11",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "mple: Travel Booking\nTools enable AI applications to perform actions on behalf of users. In a travel planning scenario, the AI application might use several tools to help book a vacation:\nFlight Search\nsearchFlights(origin: \"NYC\", destination: \"Barcelona\", date: \"2024-06-15\")\nQueries multiple airlin",
"chunk_index": 11,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__12",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "lona\", date: \"2024-06-15\")\nQueries multiple airlines and returns structured flight options.\nCalendar Blocking\ncreateCalendarEvent(title: \"Barcelona Trip\", startDate: \"2024-06-15\", endDate: \"2024-06-22\")\nMarks the travel dates in the user's calendar.\nEmail notification\nsendEmail(to: \"team@work.com\",",
"chunk_index": 12,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__13",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "Email notification\nsendEmail(to: \"team@work.com\", subject: \"Out of Office\", body: \"...\")\nSends an automated out-of-office message to colleagues.\nUser Interaction Model\nTools are model-controlled, meaning AI models can discover and invoke them automatically. However, MCP emphasizes human oversight th",
"chunk_index": 13,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__14",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ically. However, MCP emphasizes human oversight through several mechanisms.\nFor trust and safety, applications can implement user control through various mechanisms, such as:\n\nDisplaying available tools in the UI, enabling users to define whether a tool should be made available in specific interacti",
"chunk_index": 14,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__15",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ool should be made available in specific interactions\nApproval dialogs for individual tool executions\nPermission settings for pre-approving certain safe operations\nActivity logs that show all tool executions with their results\n\nResources\nResources provide structured access to information that the AI",
"chunk_index": 15,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__16",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ovide structured access to information that the AI application can retrieve and provide to models as context.\nHow Resources Work\nResources expose data from files, APIs, databases, or any other source that an AI needs to understand context. Applications can access this information directly and decide",
"chunk_index": 16,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__17",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ns can access this information directly and decide how to use it - whether that's selecting relevant portions, searching with embeddings, or passing it all to the model.\nEach resource has a unique URI (like file:///path/to/document.md) and declares its MIME type for appropriate content handling. The",
"chunk_index": 17,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__18",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ts MIME type for appropriate content handling. They declare MIME types for appropriate content handling and support two discovery patterns:\n\nDirect Resources - fixed URIs that point to specific data. Example: calendar://events/2024 - returns calendar availability for 2024\nResource Templates - dynami",
"chunk_index": 18,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__19",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "availability for 2024\nResource Templates - dynamic URIs with parameters for flexible queries. Example:\ntravel://activities/{city}/{category} - returns activities by city and category\ntravel://activities/barcelona/museums - returns all museums in Barcelona\n\nResource Templates include metadata such a",
"chunk_index": 19,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__20",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "celona\n\nResource Templates include metadata such as title, description, and expected MIME type, making them discoverable and self-documenting.\nProtocol operations:\n| Method | Purpose | Returns |\n| -------------------------- | ------------------------------- | -------------------------------------- |",
"chunk_index": 20,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__21",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "------- | -------------------------------------- |\n| resources/list | List available direct resources | Array of resource descriptors |\n| resources/templates/list | Discover resource templates | Array of resource template definitions |\n| resources/read | Retrieve resource contents | Resource data wi",
"chunk_index": 21,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__22",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ad | Retrieve resource contents | Resource data with metadata |\n| resources/subscribe | Monitor resource changes | Subscription confirmation |\nExample: Getting Travel Planning Context\nContinuing with the travel planning example, resources provide the AI application with access to relevant informatio",
"chunk_index": 22,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__23",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "AI application with access to relevant information:\n\nCalendar data (calendar://events/2024) - Checks user availability\nTravel documents (file:///Documents/Travel/passport.pdf) - Accesses important documents\nPrevious itineraries (trips://history/barcelona-2023) - References past trips and preference",
"chunk_index": 23,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__24",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "elona-2023) - References past trips and preferences\n\nThe AI application retrieves these resources and decides how to process them, whether selecting a subset of data using embeddings or keyword search, or passing raw data directly to the model.\nIn this case, it provides calendar data, weather inform",
"chunk_index": 24,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__25",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "is case, it provides calendar data, weather information, and travel preferences to the model, enabling it to check availability, look up weather patterns, and reference past travel preferences.\nResource Template Examples:\n```json theme={null}\n{\n \"uriTemplate\": \"weather://forecast/{city}/{date}\",\n \"n",
"chunk_index": 25,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__26",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "Template\": \"weather://forecast/{city}/{date}\",\n \"name\": \"weather-forecast\",\n \"title\": \"Weather Forecast\",\n \"description\": \"Get weather forecast for any city and date\",\n \"mimeType\": \"application/json\"\n}\n{\n \"uriTemplate\": \"travel://flights/{origin}/{destination}\",\n \"name\": \"flight-search\",\n \"title\": \"",
"chunk_index": 26,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__27",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "stination}\",\n \"name\": \"flight-search\",\n \"title\": \"Flight Search\",\n \"description\": \"Search available flights between cities\",\n \"mimeType\": \"application/json\"\n}\n```\nThese templates enable flexible queries. For weather data, users can access forecasts for any city/date combination. For flights, they ca",
"chunk_index": 27,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__28",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "or any city/date combination. For flights, they can search routes between any two airports. When a user has input \"NYC\" as the origin airport and begins to input \"Bar\" as the destination airport, the system can suggest \"Barcelona (BCN)\" or \"Barbados (BGI)\".\nParameter Completion\nDynamic resources sup",
"chunk_index": 28,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__29",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "(BGI)\".\nParameter Completion\nDynamic resources support parameter completion. For example:\n\nTyping \"Par\" as input for weather://forecast/{city} might suggest \"Paris\" or \"Park City\"\nTyping \"JFK\" for flights://search/{airport} might suggest \"JFK - John F. Kennedy International\"\n\nThe system helps discov",
"chunk_index": 29,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__30",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "F. Kennedy International\"\n\nThe system helps discover valid values without requiring exact format knowledge.\nUser Interaction Model\nResources are application-driven, giving them flexibility in how they retrieve, process, and present available context. Common interaction patterns include:\n\nTree or lis",
"chunk_index": 30,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__31",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "Common interaction patterns include:\n\nTree or list views for browsing resources in familiar folder-like structures\nSearch and filter interfaces for finding specific resources\nAutomatic context inclusion or smart suggestions based on heuristics or AI selection\nManual or bulk selection interfaces for",
"chunk_index": 31,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__32",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "selection\nManual or bulk selection interfaces for including single or multiple resources\n\nApplications are free to implement resource discovery through any interface pattern that suits their needs. The protocol doesn't mandate specific UI patterns, allowing for resource pickers with preview capabil",
"chunk_index": 32,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__33",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "allowing for resource pickers with preview capabilities, smart suggestions based on current conversation context, bulk selection for including multiple resources, or integration with existing file browsers and data explorers.\nPrompts\nPrompts provide reusable templates. They allow MCP server authors",
"chunk_index": 33,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__34",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "reusable templates. They allow MCP server authors to provide parameterized prompts for a domain, or showcase how to best use the MCP server.\nHow Prompts Work\nPrompts are structured templates that define expected inputs and interaction patterns. They are user-controlled, requiring explicit invocation",
"chunk_index": 34,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__35",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "are user-controlled, requiring explicit invocation rather than automatic triggering. Prompts can be context-aware, referencing available resources and tools to create comprehensive workflows. Similar to resources, prompts support parameter completion to help users discover valid argument values.\nPro",
"chunk_index": 35,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__36",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "to help users discover valid argument values.\nProtocol operations:\n| Method | Purpose | Returns |\n| -------------- | -------------------------- | ------------------------------------- |\n| prompts/list | Discover available prompts | Array of prompt descriptors |\n| prompts/get | Retrieve prompt detai",
"chunk_index": 36,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__37",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "escriptors |\n| prompts/get | Retrieve prompt details | Full prompt definition with arguments |\nExample: Streamlined Workflows\nPrompts provide structured templates for common tasks. In the travel planning context:\n\"Plan a vacation\" prompt:\njson theme={null}\n{\n \"name\": \"plan-vacation\",\n \"title\": \"Plan",
"chunk_index": 37,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__38",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "{null}\n{\n \"name\": \"plan-vacation\",\n \"title\": \"Plan a vacation\",\n \"description\": \"Guide through vacation planning process\",\n \"arguments\": [\n { \"name\": \"destination\", \"type\": \"string\", \"required\": true },\n { \"name\": \"duration\", \"type\": \"number\", \"description\": \"days\" },\n { \"name\": \"budget\", \"type\": \"n",
"chunk_index": 38,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__39",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "iption\": \"days\" },\n { \"name\": \"budget\", \"type\": \"number\", \"required\": false },\n { \"name\": \"interests\", \"type\": \"array\", \"items\": { \"type\": \"string\" } }\n ]\n}\nRather than unstructured natural language input, the prompt system enables:\n\nSelection of the \"Plan a vacation\" template\nStructured input: Barc",
"chunk_index": 39,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__40",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "\"Plan a vacation\" template\nStructured input: Barcelona, 7 days, \\$3000, [\"beaches\", \"architecture\", \"food\"]\nConsistent workflow execution based on the template\n\nUser Interaction Model\nPrompts are user-controlled, requiring explicit invocation. The protocol gives implementers freedom to design inter",
"chunk_index": 40,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__41",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "rotocol gives implementers freedom to design interfaces that feel natural within their application. Key principles include:\n\nEasy discovery of available prompts\nClear descriptions of what each prompt does\nNatural argument input with validation\nTransparent display of the prompt's underlying template",
"chunk_index": 41,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__42",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "arent display of the prompt's underlying template\n\nApplications typically expose prompts through various UI patterns such as:\n\nSlash commands (typing \"/\" to see available prompts like /plan-vacation)\nCommand palettes for searchable access\nDedicated UI buttons for frequently used prompts\nContext menu",
"chunk_index": 42,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__43",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "I buttons for frequently used prompts\nContext menus that suggest relevant prompts\n\nBringing Servers Together\nThe real power of MCP emerges when multiple servers work together, combining their specialized capabilities through a unified interface.\nExample: Multi-Server Travel Planning\nConsider a perso",
"chunk_index": 43,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__44",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ple: Multi-Server Travel Planning\nConsider a personalized AI travel planner application, with three connected servers:\n\nTravel Server - Handles flights, hotels, and itineraries\nWeather Server - Provides climate data and forecasts\nCalendar/Email Server - Manages schedules and communications\n\nThe Comp",
"chunk_index": 44,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__45",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "r - Manages schedules and communications\n\nThe Complete Flow\n\nUser invokes a prompt with parameters:\n\njson theme={null}\n {\n \"prompt\": \"plan-vacation\",\n \"arguments\": {\n \"destination\": \"Barcelona\",\n \"departure_date\": \"2024-06-15\",\n \"return_date\": \"2024-06-22\",\n \"budget\": 3000,\n \"travelers\": 2\n }\n }\n\nUs",
"chunk_index": 45,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__46",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "06-22\",\n \"budget\": 3000,\n \"travelers\": 2\n }\n }\n\nUser selects resources to include:\ncalendar://my-calendar/June-2024 (from Calendar Server)\ntravel://preferences/europe (from Travel Server)\n\ntravel://past-trips/Spain-2023 (from Travel Server)\n\nAI processes the request using tools:\n\nThe AI first reads",
"chunk_index": 46,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__47",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "sses the request using tools:\n\nThe AI first reads all selected resources to gather context - identifying available dates from the calendar, learning preferred airlines and hotel types from travel preferences, and discovering previously enjoyed locations from past trips.\nUsing this context, the AI th",
"chunk_index": 47,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__48",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ons from past trips.\nUsing this context, the AI then executes a series of Tools:\n\nsearchFlights() - Queries airlines for NYC to Barcelona flights\ncheckWeather() - Retrieves climate forecasts for travel dates\n\nThe AI then uses this information to create the booking and following steps, requesting app",
"chunk_index": 48,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__49",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "te the booking and following steps, requesting approval from the user where necessary:\n\nbookHotel() - Finds hotels within the specified budget\ncreateCalendarEvent() - Adds the trip to the user's calendar\nsendEmail() - Sends confirmation with trip details\n\nThe result: Through multiple MCP servers, th",
"chunk_index": 49,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__50",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ails\n\nThe result: Through multiple MCP servers, the user researched and booked a Barcelona trip tailored to their schedule. The \"Plan a Vacation\" prompt guided the AI to combine Resources (calendar availability and travel history) with Tools (searching flights, booking hotels, updating calendars) ac",
"chunk_index": 50,
"total_chunks": 52
},
{
"chunk_id": "md_server-concepts_b2e90da1__51",
"doc_id": "md_server-concepts_b2e90da1",
"title": "Understanding MCP servers",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\server-concepts.md",
"filename": "server-concepts.md",
"file_path": "server-concepts.md",
"updated_at": "1760788520.8599238",
"text": "ng flights, booking hotels, updating calendars) across different servers—gathering context and executing the booking. A task that could've taken hours was completed in minutes using MCP.",
"chunk_index": 51,
"total_chunks": 52
},
{
"chunk_id": "md_versioning_2b1431db__0",
"doc_id": "md_versioning_2b1431db",
"title": "Versioning",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\versioning.md",
"filename": "versioning.md",
"file_path": "versioning.md",
"updated_at": "1760788520.8599238",
"text": "Versioning\nThe Model Context Protocol uses string-based version identifiers following the format\nYYYY-MM-DD, to indicate the last date backwards incompatible changes were made.\n\n The protocol version will not be incremented when the\n protocol is updated, as long as the changes maintain backwards com",
"chunk_index": 0,
"total_chunks": 5
},
{
"chunk_id": "md_versioning_2b1431db__1",
"doc_id": "md_versioning_2b1431db",
"title": "Versioning",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\versioning.md",
"filename": "versioning.md",
"file_path": "versioning.md",
"updated_at": "1760788520.8599238",
"text": "ted, as long as the changes maintain backwards compatibility. This allows\n for incremental improvements while preserving interoperability.\n\nRevisions\nRevisions may be marked as:\n\nDraft: in-progress specifications, not yet ready for consumption.\nCurrent: the current protocol version, which is ready f",
"chunk_index": 1,
"total_chunks": 5
},
{
"chunk_id": "md_versioning_2b1431db__2",
"doc_id": "md_versioning_2b1431db",
"title": "Versioning",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\versioning.md",
"filename": "versioning.md",
"file_path": "versioning.md",
"updated_at": "1760788520.8599238",
"text": "nt: the current protocol version, which is ready for use and may continue to\n receive backwards compatible changes.\nFinal: past, complete specifications that will not be changed.\n\nThe current protocol version is 2025-06-18.\nNegotiation\nVersion negotiation happens during\ninitialization. Clients and\ns",
"chunk_index": 2,
"total_chunks": 5
},
{
"chunk_id": "md_versioning_2b1431db__3",
"doc_id": "md_versioning_2b1431db",
"title": "Versioning",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\versioning.md",
"filename": "versioning.md",
"file_path": "versioning.md",
"updated_at": "1760788520.8599238",
"text": "ation happens during\ninitialization. Clients and\nservers MAY support multiple protocol versions simultaneously, but they MUST\nagree on a single version to use for the session.\nThe protocol provides appropriate error handling if version negotiation fails, allowing\nclients to gracefully terminate conn",
"chunk_index": 3,
"total_chunks": 5
},
{
"chunk_id": "md_versioning_2b1431db__4",
"doc_id": "md_versioning_2b1431db",
"title": "Versioning",
"url": "file://C:\\crawl\\mcp-docs-hf-space\\versioning.md",
"filename": "versioning.md",
"file_path": "versioning.md",
"updated_at": "1760788520.8599238",
"text": "ils, allowing\nclients to gracefully terminate connections when they cannot find a version compatible\nwith the server.",
"chunk_index": 4,
"total_chunks": 5
}
]