Steps 1 through 9 suggestions #8

Jahteo · 2025-10-13T15:39:04Z

I was able to go through all solutions except step 9 authorizing mcp. Step 9 had no technical requirements or validation, only file changes.

Minor code changes implemented
recommendations and questions in code comments

Adds a note indicating that the VS Code MCP extension documentation URL is broken.

…lutions

Jahteo · 2025-10-14T17:13:27Z

training/1-what-is-mcp.md

+## Terminology Note
+
+<!-- comment: I had multiple comments about why we weren't defining client, server and transport clearly until I found them at the very bottom. List them early so learners can find the definition asap. We might also want to list them again at the end as a key takeaway, but definitely include them at the top. -->
+
+Throughout this training, we'll use "server" and "tool provider" consistently with the MCP SDK terminology. Remember:
+
+- **Client**: The AI agent, IDE, or chat application
+- **Server**: The MCP service that provides tools, resources, and prompts
+- **Transport**: The communication layer for client and server (stdio or Streamable HTTP)
+


I initially had multiple comments about why we weren't defining client, server and transport clearly until I found them at the very bottom. List them early so learners get the definition asap. We can still list them again at the end as a key takeaway if desired, but definitely include them at the top.

Jahteo · 2025-10-14T17:18:05Z

training/1-what-is-mcp.md

 **Key differences from tools:**

 - **Discoverable**: Agents can list and browse available resources
 - **Cacheable**: Content can be cached since resources are relatively static
 - **URI-based**: Use templated URI patterns for easy access
 - **Content-focused**: Represent "things that exist" vs "actions to take"

 **Examples:**

 - Configuration files
 - API documentation
 - Live data feeds
 - Database schemas
 - Log files
 - Project documentation


[organizing consideration]
Maybe move "Key differences" to the bottom of "## Resources" and consolidated with "Example context patterns", since that also lists the differences.
Bonus: "Examples" could then be consolidated into the "Resources" intro paragraph above, like how "### Tools" has it. Fewer bold list headings = easier to understand structure

Jahteo · 2025-10-14T17:20:57Z

training/1-what-is-mcp.md

 **Agent capabilities with resources:**

 - VS Code and other agents can treat resources as virtual files
 - Display resources in tree views or file explorers
 - Cache frequently accessed resources for performance
 - Use resource content for IntelliSense and autocomplete
 - Preview resource content without executing actions

 **Context efficiency:**

 - **Resources can be cached**: Fetch once, reference multiple times without re-loading
 - **Selective loading**: Agents can load only relevant parts of large resources
 - **Reference vs execution**: Resources can be referenced by URI without full content in context
 - **Tools require execution context**: Each tool call needs parameters, execution trace, and results


[minor thought]
Agent capabilities and Context efficiency lists make the Resources section feel too long. And since caching is mentioned in 3 lists, it makes these feel slightly redundant. Could these be consolidated?

Jahteo · 2025-10-14T17:23:27Z

training/1-what-is-mcp.md


+<!-- this is where we should start all Tools vs Resources lists. "Example context patterns" should be renamed to make it clear that it's a comparison list, if it's going to stay as it's own list -->
+
 **Example context patterns:**


Continuing off prior comment about moving comparisons to the end:
This is where we could start all the Tools vs Resources lists.

"Example context patterns" should also be renamed to make it clear that it's a comparison list, if it's going to stay as it's own list.

Jahteo · 2025-10-14T17:36:40Z

training/2-using-mcp.md


