Advanced Data Structures & Algorithms

Java Backend Modernization

Beginner's Guide to Data Structures

Agentic AI Systems

Data Engineering & Spark Mastery

Low-Level Design Interview Prep

Microservices Interview Roadmap

Design Patterns Interview Roadmap

Distributed Systems Interview Roadmap

Mastering Python Development

System Design Interview Prep

Distributed Systems Refresher

AI Engineering Launchpad

Architecture Patterns for Scalable Systems

RAG & Vector Search Mastery

Production DevOps & Reliability

Enterprise Patterns Playbook

Master Coding Interviews

Coding Techniques Interview Roadmap

Data Structures Interview Roadmap

Architecture Patterns Interview Roadmap

software-engineering-principles

Migrate your Spring Boot services from thread-pool exhaustion to JDK 21 virtual threads — the practical Spring developer guide

Adapting to Virtual Threads for Spring Developers

how-it-works-internals-explained

From WAL and MVCC to fsync and isolation levels — the internals behind every ACID guarantee in PostgreSQL, MySQL, Oracle, and SQL Server.

ACID Properties Explained: How SQL Databases Guarantee Atomicity, Consistency, Isolation, and Durability

How modern NoSQL databases achieve atomicity and isolation without a single machine

ACID Transactions in Distributed Databases: DynamoDB, Cosmos DB, and Spanner Compared

llm-engineering

Is an LLM a brain in a jar? To make it truly useful, we need to give it access to the world. This guide explains RAG and Agents.

Advanced AI: Agents, RAG, and the Future of Intelligence

Production AI needs explicit routing, memory, execution, and evaluation layers rather than one loop.

AI Architecture Patterns: Routers, Planner-Worker Loops, Memory Layers, and Evaluation Guardrails

datastructures-and-algorithms

Master shortest paths, dependency resolution, and cycle detection with robust Java solutions.

Advanced Graph Algorithms: Dijkstra, Topological Sort, and Disjoint Set Union (DSU)

An LLM can talk, but an AI Agent can *act*. We explain how Agents use the ReAct framework to brow...

AI Agents Explained: When LLMs Start Using Tools

A production-first guide to picking the right vector index for recall, latency, memory, and update patterns.

ANN Index Types Explained: When to Choose Flat, HNSW, IVF, or IVF-PQ

apache-spark-engineering

Process petabytes with Python: understand Spark's execution model, DataFrame transformations, partitioning strategy, and real-time streaming.

Apache Spark for Data Engineers: RDDs, DataFrames, and Structured Streaming

ACID guarantees consistency. BASE guarantees availability. We explain the trade-offs between SQL...

BASE Theorem Explained: How it Stands Against ACID

machine-learning-fundamentals

From the query-key-value formulation to multi-head attention — the mechanism that made transformers dominate AI

Attention Mechanism Explained: How Transformers Learn to Focus

system-design-interview-prep

They all sit in front of your servers. But do you need Nginx, HAProxy, or Kong? We clarify the roles of each component.

API Gateway vs. Load Balancer vs. Reverse Proxy: What's the Difference?

architecture-patterns-for-production-systems

Mobile apps need less data than Desktop dashboards. Why serve them the same JSON? The Backend for Frontend (BFF) pattern solves this.

Backend for Frontend (BFF): Tailoring APIs for UI

BFS explores graphs level by level using a queue — the key to shortest paths and level-order problems.

BFS — Breadth-First Search: Level-by-Level Graph Exploration

Backtracking is a brute-force algorithmic technique that solves problems by trying to build a sol...

Exploring Backtracking Techniques in Data Structures

big-data-engineering

Choose ingestion, serving, and ownership patterns deliberately when data platforms start to scale.

Big Data Architecture Patterns: Lambda, Kappa, CDC, Medallion, and Data Mesh

Why traditional databases fail at scale, what the 5 Vs really mean, and a practical map of the big data ecosystem from ingestion to insights.

Big Data 101: The 5 Vs, Ecosystem, and Why Scale Breaks Everything

Not all Binary Trees are created equal. We explain Full, Complete, Perfect, and Balanced Binary T...

Exploring Different Types of Binary Trees

Master Big O notation: measure algorithm efficiency from O(1) to O(n²) with growth diagrams, worked examples, and the interview mental model.

Big O Notation Explained: Time Complexity, Space Complexity, and Why They Matter in Interviews

Binary search has five distinct patterns — classic, leftmost, rightmost, rotated arrays, and 2D matrices.

