A hands-on learning path for the Model Context Protocol (MCP) featuring structured lessons on server construction, client implementation, and the three MCP primitives (Tools, Resources, Prompts), accompanied by a fully working CLI chat demo project (documentMCP) that integrates
SaferSkills independently audited claude-mcp-course (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
A hands-on learning path for the Model Context Protocol (MCP) — the open standard that connects AI applications to external data sources, tools, and workflows through a unified interface.
This repository contains structured learning materials that progress from core concepts to working demo projects, covering server construction, client implementation, the three MCP primitives (Tools, Resources, Prompts), and advanced topics like sampling, notifications, roots, and transports.
Foundational concepts behind MCP and the role of clients in the protocol.
| # | File | Summary |
|---|---|---|
| 1.1 | Introducing MCP | What MCP is, the USB-C analogy, client/server architecture, capabilities overview, and real-world use cases. |
| 1.2 | MCP Clients | The client as intermediary between AI models and servers — tool management, resource access, prompt handling, and the full interaction workflow loop. |
Build and test an MCP server from scratch using the Python SDK and FastMCP.
| # | File | Summary |
|---|---|---|
| 2.1 | Project Setup | Setting up a Python environment, transport options (stdio), session management, and dependency installation. |
| 2.2 | Define Tools in MCP | Creating tools with the @mcp.tool decorator, type hints, pydantic Field validation, error handling, and real-world examples (read_doc_contents, edit_document). |
| 2.3 | The Server Inspector | Using the MCP Inspector (mcp dev) to test servers interactively without building a full client. |
Implement a client that connects to MCP servers and integrates with Claude.
| # | File | Summary |
|---|---|---|
| 3.1 | Implementing a Client | Building a class-based MCP client — session lifecycle, async context management, tool/resource/prompt wrappers, and the complete data flow. |
| 3.2 | Defining Resources | Server-side resource definitions — static vs. templated URIs, the @mcp.resource decorator, URI design, and MIME types. |
| 3.3 | Accessing Resources | Client-side resource reading — read_resource implementation, AnyUrl wrapping, and MIME-based content parsing. |
| 3.4 | Defining Prompts | Server-side prompt templates — the @mcp.prompt decorator, argument injection, UserMessage construction, and use cases. |
| 3.5 | Prompts in the Client | Client-side prompt consumption — list_prompts for discovery, get_prompt for retrieval, and the end-to-end prompt workflow. |
| 3.6 | MCP Review | Cheat-sheet covering the three primitives, a decision matrix for choosing between them, and the full development lifecycle. |
Deep dives into MCP features beyond the three core primitives.
| # | File | Summary |
|---|---|---|
| 4.1 | Sampling | The "reverse request" — servers ask clients to generate text via the LLM. Security, cost, and stdio vs. HTTP trade-offs. |
| 4.2 | Log and Progress Notifications | Real-time feedback during tool execution using ctx.info() and ctx.report_progress(). Server and client setup. |
| 4.3 | Roots | Scoped file system access — granting servers permission to specific directories, autonomous discovery, and enforcing boundaries. |
| 4.4 | JSON Message Types | The JSON-RPC message format (requests, results, notifications), transport comparison, and critical server flags (stateless, json_response). |
| 4.5 | The STDIO Transport | How stdio works — bidirectional communication via stdin/stdout, the initialization handshake, and the same-machine limitation. |
| 4.6 | The StreamableHTTP Transport | Hosting MCP servers remotely — Server-Sent Events (SSE) for bidirectional messaging, session IDs, and danger flags. |
See 004-Advanced-Topics/README.md for the full section index including demo applications.
cli_project_mcp/The primary demo application. An interactive CLI chat that connects Claude to an in-memory document store through MCP. Supports @ document mentions, / commands, and tab autocompletion.
cli_project_mcp/
├── main.py # Entry point
├── mcp_server.py # FastMCP server — tools, resources, prompts
├── mcp_client.py # MCP client — stdio transport
├── core/
│ ├── chat.py # Base chat class — agentic tool-use loop
│ ├── cli_chat.py # @mention extraction, /command routing
│ ├── claude.py # Anthropic API wrapper
│ ├── cli.py # Interactive CLI with autocompletion
│ └── tools.py # Tool discovery and execution
├── pyproject.toml # Dependencies
└── .env.example # Environment variable templateSee cli_project_mcp/README.md for full documentation.
004-Advanced-Topics/sampling/Demonstrates the reverse request pattern. The server's summarize tool asks the client to call Claude via a sampling callback, so the server never needs its own API key.
See 004-Advanced-Topics/sampling/README.md.
004-Advanced-Topics/notifications/Demonstrates real-time feedback. The server's add tool sends log messages (ctx.info()) and progress updates (ctx.report_progress()) to the client during execution.
See 004-Advanced-Topics/notifications/README.md.
004-Advanced-Topics/roots/Demonstrates scoped file system access. A CLI chat where the user passes root directories as arguments. The server can only access files within those roots, enforced by is_path_allowed(). Includes a video converter tool using FFmpeg.
See 004-Advanced-Topics/roots/README.md.
004-Advanced-Topics/transport-http/Demonstrates the HTTP transport with a browser-based protocol explorer. Walks through the JSON-RPC handshake (Initialize, Initialized, Tool Call) and shows raw request/response payloads. Runs with stateless_http=True to illustrate the limitations of stateless mode.
See 004-Advanced-Topics/transport-http/README.md.
transSum-server/A modular document summarizer and translator that combines multiple MCP features in a single project. Uses Ollama (local) or Anthropic Claude as the LLM backend, with intelligent chunking and a map-reduce pipeline for long documents.
MCP features demonstrated:
summarize_text, translate_text, summarize_filetransSum-server/
├── src/transsum/
│ ├── config.py # Pydantic-validated settings
│ ├── cli.py # Rich CLI
│ ├── models/ # Ollama & Anthropic adapters
│ ├── processing/ # Loader, chunker, map-reduce pipeline
│ └── mcp/server.py # FastMCP server (tools, resources, prompts, sampling)
├── tests/ # Mock-based test suite
└── pyproject.tomlSee transSum-server/README.md for full documentation.
cd introduction-to-mcp/cli_project_mcp
# Configure environment
cp .env.example .env
# Edit .env → set ANTHROPIC_API_KEY
# Install with uv (recommended)
pip install uv
uv venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
uv pip install -e .
# Or install with pip
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install anthropic python-dotenv prompt-toolkit "mcp[cli]>=1.8.0"Each demo in 004-Advanced-Topics/ is self-contained:
cd 004-Advanced-Topics/<demo-directory>
# Configure environment (where applicable)
cp .env.example .env
# Edit .env → set ANTHROPIC_API_KEY
# Install and run
uv sync
uv run client.py # sampling, notifications
uv run main.py # roots, transport-httpcd introduction-to-mcp/transSum-server
# Configure environment
cp .env.example .env
# Edit .env → set MODEL_PROVIDER and keys as needed
# Install and run
uv sync
# Run tests
uv run pytest -v
# Test with MCP Inspector
uv run mcp dev src/transsum/mcp/server.py| Package | Used by | Purpose |
|---|---|---|
anthropic | documentMCP, sampling, roots | Claude API client |
mcp[cli] | All projects | Model Context Protocol SDK |
prompt-toolkit | documentMCP, roots | Interactive CLI with autocompletion |
python-dotenv | documentMCP, roots | .env file loading |
aioconsole | sampling, notifications | Async console I/O |
# Run the main CLI chat application
cd cli_project_mcp
uv run main.py # or: python main.py> What documents are available? # plain chat
> Tell me about @deposition.md # @mention injects document context
> /format spec.txt # /command runs a server-defined prompt
> /summarize report.pdf # Tab for autocompletionTo test an MCP server in isolation with the Inspector:
mcp dev mcp_server.py| Primitive | Controlled by | Purpose | Example |
|---|---|---|---|
| Tools | AI model | Perform actions | read_doc_contents, edit_doc_contents |
| Resources | Application | Expose data | docs://documents, docs://documents/{id} |
| Prompts | User | Start workflows | /format, /summarize |
Introducing MCP ➜ MCP Clients ➜ Project Setup ➜ Define Tools ➜ Server Inspector
➜ Implementing a Client ➜ Resources ➜ Prompts ➜ MCP Review ➜ Run the Demo
➜ Sampling ➜ Notifications ➜ Roots ➜ Transports ➜ Run Advanced DemosFollow the numbered sections in order. Sections 1-3 build toward the cli_project_mcp demo. Section 4 explores advanced features with standalone demos.
](https://anthropic.skilljar.com/introduction-to-agent-skills)
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.