From 3064a73f1668d34281ffe795ba3bbbf799882857 Mon Sep 17 00:00:00 2001
From: Jacob Leksan <jacob.leksan@expedient.com>
Date: Mon, 6 Apr 2026 14:31:17 -0400
Subject: [PATCH] Implement MCP server instructions handling: append
 instructions to system prompt in chat payload and add configuration option in
 AddToolServerModal.

---
 backend/open_webui/utils/mcp/client.py       |  9 +++++-
 backend/open_webui/utils/middleware.py       |  9 ++++++
 src/lib/components/AddToolServerModal.svelte | 31 ++++++++++++++++++--
 3 files changed, 46 insertions(+), 3 deletions(-)

diff --git a/backend/open_webui/utils/mcp/client.py b/backend/open_webui/utils/mcp/client.py
index beb2f15079..669e06dd13 100644
--- a/backend/open_webui/utils/mcp/client.py
+++ b/backend/open_webui/utils/mcp/client.py
@@ -52,6 +52,8 @@ class MCPClient:
     def __init__(self):
         self.session: Optional[ClientSession] = None
         self.exit_stack = None
+        # From InitializeResult.instructions (MCP protocol); forwarded to the model when using this server.
+        self.server_instructions: Optional[str] = None
 
     async def connect(self, url: str, headers: Optional[dict] = None):
         async with AsyncExitStack() as exit_stack:
@@ -71,7 +73,11 @@ class MCPClient:
 
                 self.session = await exit_stack.enter_async_context(self._session_context)
                 with anyio.fail_after(10):
-                    await self.session.initialize()
+                    init_result = await self.session.initialize()
+                instr = getattr(init_result, 'instructions', None)
+                if isinstance(instr, str):
+                    instr = instr.strip()
+                self.server_instructions = instr or None
                 self.exit_stack = exit_stack.pop_all()
             except Exception as e:
                 await asyncio.shield(self.disconnect())
@@ -153,6 +159,7 @@ class MCPClient:
         # Prevent double-close from concurrent callers
         self.exit_stack = None
         self.session = None
+        self.server_instructions = None
 
         try:
             await asyncio.wait_for(
diff --git a/backend/open_webui/utils/middleware.py b/backend/open_webui/utils/middleware.py
index 54df422c4b..4207a377db 100644
--- a/backend/open_webui/utils/middleware.py
+++ b/backend/open_webui/utils/middleware.py
@@ -2546,6 +2546,15 @@ async def process_chat_payload(request, form_data, user, metadata, model):
                             headers=headers if headers else None,
                         )
 
+                        if mcp_server_connection.get('config', {}).get('forward_mcp_instructions', True):
+                            mcp_instr = mcp_clients[server_id].server_instructions
+                            if mcp_instr:
+                                form_data['messages'] = add_or_update_system_message(
+                                    mcp_instr,
+                                    form_data['messages'],
+                                    append=True,
+                                )
+
                         function_name_filter_list = mcp_server_connection.get('config', {}).get(
                             'function_name_filter_list', ''
                         )
diff --git a/src/lib/components/AddToolServerModal.svelte b/src/lib/components/AddToolServerModal.svelte
index 2237c1afc6..ace505baab 100644
--- a/src/lib/components/AddToolServerModal.svelte
+++ b/src/lib/components/AddToolServerModal.svelte
@@ -50,6 +50,8 @@
 	let headers = '';
 
 	let functionNameFilterList = '';
+	/** MCP: append InitializeResult.instructions to the system prompt (backend). */
+	let forwardMcpInstructions = true;
 	let accessGrants = [];
 
 	let id = '';
@@ -223,6 +225,9 @@
 				if (data.config) {
 					enable = data.config.enable ?? true;
 					accessGrants = data.config.access_grants ?? [];
+					if (data.config.forward_mcp_instructions !== undefined) {
+						forwardMcpInstructions = data.config.forward_mcp_instructions;
+					}
 				}
 
 				toast.success($i18n.t('Import successful'));
@@ -252,7 +257,10 @@
 					id: id,
 					name: name,
 					description: description
-				}
+				},
+				...(type === 'mcp'
+					? { config: { forward_mcp_instructions: forwardMcpInstructions } }
+					: {})
 			}
 		]);
 
@@ -329,7 +337,8 @@
 			config: {
 				enable: enable,
 				function_name_filter_list: functionNameFilterList,
-				access_grants: accessGrants
+				access_grants: accessGrants,
+				...(type === 'mcp' ? { forward_mcp_instructions: forwardMcpInstructions } : {})
 			},
 			info: {
 				id: id,
@@ -368,6 +377,7 @@
 
 		enable = true;
 		functionNameFilterList = '';
+		forwardMcpInstructions = true;
 		accessGrants = [];
 	};
 
@@ -394,6 +404,7 @@
 
 			enable = connection.config?.enable ?? true;
 			functionNameFilterList = connection.config?.function_name_filter_list ?? '';
+			forwardMcpInstructions = connection.config?.forward_mcp_instructions ?? true;
 			accessGrants = connection.config?.access_grants ?? [];
 		}
 	};
@@ -880,6 +891,22 @@
 									</div>
 								</div>
 							{/if}
+
+							{#if type === 'mcp'}
+								<Tooltip
+									className="flex w-full items-center justify-between gap-3 mt-2"
+									content={$i18n.t(
+										'When enabled, instructions returned in the MCP initialize response are appended to the system prompt for chats that use this server.'
+									)}
+								>
+									<span
+										class={`text-xs font-medium ${($settings?.highContrastMode ?? false) ? 'text-gray-800 dark:text-gray-100' : 'text-gray-700 dark:text-gray-200'}`}
+									>
+										{$i18n.t('Include MCP server instructions')}
+									</span>
+									<Switch bind:state={forwardMcpInstructions} />
+								</Tooltip>
+							{/if}
 						{/if}
 
 						{#if !direct}