Binary Search Patterns: Five Variants Every Senior Engineer Knows

Step-by-step: annotate a Python function, test with MCP Inspector, containerize it, and register in Claude Desktop, Cursor, and VS Code.

Step-by-Step: How to Expose a Skill as an MCP Server

Build a Python MCP server, add auth and Docker, and register it in Claude Desktop, Cursor, and VS Code — deploy once, call from everywhere.

Headless Agents: Deploy Skills as MCP Servers — Full Guide from Concept to Three Clients

agentic-ai-langchain-and-langgraph

LangChain/LangGraph run workflows, MCP exposes capabilities, tools do actions, and skills package outcomes.

Skills vs LangChain, LangGraph, MCP, and Tools: A Practical Architecture Guide

## Scenario context

Turn any Python function into a multi-client MCP server in 11 steps — from annotation to Docker.

---

A developer pastes their `summarize_pr_diff` function into a Slack message because their teammate uses Cursor and can't call a Copilot skill. The function works perfectly. The sharing mechanism is broken. By the end of this post, that same function runs as an MCP server — callable from Cursor, Claude Desktop, and V…

This walkthrough focuses on **The Copy-Paste Problem: Why Skills Die at IDE Boundaries**.

Before making a design choice, clarify:

- A developer pastes their summarize pr diff function into a Slack message because their teammate uses Cursor and can't call a Copilot skill.
- The sharing mechanism is broken.
- By the end of this post, that same function runs as an MCP server — callable from Cursor, Claude Desktop, and VS Code Copilot simultaneously, with no copy-paste required.

**Concepts in play:** llm-agents-and-langgraph, system-design-hld-architectures, jvm-internals-and-garbage-collection, low-level-design-systems

## Stage 1 — Before You Start: What You Need and How MCP Registration Works

- Before running a single command, it helps to understand what the end state looks like so each step has a clear purpose.
- What you need installed: - Python 3.11+ with pip - Docker Desktop (for Step 7) - Claude Desktop, Cursor, or VS Code with GitHub Copilot (at least one to test registration) - curl for HTTP transport testing What "registe…
- When you open the client, it reads this config, attempts to start or connect to every listed server, and calls tools/list to discover available tools.
- If your server is running and returns a valid schema, the tools appear in the client's tool picker within seconds.

*Applies **llm-agents-and-langgraph** to the decision above.*

**Observable outcome:** If your server is running and returns a valid schema, the tools appear in the client's tool picker within seconds.

## Stage 2 — Steps 1–4: From Python Function to Locally Tested MCP Server

- These four steps take you from an empty directory to a fully verified local MCP server.
- Every subsequent step builds on this foundation.
- Step 1 — Set Up the Project Structure Create the directory layout and install dependencies: Your directory should look like this: The pyproject.toml declares the package and its runtime dependencies: FastMCP vs.
- bare mcp.server : FastMCP is a thin decorator layer over the official MCP Python SDK.

*Applies **system-design-hld-architectures** to the decision above.*

```bash
mkdir mcp-pr-summarizer && cd mcp-pr-summarizer
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install "mcp>=1.0" fastmcp openai
```

```
mcp-pr-summarizer/
├── server.py
├── pyproject.toml
└── Dockerfile
```

**Observable outcome:** bare mcp.server : FastMCP is a thin decorator layer over the official MCP Python SDK.

## Stage 3 — The Registration Journey: From Local Dev to Three Live Clients

- The diagram below shows the complete path from a working Python function to a tool registered across all three clients.
- Each arrow represents a concrete step in this post.
- The decision diamond at the centre is the key branch: stdio registration skips the Docker steps entirely and goes straight to client config files.
- SSE registration requires the running server (Steps 5–7) before the config files can point anywhere useful.

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```mermaid
flowchart TD
    A["✏ Write tool function (Steps 1–2)"] --> B["� Add error handling (Step 3)"]
    B --> C["� Test with MCP Inspector (Step 4)"]
    C --> D{Which transport?}
    D -->|"Local / single dev"| E["� Register via stdio (Step 8, 9, 10)"]
    D -->|"Shared / remote"| F["� Switch to HTTP+SSE (Step 5)"]
    F --> G[" Add bearer token auth (Step 6)"]
    G --> H["� Package as Docker container (Step 7)"]
    H --> I[" docker run -p 8080: 8080"]
    I --> J["� Register via SSE URL (Step 8, 9, 10)"]
    E --> K[" Claude Desktop sees tool"]
    J --> K
    K --> L[" Cursor sees tool"]
    L --> M[" VS Code Copilot sees tool"]
    M --> N["� Debug failures (Step 11)"]
```