+<!-- todo: this url is broken ⬇️. Maybe it should be https://code.visualstudio.com/docs/copilot/customization/mcp-servers ? -->
+
 📝 **Reference**: [VS Code MCP Extension Documentation](https://github.com/modelcontextprotocol/vscode-mcp)


broken url. Should it be https://code.visualstudio.com/docs/copilot/customization/mcp-servers ?

Jahteo · 2025-10-14T20:09:38Z

training/6-streaming-mcp.md


+<!-- what progressToken? -->
+
 When a client doesn't provide a `progressToken`, you can still stream intermediate content updates using structured notification messages:


[clarify]
what is this progressToken & what should we be doing about it? Should it be coded somewhere? How do we test for it?

Jahteo · 2025-10-14T21:12:25Z

training/8-validating-mcp.md


+<!-- ? why not just provide the default in only the typescript function? This would cause confusion if someone updates only 1 of the 2... -->
+
 **Note on defaults**: While Zod's `.default()` provides the default value, you should also add a TypeScript default in your function parameter destructuring for type safety:


why not just provide the default in only the typescript function? This would cause confusion if someone updates only 1 of the 2...

Jahteo · 2025-10-14T21:16:49Z

training/8-validating-mcp.md


+<!-- broken link. maybe https://modelcontextprotocol.io/docs/learn/server-concepts? -->
+
 The **[MCP SDK](https://modelcontextprotocol.io/docs/api/server)** provides specific error types for different scenarios:


broken link. maybe https://modelcontextprotocol.io/docs/learn/server-concepts?

Jahteo · 2025-10-14T21:22:17Z

training/9-authorizing-mcp.md


+<!-- todo: Recommend a mermaid diagram plugin. VScode supports no diagramming languages by default. - ex: Markdown Preview Mermaid Support -->
+
 ```mermaid


[todo]
Recommend a mermaid diagram plugin. VScode supports no diagramming languages by default.

ex: Markdown Preview Mermaid Support

Jahteo · 2025-10-14T21:22:58Z

training/9-authorizing-mcp.md

[todo]
Missing the "problem" & "verify" sections. & need more than just the diagram for the background info section.

…e collapsable

Jahteo · 2025-10-14T21:33:22Z

training/6-streaming-mcp.md

+   # Note: If port 6277 is in use, set a new `SERVER_PORT`.
+   # You can also optionally change the URL by setting a new `CLIENT_PORT`.
+   # Example of changing both:
+   # CLIENT_PORT=8080 SERVER_PORT=6278 npx @modelcontextprotocol/inspector


Should we introduce this earlier?

Why include this: Trying to simply run the inspector in two terminals results in a "port in use" error

Jahteo added 9 commits October 9, 2025 18:03

fix table of contents

74684eb

fix urls

126f115

optional suggestions on organization and definitions

f60a5b8

Update URLs

21d0eda

Adds a note indicating that the VS Code MCP extension documentation URL is broken.

suggestions comments

73ceb19

change filename to mcp-training-stdio to match actual filename and so…

14dc99b

…lutions

linting code solution

0aa17ba

small fixes

a1d8439

minor comments

7e28973

Jahteo requested a review from justinbmeyer October 13, 2025 15:39

Jahteo commented Oct 14, 2025

View reviewed changes

Inline comments moved to PR comments. Some implemented. Solutions mad…

79c439b

…e collapsable

Jahteo commented Oct 14, 2025

View reviewed changes

minor clarify around existing files

b40f542

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Steps 1 through 9 suggestions #8

Steps 1 through 9 suggestions #8

Uh oh!

Jahteo commented Oct 13, 2025

Uh oh!

Jahteo Oct 14, 2025

Uh oh!

Jahteo Oct 14, 2025

Uh oh!

Jahteo Oct 14, 2025

Uh oh!

Jahteo Oct 14, 2025

Uh oh!

Jahteo Oct 14, 2025

Uh oh!

Jahteo Oct 14, 2025

Uh oh!

Jahteo Oct 14, 2025

Uh oh!

Jahteo Oct 14, 2025

Uh oh!

Jahteo Oct 14, 2025

Uh oh!

Jahteo Oct 14, 2025

Uh oh!

Jahteo Oct 14, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant


		<!-- this is where we should start all Tools vs Resources lists. "Example context patterns" should be renamed to make it clear that it's a comparison list, if it's going to stay as it's own list -->

		Example context patterns:


		<!-- todo: this url is broken ⬇️. Maybe it should be https://code.visualstudio.com/docs/copilot/customization/mcp-servers ? -->

		📝 Reference: [VS Code MCP Extension Documentation](https://github.com/modelcontextprotocol/vscode-mcp)


		<!-- what progressToken? -->

		When a client doesn't provide a `progressToken`, you can still stream intermediate content updates using structured notification messages:


		<!-- ? why not just provide the default in only the typescript function? This would cause confusion if someone updates only 1 of the 2... -->

		Note on defaults: While Zod's `.default()` provides the default value, you should also add a TypeScript default in your function parameter destructuring for type safety:


		<!-- broken link. maybe https://modelcontextprotocol.io/docs/learn/server-concepts? -->

		The [MCP SDK](https://modelcontextprotocol.io/docs/api/server) provides specific error types for different scenarios:


		<!-- todo: Recommend a mermaid diagram plugin. VScode supports no diagramming languages by default. - ex: Markdown Preview Mermaid Support -->

		```mermaid

Steps 1 through 9 suggestions #8

Are you sure you want to change the base?

Steps 1 through 9 suggestions #8

Uh oh!

Conversation

Jahteo commented Oct 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant