feat(everything): add trigger-agentic-sampling tool

[olaservo]

Description

Adds support for SEP-1577 (Sampling With Tools) to the Everything server by introducing a new trigger-agentic-sampling tool that demonstrates the agentic sampling loop pattern.

This tool:

• Sends a prompt to the client's LLM with tools available
• Handles tool_use responses and executes tools locally
• Loops until a final text response is received or max iterations reached
• Only registers if the client supports sampling.tools capability

Server Details

• Server: everything
• Changes to: tools

Motivation and Context

Issue: #3040

SEP-1577 adds tool calling support to the MCP sampling API, enabling servers to provide tools that the LLM can use during sampling requests. This creates an "agentic loop" where:

1. Server sends sampling/createMessage with a tools array
2. If the LLM returns stopReason: "toolUse", the server executes the tools
3. Server sends tool results back and continues until final response

The Everything server is a reference implementation that demonstrates all MCP features, so it should include this capability.

How Has This Been Tested?

• Build passes successfully
• Tool registration is conditional on sampling.tools capability check
• Follows the same pattern as existing conditional tools (trigger-sampling-request, trigger-elicitation-request)
• Tested with custom client using local build of Typescript SDK (see also: Client-side sampling validation doesn't use CreateMessageResultWithToolsSchema when tools are present typescript-sdk#1346 )

(We can wait to merge until I've had a chance to add a screengrab if that's preferred.)

Breaking Changes

No

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Protocol Documentation
• My changes follows MCP security best practices
• I have updated the server's README accordingly
• I have tested this with an LLM client
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have documented all environment variables and configuration options

Additional context

References

• SEP-1577 Proposal
• Specification changes
• TypeScript SDK changes
• Inspector support

Implementation Notes

The tool includes simple local implementations of echo and add tools for demonstration purposes. In a production scenario, tools could likely be reused via:

• Internal server.server.callTool() calls
• Connecting to other MCP servers as a client
• Shared business logic functions

I thought about trying to re-use existing tools already defined in the everything server, but then decided to keep it self-contained instead.

[domdomegg]

Nice!

[cliffhall]

Can't test with the Inspector yet (saw your mention of an issue with the SDK on that), but review did turn up a few minor things.

[cliffhall]

Hi @olaservo. If you could resolve the conflicts and include some screenshots, it would be helpful. I'm still not fully up to speed on what this looks like for the Inspector side of things, so I need to do some reseach.

[olaservo]

Fixed the conflicts, working on some screenshots from my custom client to illustrate the flow (I think I might update the example here too in the process).

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 3m 49s —— View job

---

PR Review: feat(everything): add trigger-agentic-sampling tool

• Gather context and read changed files
• Review documentation changes
• Review tool registration
• Review main implementation file
• Post findings

---

Overall this is a well-structured implementation of the SEP-1577 agentic sampling loop. The build passes cleanly and the core logic is sound. A few issues to address before merging:

Issues

1. Inconsistent indentation in the handler body (style)

[trigger-agentic-sampling.ts:167-317] The server.registerTool(...) callback body starts at 4-space indent (lines 168–312) but then the return statement on line 314 jumps to 6 spaces before the closing }); on line 317. Compare with trigger-sampling-request.ts where the handler body is consistently at 6 spaces (2 for the function body + 2 for the if block + 2 for the callback). The entire handler body from line 168 to 316 should be at 6-space indent.

Fix this →

2. Variable shadowing (code smell)

[trigger-agentic-sampling.ts:173-174] The outer name constant (line 134, value "trigger-agentic-sampling") is shadowed by the callback parameters in the filter/map chain:

const tools: Tool[] = availableTools
  .filter((name) => name in AVAILABLE_TOOL_DEFINITIONS)  // shadows outer `name`
  .map((name) => AVAILABLE_TOOL_DEFINITIONS[name]);      // shadows outer `name`

Rename to toolName to avoid the shadowing and improve clarity. Fix this →

3. README.md not updated

The checklist marks "I have updated the server's README accordingly" but src/everything/README.md has no mention of trigger-agentic-sampling. Only the docs/features.md and docs/structure.md files were updated. The README should at minimum reference the new tool. Fix this →

4. Decorative comment banners don't match repo style (minor)

The file uses heavy // ====...==== section dividers that don't appear in any other tool file in the repo. These add noise without benefit — the section names (INPUT SCHEMA, TOOL DEFINITIONS, etc.) are self-evident from the code. Suggest removing them to match the lean style of the rest of the codebase.

Looks Good

• Conditional registration: Correctly gates on "tools" in samplingCapability, matching the pattern in trigger-sampling-request.ts and trigger-elicitation-request.ts. No console.log on skip (previous review feedback addressed).
• console.error for debug output: Correct — using stderr avoids corrupting STDIO JSON-RPC output.
• toolChoice: none on the final iteration: Smart safety valve to force a text response when the iteration limit is about to be hit.
• Batched tool results: Multiple tool_use blocks in a single response are all executed and returned as a single role: "user" message with an array of tool_result items — correct per MCP spec.
• Post-loop guard: The if (iteration >= maxIterations && !finalResponse) check correctly handles the edge case where the LLM returns stopReason: "toolUse" even when toolChoice: none was sent.
• SDK types: CreateMessageResultWithToolsSchema, ToolUseContent, ToolResultContent, toolChoice are all present in the installed SDK v1.25.2 — build passes cleanly.
• Type cast: toolUse.input as Record<string, unknown> on line 266 is expected; ToolUseContent.input is typed as object in the SDK.