**Observable outcome:** SSE registration requires the running server (Steps 5–7) before the config files can point anywhere useful.

## Stage 4 — Real-World Applications: How Teams Are Sharing Skills Across IDEs Today

- The platform-agnostic code review assistant.
- A mid-size engineering team has developers split across Cursor, Claude Desktop, and VS Code.
- They built a single MCP server that wraps three tools: summarize pr diff (this post's example), lint findings summary (summarizes ESLint/Flake8 output), and test coverage report (describes coverage gaps in plain English…
- The server runs as a Railway-hosted Docker container.

*Applies **low-level-design-systems** to the decision above.*

**Observable outcome:** The server runs as a Railway-hosted Docker container.

## Stage 5 — MCP Inspector: The Debugging Tool You'll Use Every Day

- The MCP Inspector ( mcp dev ) is the single most useful tool in the MCP development workflow.
- It is open-source, ships with the mcp[cli] package, and runs entirely locally — no cloud account required.
- What the Inspector UI shows: - Tools tab: Every tool your server advertises via list tools , with the full JSON Schema rendered as a human-readable form.
- If a tool is missing here, the client will never see it.

*Applies **llm-agents-and-langgraph** to the decision above.*

**Observable outcome:** If a tool is missing here, the client will never see it.

## Stage 6 — Practice Quiz

- Test your understanding of the MCP server deployment workflow.
- You run mcp dev server.py and your tool appears in the Inspector's Tools tab.
- You then add it to Claude Desktop's config file, fully restart the app, and the tool does not appear.
- What is the most likely cause?

*Applies **system-design-hld-architectures** to the decision above.*

**Observable outcome:** What is the most likely cause?

## End-to-end outcome

After working through the stages, you should be able to explain:

- After walking through eleven steps across three clients, here are the non-obvious lessons that save the most debugging time: 1.
- Write the docstring before the implementation.

## Alternatives considered

### Decision Guide: stdio for Local, SSE for Shared, Container for Team

The simplest production pattern for a small team: one Railway or Fly.io container running SSE on port 8080, bearer token authentication via environment variable, and a single shared config snippet that each developer pastes into their client config file.

### This section covers Steps 5–11: switching transports, adding auth, packaging in Docker, and writing the exact config file entries for each client.

This section covers Steps 5–11: switching transports, adding auth, packaging in Docker, and writing the exact config file entries for each client.

### Step 5 — Switch to HTTP+SSE Transport

Replace the stdio server entrypoint with SSE transport.

### Step 6 — Add Bearer Token Authentication

Wrap the SSE route with a simple Starlette middleware that checks the Authorization header: Set MCP AUTH TOKEN in your environment before starting the server:

### Step 7 — Package as a Docker Container

Use a multi-stage build to keep the image small.


## Failure and degraded modes

### Trade-offs and Failure Modes: What Breaks When You Register Across Clients

- **Detection:** Every cross-client MCP deployment surfaces failure modes that do not appear in local testing.
- **User or operator impact:** Every cross-client MCP deployment surfaces failure modes that do not appear in local testing.



## Scenario context

Build an MCP server once and call it from Cursor, Claude Desktop, and VS Code without rewrites — this guide takes you from a single Python function to a containerized, authenticated, three-client deployment in 11 concrete steps.

---

You spent an afternoon building a beautiful skill inside GitHub Copilot CLI: given a repository URL, it summarises the codebase, identifies the top changed files, and drafts a pull-req…

This walkthrough focuses on **The Trapped Skill Problem: When a Great LLM Tool Can't Leave the IDE It Was Born In**.

Before making a design choice, clarify:

- You spent an afternoon building a beautiful skill inside GitHub Copilot CLI: given a repository URL, it summarises the codebase, identifies the top changed files, and drafts a pull-request description.
- It works every time you run it.
- Then your teammate on Cursor asks if they can use it.

**Concepts in play:** llm-agents-and-langgraph, system-design-hld-architectures, jvm-internals-and-garbage-collection, low-level-design-systems

## Stage 1 — MCP Fundamentals: Protocol, Transports, and the Server Lifecycle

- MCP has three moving parts: a client (the AI assistant — Cursor, Claude Desktop, Copilot), a server (your Python process exposing tools), and a transport (the channel that connects them).
- The protocol is intentionally thin.
- At its core, MCP defines: - Tool registration — the server advertises a list of callable tools with JSON Schema-typed parameters.
- - Resource registration — the server can expose read-only data sources (files, database rows, API responses) the client can fetch.

*Applies **llm-agents-and-langgraph** to the decision above.*

**Observable outcome:** - Resource registration — the server can expose read-only data sources (files, database rows, API responses) the client can fetch.

## Stage 2 — Building Your MCP Server: From Empty Directory to Locally Tested Tool

- These four steps take you from nothing to a fully verified local MCP server.
- Every subsequent section builds on this foundation.
- Step 1 — Set Up the Project Structure Create the directory layout and install dependencies: Your directory should look like this: The pyproject.toml declares the package and its runtime dependencies: Step 2 — Write the…
- You declare tools using two decorators: @server.list tools() for the capability announcement and @server.call tool() for the dispatcher.

*Applies **system-design-hld-architectures** to the decision above.*

```bash
mkdir mcp-pr-summarizer && cd mcp-pr-summarizer
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install "mcp>=1.0" fastmcp openai
```

```
mcp-pr-summarizer/
├── server.py
├── pyproject.toml
└── Dockerfile
```

**Observable outcome:** You declare tools using two decorators: @server.list tools() for the capability announcement and @server.call tool() for the dispatcher.

## Stage 3 — Deep Dive: How MCP Routes Messages Under the Hood

- The Internals: JSON-RPC 2.0, Capability Negotiation, and Message Framing MCP's wire format is JSON-RPC 2.0 — the same protocol powering Language Server Protocol (LSP).
- Every message has three fields: jsonrpc: "2.0" , a method string, and either params (for requests) or result / error (for responses).
- The initialization handshake is a two-step exchange: 1.
- The client sends initialize with its own capabilities (protocol version, supported features).

*Applies **jvm-internals-and-garbage-collection** to the decision above.*

```mermaid
flowchart TD
 Task["Task Type"]
 Changing{Requires frequent knowledge updates?}
 RAG["Use RAG (Dynamic retrieval)"]
 Finetune["Use Fine-tuning (Static weights)"]
 
 Task --> Changing
 Changing -->|Yes| RAG
 Changing -->|No| Finetune
```

**Observable outcome:** The client sends initialize with its own capabilities (protocol version, supported features).

## Stage 4 — From Local to Headless: HTTP+SSE Transport, Auth Middleware, and Docker

- With a locally tested server in hand, these three steps lift it into a shared deployment that any client on any machine can reach.
- The call flow diagram at the end of this section shows how both transports converge at the same handler.
- Step 5 — Switch to HTTP+SSE Transport Replace the stdio server entrypoint with SSE transport.
- The tool handlers are unchanged — only main() changes: Test it immediately with curl before adding auth: Step 6 — Add Bearer Token Authentication Wrap the SSE route with a Starlette middleware that checks the Authorizat…

*Applies **low-level-design-systems** to the decision above.*

```python
# server.py — updated main() for SSE
import uvicorn
from mcp.server.sse import SseServerTransport
from starlette.applications import Starlette
from starlette.routing import Route

sse = SseServerTransport("/messages/")

async def handle_sse(request):
 async with sse.connect_sse(request.scope, request.receive, request._send) as streams:
 await server.run(*streams, server.create_initialization_options())

starlette_app = Starlette(routes=[Route("/sse", endpoint=handle_sse)])

if __name__ == "__main__":
 uvicorn.run(starlette_app, host="0.0.0.0", port=8080)
```

```bash
python server.py &
curl -N http://localhost:8080/sse
# Should emit: data: {"type":"endpoint","uri":"/messages/?session_id=..."}
```

**Observable outcome:** The tool handlers are unchanged — only main() changes: Test it immediately with curl before adding auth: Step 6 — Add Bearer Token Authentication Wrap the SSE route with a Starlette middleware that checks the Authorizat…

## Stage 5 — Complete Worked Example: The Repo Summarizer From One Python File to Three Live Clients

- Here is the complete repo summarizer skill as a single deployable file, callable from Cursor, Claude Desktop, and GitHub Copilot simultaneously.
- This is the production-ready version combining everything from the preceding steps.
- The Complete Server File Dockerfile for Headless Deployment Deploy to Railway with railway up .
- The resulting URL ( https://repo-summarizer.railway.app ) is the endpoint you register in each client config.

*Applies **llm-agents-and-langgraph** to the decision above.*

```python
# repo_summarizer_server.py
import asyncio
import os
from mcp.server import Server
from mcp.server.sse import SseServerTransport
from mcp import types
from mcp.shared.exceptions import McpError
from mcp.types import ErrorData, INTERNAL_ERROR, INVALID_PARAMS
import httpx

app = Server("repo-summarizer")

@app.list_tools()
async def list_tools() -> list[types.Tool]:
 return [
 types.Tool(
 name="summarize_repo",
 description="Fetch recent commits and open PRs for a GitHub repo and return a structured summary.",
 inputSchema={
 "type": "object",
 "properties": {
 "repo": {"type": "string", "description": "owner/repo (e.g. anthropics/mcp)"},
 "days": {"type": "integer", "default": 7, "description": "Lookback window in days"}
 },
 "required": ["repo"]
 }
 )
 ]

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
 if name != "summarize_repo":
 raise McpError(ErrorData(code=INVALID_PARAMS, message=f"Unknown tool: {name}"))
 repo = arguments.get("repo", "").strip()
 if not repo or "/" not in repo:
 raise McpError(ErrorData(code=INVALID_PARAMS, message="repo must be in owner/repo format"))
 days = arguments.get("days", 7)
 token = os.environ.get("GITHUB_TOKEN", "")
 headers = {"Authorization": f"Bearer {token}"} if token else {}
 try:
 async with httpx.AsyncClient(headers=headers) as client:
 commits_resp = await client.get(
 f"https://api.github.com/repos/{repo}/commits",
 params={"per_page": 20}
 )
 prs_resp = await client.get(
 f"https://api.github.com/repos/{repo}/pulls",
 params={"state": "open", "per_page": 10}
 )
 commits = [c["commit"]["message"].split("\n")[0] for c in commits_resp.json()[:10]]
 prs = [f"#{p['number']}: {p['title']}" for p in prs_resp.json()[:5]]
 summary = (
 f"## {repo} — last {days} days\n\n"
 f"**Recent commits ({len(commits)}):**\n"
 + "\n".join(f"- {c}" for c in commits)
 + f"\n\n**Open PRs ({len(prs)}):**\n"
 + "\n".join(f"- {p}" for p in prs)
 )
 return [types.TextContent(type="text", text=summary)]
 except Exception as exc:
 raise McpError(ErrorData(code=INTERNAL_ERROR, message=f"GitHub API call failed: {exc}")) from exc
```

```dockerfile
FROM python:3.12-slim AS builder
WORKDIR /app
COPY pyproject.toml .
RUN pip install --no-cache-dir "mcp>=1.0" httpx uvicorn starlette

FROM python:3.12-slim AS runtime
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
COPY --from=builder /usr/local/bin /usr/local/bin
COPY repo_summarizer_server.py .
EXPOSE 8080
CMD ["python", "repo_summarizer_server.py"]
```

**Observable outcome:** The resulting URL ( https://repo-summarizer.railway.app ) is the endpoint you register in each client config.

## Stage 6 — FastMCP and MCP Inspector: Two Tools That Save Hours Every Week

- FastMCP: Type Hints as JSON Schema The raw mcp SDK is explicit and flexible, but its decorator pattern can feel ceremonial for small servers.
- FastMCP ( jlowin/fastmcp ) provides a @mcp.tool() decorator that mirrors FastAPI's ergonomics — Python type hints become the JSON Schema automatically, and you skip the list tools / call tool split entirely.
- The same repo summarizer in FastMCP: FastMCP extracts the function signature, docstring, and type hints to build the full JSON Schema automatically.
- The mcp.run() call defaults to stdio but accepts a transport="sse" argument for HTTP deployment.

*Applies **system-design-hld-architectures** to the decision above.*

```python
# fast_server.py
from fastmcp import FastMCP
import httpx, os

mcp = FastMCP("repo-summarizer")

@mcp.tool()
async def summarize_repo(repo: str, days: int = 7) -> str:
 """Fetch recent commits and open PRs for a GitHub repository and return a structured summary."""
 token = os.environ.get("GITHUB_TOKEN", "")
 headers = {"Authorization": f"Bearer {token}"} if token else {}
 async with httpx.AsyncClient(headers=headers) as client:
 commits = (await client.get(
 f"https://api.github.com/repos/{repo}/commits",
 params={"per_page": 20}, headers=headers
 )).json()
 prs = (await client.get(
 f"https://api.github.com/repos/{repo}/pulls",
 params={"state": "open", "per_page": 10}, headers=headers
 )).json()
 lines = [f"## {repo}", "", "**Commits:**"]
 lines += [f"- {c['commit']['message'].split(chr(10))[0]}" for c in commits[:10]]
 lines += ["", "**Open PRs:**"]
 lines += [f"- #{p['number']}: {p['title']}" for p in prs[:5]]
 return "\n".join(lines)

if __name__ == "__main__":
 mcp.run()
```

```mermaid
flowchart TD
 Pretrained["Pretrained Model (Frozen)"]
 LoRA["LoRA Adapter (Trainable)"]
 Finetune["Fine-tune on Custom Data"]
 Result["Fine-tuned Model"]
 
 Pretrained --> LoRA
 LoRA --> Finetune
 Finetune --> Result
```

**Observable outcome:** The mcp.run() call defaults to stdio but accepts a transport="sse" argument for HTTP deployment.

## End-to-end outcome

After working through the stages, you should be able to explain:

- Write the tool description before the implementation.
- The description field is the single most important field in your schema — not for humans, but for the LLM that routes calls to your tool.

## Alternatives considered

### With the server running — either locally via stdio or in Docker via SSE — these three steps write the exact config entries needed for each client. The diagram below maps the full journey from Steps 1–11 so you can see where you are in the process.

The decision diamond is the key branch: stdio registration skips the Docker steps entirely and goes straight to config files.

### Step 8 — Register in Claude Desktop

Claude Desktop reads its server registry from a JSON config file in the OS application support directory.

### Step 9 — Register in Cursor

Cursor reads MCP config from ~/.cursor/mcp.json in your home directory (global, applies to all projects) or from .cursor/mcp.json in your project root (workspace-scoped, only that project).

### Step 10 — Register in VS Code and GitHub Copilot Agent Mode

VS Code reads MCP config from .vscode/mcp.json in your workspace root.

### Decision Guide: stdio, SSE, or Container — Choosing Once and Choosing Right

The simplest production pattern for a small team: one Railway or Fly.io container running SSE on port 8080, bearer token authentication via environment variable, and a shared config snippet that each developer pastes into their client config file.


## Failure and degraded modes

### Trade-offs and Failure Modes: What Breaks When You Register Across Three Clients

- **Detection:** Every cross-client MCP deployment surfaces failure modes that do not appear in local testing.
- **User or operator impact:** Every cross-client MCP deployment surfaces failure modes that do not appear in local testing.

## Scenario context

These are not competing ideas. They are layers. Tools do one action. MCP standardizes access to actions and resources. LangChain and LangGraph orchestrate calls. Skills package business outcomes with contracts, guardrails, and evaluation. Most production confusion comes from mixing these layers.

---

### Internals: control plane vs execution plane

A useful split:

- **Control plane**: registry, routing policy, ris…

This walkthrough focuses on **Deep Dive: Why Layer Confusion Breaks Production Systems**.

Before making a design choice, clarify:

- Internals: control plane vs execution plane A useful split: - Control plane : registry, routing policy, risk gating, rollout rules - Execution plane : LangGraph graph run, MCP calls, tool invocation, retries If everythi…
- Skills sit at the boundary and stabilize product expectations while execution internals evolve.
- Mathematical model: route score vs policy eligibility A practical routing pattern: $$ Eligible(s, q) = PolicyAllow(s, q) \land PermissionAllow(s, q) $$ Then score only eligible skills: $$ Score(s \mid q) = a \cdot Fit -…

**Concepts in play:** llm-agents-and-langgraph, graph-traversal-algorithms, tree-data-structures, design-patterns-gof

## Stage 1 — The Layer Cake: What Each Term Actually Means

- A product team shipped a customer support agent that worked in every demo.
- In production, it returned inconsistent refund decisions — sometimes citing correct policy, sometimes hallucinating eligibility rules — because the "agent" was a single LangGraph workflow with no output contract and no…
- The problem was not the model.
- The problem was missing layers.

*Applies **llm-agents-and-langgraph** to the decision above.*

```mermaid
flowchart TD
 Goal[Define Agent Goal]
 Single{Single tool call or simple chain?}
 Stateful{Multi-step stateful workflow?}
 Contract{Need stable output contract?}
 Cross{Cross-system tool discovery?}

 LC["LangChain (prompt chains, tools)"]
 LG["LangGraph (stateful graph, retries)"]
 Skill["Skill Layer (reusable capability)"]
 MCP["MCP (cross-system protocol)"]
 Both[LangGraph + Skill Layer]

 Goal --> Single
 Single -->|Yes| LC
 Single -->|No| Stateful
 Stateful -->|Yes| Contract
 Contract -->|No| LG
 Contract -->|Yes| Both
 Cross -->|Yes| MCP
 Both --> Cross
```

```mermaid
sequenceDiagram
 participant R as Router
 participant NA as Node A
 participant E as Edge Condition
 participant NB as Node B
 participant NC as Node C
 participant Term as END

 R->>NA: Start graph execution
 NA->>NA: Process state
 NA->>E: Evaluate conditional edge
 E-->>NB: Condition = "path_b"
 NB->>NB: Process state
 NB->>Term: Transition to END
 Note over NC: Node C not executed. Conditional branch skipped.
```

**Observable outcome:** The problem was missing layers.

## Stage 2 — Where LangChain and LangGraph Fit, and Where They Do Not

- LangChain and LangGraph are implementation frameworks.
- They help you execute reasoning and workflows.
- They do not automatically define product-level ownership, risk boundaries, or capability lifecycle.
- They build one graph and call it a "skill".

*Applies **graph-traversal-algorithms** to the decision above.*

**Observable outcome:** They build one graph and call it a "skill".

## Stage 3 — End-to-End Execution Path: How the Layers Collaborate

- Let us trace one request: "Investigate payment failure spikes and open an incident if needed." This flow exposes the distinction clearly: - LangGraph is the runtime engine for state transitions.
- - MCP is the interoperability channel for tools/resources.
- - Skill wraps the whole thing as a reusable product capability.
- Mini dataset for one run: The skill result is what downstream products depend on.

*Applies **tree-data-structures** to the decision above.*

```mermaid
flowchart TD
 A[User request] --> B[Router chooses PaymentIncidentSkill]
 B --> C[Skill validates input and policy]
 C --> D[LangGraph executes workflow state]
 D --> E[Node calls tools via MCP]
 E --> F[Collects logs metrics and ticket status]
 F --> G[Skill output validation]
 G --> H[Final structured response plus trace]
```

**Observable outcome:** Mini dataset for one run: The skill result is what downstream products depend on.

## Stage 4 — Real-World Applications: Real-World Patterns That Make This Practical

- Pattern 1: Product support copilot - Tools: CRM lookup, order API, refund API.
- - MCP: centralizes access to those systems.
- - LangGraph: executes decision branches (refund eligible or not).
- - Skill: RefundResolutionSkill returns decision , reason , next action .

*Applies **design-patterns-gof** to the decision above.*

**Observable outcome:** - Skill: RefundResolutionSkill returns decision , reason , next action .

## Stage 5 — Practical Example: One Capability Across All Layers

- Example 1: Tool and MCP-facing adapter This example traces a single payment incident investigation capability across all four architectural layers — raw tool function, skill contract with policy gate, LangGraph-orchestr…
- The multi-layer presentation was chosen deliberately because the most common architectural mistake in agent systems is forcing one layer to do the work of all the others.
- When reading the code, focus on where the output contract appears: only the skill layer enforces a stable typed return value, which is what makes downstream integrations predictable regardless of how the internal execut…
- Example 2: LangGraph workflow plus skill boundary This code is simple, but the design principle is important: output contract remains stable even if runtime internals change.

*Applies **llm-agents-and-langgraph** to the decision above.*

```python
# Tool function signature

def fetch_payment_metrics(service: str, window_minutes: int) -> dict:
 return {
 "service": service,
 "window_minutes": window_minutes,
 "error_rate": 0.087,
 "p95_latency_ms": 1230,
 }

# In practice this tool may be exposed through an MCP server with typed schemas.
```

```python
from dataclasses import dataclass

@dataclass
class PaymentIncidentInput:
 service: str
 window_minutes: int

def payment_incident_skill(payload: PaymentIncidentInput) -> dict:
 # 1) Validate boundary
 if payload.window_minutes <= 0:
 raise ValueError("window_minutes must be positive")

 # 2) Graph execution would happen here
 metrics = fetch_payment_metrics(payload.service, payload.window_minutes)

 # 3) Policy gate
 must_open_incident = metrics["error_rate"] >= 0.05

 # 4) Stable contract
 return {
 "service": payload.service,
 "error_rate": metrics["error_rate"],
 "incident_required": must_open_incident,
 "reason": "error_rate_threshold_breached" if must_open_incident else "within_limits",
 }
```

**Observable outcome:** Example 2: LangGraph workflow plus skill boundary This code is simple, but the design principle is important: output contract remains stable even if runtime internals change.

## Stage 6 — LangChain, LangGraph, and MCP: Concrete Implementation of the Four Layers

- LangChain provides the Runnable abstraction — chainable, composable steps with a uniform .invoke() / .stream() interface.
- LangGraph adds stateful graph execution with checkpointing and cyclic routing.
- MCP (Model Context Protocol) is an emerging open standard for exposing tools and data resources to LLMs over a typed protocol, enabling cross-framework capability sharing.
- This single code block illustrates the separation of concerns: the tool is an atomic function, the LangChain RunnableSequence handles linear orchestration, LangGraph manages stateful branching, and the skill wrapper exp…

*Applies **graph-traversal-algorithms** to the decision above.*

```python
# pip install langchain langchain-core langgraph
from langchain_core.runnables import RunnableLambda, RunnableSequence
from langgraph.graph import StateGraph, END
from typing import TypedDict, Optional

# --- Layer 1: Tool — one atomic action ---
def fetch_payment_metrics(service: str, window: int = 15) -> dict:
 """Retrieve error rate and latency; replace with real observability API."""
 return {"service": service, "error_rate": 0.072, "p95_ms": 980}

# --- Layer 2: LangChain Runnable chain — lightweight sequential orchestration ---
enrich_chain = RunnableSequence(
 RunnableLambda(lambda x: fetch_payment_metrics(x["service"])),
 RunnableLambda(lambda m: {**m, "alert": m["error_rate"] >= 0.05}),
)
# Use for simple, linear workflows: result = enrich_chain.invoke({"service": "pay-svc"})

# --- Layer 3: LangGraph stateful workflow — stateful branching and retry ---
class PaymentState(TypedDict):
 service: str
 metrics: Optional[dict]
 incident_id: Optional[str]

def fetch_step(state: PaymentState) -> PaymentState:
 return {**state, "metrics": fetch_payment_metrics(state["service"])}

def ticket_step(state: PaymentState) -> PaymentState:
 iid = f"INC-{abs(hash(state['service'])) % 9999:04d}"
 return {**state, "incident_id": iid}

def should_escalate(state: PaymentState) -> str:
 return "ticket" if state.get("metrics", {}).get("error_rate", 0) >= 0.05 else END

graph = StateGraph(PaymentState)
graph.add_node("fetch", fetch_step)
graph.add_node("ticket", ticket_step)
graph.set_entry_point("fetch")
graph.add_conditional_edges("fetch", should_escalate)
graph.add_edge("ticket", END)
workflow = graph.compile()

# --- Layer 4: Skill — stable product contract wrapping the graph ---
def payment_incident_skill(service: str) -> dict:
 """
 Public capability contract. Internal runtime can change without affecting callers.
 This is what the registry, router, and downstream systems depend on.
 """
 result = workflow.invoke({"service": service, "metrics": None, "incident_id": None})
 return {
 "service": result["service"],
 "error_rate": result.get("metrics", {}).get("error_rate"),
 "incident_id": result.get("incident_id") or "none",
 }

print(payment_incident_skill("payments-svc"))
```

**Observable outcome:** This single code block illustrates the separation of concerns: the tool is an atomic function, the LangChain RunnableSequence handles linear orchestration, LangGraph manages stateful branching, and the skill wrapper exp…

## End-to-end outcome

After working through the stages, you should be able to explain:

- - Tools, protocols, frameworks, and skills are complementary layers.
- - Framework quality does not replace capability modeling discipline.

## Alternatives considered

### Sequence View: Tool-Only Agent vs Skill-Centric Agent

A tool-only approach may skip S and return free-form text.

### Decision Guide: What to Build at Your Current Maturity

Quick rule set:


## Failure and degraded modes

### Trade-offs & Failure Modes: Trade-offs and Failure Modes

- **Detection:** You should not force everything into skills.
- **User or operator impact:** You should not force everything into skills.

Step 1

Build and deploy headless agents and custom skills as Model Context Protocol (MCP) servers.

Model Context Protocol (MCP)