docs: Add guide for organizing larger FastMCP servers with versioned tools

[dgenio]

Summary

Adds documentation and examples for organizing larger FastMCP servers and managing tool versions.

Closes #1681

Changes

Documentation

• New: docs/server_organization.md - Comprehensive guide on:
  • Recommended project layout (server.py + tools/ structure)
  • Name-based tool versioning pattern (tool_v1, tool_v2)
  • When to create new versions vs. maintaining backward compatibility
  • Client consumption strategies (whitelists, version selection)
  • Advanced patterns (shared logic, deprecation)

Examples

• New: examples/snippets/servers/server_layout/ - Runnable example showing:
  • Organized tool structure with separate modules
  • Two versions of a tool (get_info_v1, get_info_v2) demonstrating breaking changes
  • Clean separation between server wiring and tool implementation

Other Changes

• Updated mkdocs.yml to include new docs page in navigation
• Updated examples/snippets/servers/__init__.py to include new example

Design Decisions

• Name-based versioning: Uses tool names like get_info_v1, get_info_v2 - compatible with current main branch, no protocol changes needed
• No dependency on unmerged PRs: This pattern works with the SDK as-is today
• Docs-only scope: No modifications to core library behavior under src/mcp/
• Follows existing patterns: Consistent with other snippet examples and documentation style

Testing

Run the example:
uv run examples/snippets/servers/server_layout/server.py## Checklist

• Documentation follows existing style and conventions
• Example code uses proper type hints
• Example follows existing snippet patterns
• No changes to core library behavior
• mkdocs.yml navigation updated
• Code passes ruff formatting/linting
• Example is runnable and self-contained

[maxisbey]

Thanks for the effort here! Unfortunately, SEP-1575 (tool versioning) is not yet accepted and is still in early discussions. The SEP would need to be accepted and part of an upcoming MCP spec release before we add anything about it in the SDK.

Once tool versioning lands in the spec, we'd be happy to revisit this.

_{AI Disclaimer}