From 5516c1ba66221e42b5ac7efad8db331238cc08ab Mon Sep 17 00:00:00 2001
From: Konstantin Konstantinov <KKonstantinov@users.noreply.github.com>
Date: Fri, 27 Mar 2026 14:19:32 +0200
Subject: [PATCH] chore: add instructions docs (#1778)

---
 docs/server.md                              | 20 +++++++++++++++++++
 examples/server/src/serverGuide.examples.ts | 22 +++++++++++++++++++++
 2 files changed, 42 insertions(+)

diff --git a/docs/server.md b/docs/server.md
index 3c246ac12..ee2edac3c 100644
--- a/docs/server.md
+++ b/docs/server.md
@@ -330,6 +330,26 @@ server.registerTool(
 >
 > For protocol details, see [Logging](https://modelcontextprotocol.io/specification/latest/server/utilities/logging) in the MCP specification.
 
+## Instructions
+
+Pass an `instructions` string in the server options to describe how to use the server and its features. This can be used by clients to improve the LLM's understanding of available tools, resources, and prompts. It can be thought of like a "hint" to the model — for example, a client MAY add it to the system prompt. See [Instructions](https://modelcontextprotocol.io/specification/latest/basic/lifecycle#instructions) in the MCP specification.
+
+```ts source="../examples/server/src/serverGuide.examples.ts#instructions_basic"
+const server = new McpServer(
+    {
+        name: 'multi-tool-server',
+        version: '1.0.0'
+    },
+    {
+        instructions: `This server provides data-pipeline tools. Always call "validate-schema"
+before calling "transform-data" to avoid runtime errors.`
+    }
+);
+```
+
+> [!TIP]
+> Use instructions for cross-tool relationships, workflow ordering, and constraints that individual tool descriptions cannot express on their own.
+
 ## Server‑initiated requests
 
 MCP is bidirectional — servers can also send requests *to* the client during tool execution, as long as the client declares matching capabilities.
diff --git a/examples/server/src/serverGuide.examples.ts b/examples/server/src/serverGuide.examples.ts
index ca4be3d4a..f0140a27b 100644
--- a/examples/server/src/serverGuide.examples.ts
+++ b/examples/server/src/serverGuide.examples.ts
@@ -15,6 +15,27 @@ import type { CallToolResult, ResourceLink } from '@modelcontextprotocol/server'
 import { completable, McpServer, ResourceTemplate, StdioServerTransport } from '@modelcontextprotocol/server';
 import * as z from 'zod/v4';
 
+// ---------------------------------------------------------------------------
+// Instructions
+// ---------------------------------------------------------------------------
+
+/** Example: Providing server instructions to guide LLM usage. */
+function instructions_basic() {
+    //#region instructions_basic
+    const server = new McpServer(
+        {
+            name: 'multi-tool-server',
+            version: '1.0.0'
+        },
+        {
+            instructions: `This server provides data-pipeline tools. Always call "validate-schema"
+before calling "transform-data" to avoid runtime errors.`
+        }
+    );
+    //#endregion instructions_basic
+    return server;
+}
+
 // ---------------------------------------------------------------------------
 // Tools, resources, and prompts
 // ---------------------------------------------------------------------------
@@ -373,6 +394,7 @@ function dnsRebinding_allowedHosts() {
 }
 
 // Suppress unused-function warnings (functions exist solely for type-checking)
+void instructions_basic;
 void registerTool_basic;
 void registerTool_resourceLink;
 void registerTool_logging;