feat(mcp): add server instructions to initialize response (#389)

Adds a configurable top-level `instructions` field surfaced in the MCP `initialize` response via `WithInstructions`. When unset, a routing-mode-aware built-in default explains the `retrieve_tools` → `call_tool_*` workflow and warns against using `search_servers` to find already-connected tools.

- internal/config: new `Config.Instructions` field
- internal/server/mcp.go: `defaultInstructions` + `resolveInstructions()`, wired into capabilities
- Tests, regenerated OpenAPI artifacts, docs/configuration.md row

Thanks to @badigit for the contribution.

Author: badigit

docs/configuration.md

@@ -756,6 +756,22 @@ All three modes are always available on dedicated endpoints regardless of config
 
 See [Routing Modes](features/routing-modes.md) for complete details.
 
+## Server Instructions
+
+Text returned in the MCP `initialize` response to guide AI agents on how to use the proxy (e.g., use `retrieve_tools` to discover existing tools rather than `search_servers`).
+
+```json
+{
+  "instructions": "Use retrieve_tools to discover tools before assuming a capability is unavailable."
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `instructions` | string | _(built-in)_ | Custom instructions sent in the MCP `initialize` response. When empty, a built-in default explains the `retrieve_tools` → `call_tool_*` workflow and warns against using `search_servers` for existing tools. |
+
+**Note:** Applied at startup / on the next client connect — editing this value does not hot-reload into already-connected MCP sessions.
+
 ---
 
 ## Tool-Level Quarantine

internal/config/config.go

@@ -226,6 +226,10 @@ type Config struct {
 	// Valid values: "retrieve_tools" (default), "direct", "code_execution"
 	RoutingMode string `json:"routing_mode,omitempty" mapstructure:"routing-mode"`
 
+	// Instructions text returned in the MCP initialize response to guide AI agents.
+	// When empty, a built-in default is used that explains retrieve_tools workflow.
+	Instructions string `json:"instructions,omitempty" mapstructure:"instructions"`
+
 	// QuarantineEnabled controls whether quarantine is active. It gates two
 	// things together:
 	//   1. Server-level auto-quarantine for newly added servers (issue #370).

internal/server/mcp.go

@@ -58,6 +58,17 @@ const (
 	operationListRegistries  = "list_registries"
 	operationSearchServers   = "search_servers"
 
+	// defaultInstructions is returned in the MCP initialize response when no
+	// custom instructions are configured. It guides AI agents on the correct
+	// workflow for discovering and calling tools through the proxy.
+	defaultInstructions = "This is mcpproxy-go, an MCP aggregator proxy that connects multiple upstream MCP servers and exposes their tools. " +
+		"DISCOVERY: Use 'retrieve_tools' to search for tools by description across all connected upstream servers — do this before assuming a capability is unavailable. " +
+		"CALLING: When 'call_tool_read', 'call_tool_write', and 'call_tool_destructive' are exposed, call the variant named by the 'call_with' field of each retrieve_tools result. " +
+		"When 'code_execution' is exposed, you may instead orchestrate several discovered tools in a single step with JavaScript. " +
+		"When upstream tools are listed directly (named 'server__tool'), just call them by name. " +
+		"Do NOT use 'search_servers' to find existing tools — it searches EXTERNAL registries for adding NEW servers only. " +
+		"Use 'upstream_servers' with operation 'list' to see currently connected servers and their status."
+
 	// Connection status constants
 	statusError                = "error"
 	statusDisabled             = "disabled"
@@ -67,6 +78,14 @@ const (
 	messageConnectionCancelled = "Connection monitoring cancelled due to server shutdown"
 )
 
+// resolveInstructions returns custom instructions if set, otherwise the built-in default.
+func resolveInstructions(custom string) string {
+	if custom != "" {
+		return custom
+	}
+	return defaultInstructions
+}
+
 // proxyVersion holds the build version for MCP server identification.
 // Set via SetMCPServerVersion during startup.
 var proxyVersion = "1.0.0"
@@ -256,6 +275,9 @@ func NewMCPProxyServer(
 		capabilities = append(capabilities, mcpserver.WithPromptCapabilities(true))
 	}
 
+	// Add server instructions for AI agent guidance
+	capabilities = append(capabilities, mcpserver.WithInstructions(resolveInstructions(config.Instructions)))
+
 	mcpServer := mcpserver.NewMCPServer(
 		"mcpproxy-go",
 		mcpServerVersion(),

internal/server/mcp_instructions_test.go

@@ -0,0 +1,29 @@
+package server
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestResolveInstructions_Default(t *testing.T) {
+	result := resolveInstructions("")
+	assert.Equal(t, defaultInstructions, result)
+}
+
+func TestResolveInstructions_Custom(t *testing.T) {
+	custom := "Use retrieve_tools to find tools. Custom instructions."
+	result := resolveInstructions(custom)
+	assert.Equal(t, custom, result)
+}
+
+func TestDefaultInstructions_ContainsKeyTerms(t *testing.T) {
+	assert.Contains(t, defaultInstructions, "retrieve_tools")
+	assert.Contains(t, defaultInstructions, "search_servers")
+	assert.Contains(t, defaultInstructions, "call_tool_read")
+	assert.Contains(t, defaultInstructions, "upstream_servers")
+	// Routing-mode-aware guidance: the default must also cover the
+	// code_execution and direct (server__tool) modes (Spec 031).
+	assert.Contains(t, defaultInstructions, "code_execution")
+	assert.Contains(t, defaultInstructions, "server__tool")
+}

oas/docs.go

@@ -75,6 +75,11 @@ components:
             so an unset key behaves exactly as before this feature (SC-005). Validated
             in Validate(): health-check ∈ {0} ∪ [5s,1h]; tool-discovery ∈ {0} ∪ [30s,24h].
           type: string
+        instructions:
+          description: |-
+            Instructions text returned in the MCP initialize response to guide AI agents.
+            When empty, a built-in default is used that explains retrieve_tools workflow.
+          type: string
         intent_declaration:
           $ref: '#/components/schemas/config.IntentDeclarationConfig'
         listen: