Picture this: you’ve got the most brilliant assistant in the world. Knows everything. Speaks 50 languages. Can explain quantum physics and write poetry at the same time. But here’s the catch — they’re locked in a glass box. They can see your computer screen. They can describe what they’d do if they could reach it. But touch anything? Nope. Read a file? Uh-uh. Check your calendar? Dream on.

That was AI assistants until very recently. Incredibly smart, utterly helpless. Like hiring Einstein to organize your sock drawer and then refusing to let him into the room.

Enter MCP — the Model Context Protocol. The thing that breaks the glass and lets your AI assistant actually do the thing.

MCP is essentially a USB standard for AI. Before USB, every device needed its own special plug. Now there’s one protocol, and everything just… works.

By the end of this article you’ll understand what MCP is, why it exists, how it works, and — most importantly — you’ll build your own working MCP server from scratch and connect it to Claude. Buckle up.

A Brief History of AI’s Helplessness Problem

To understand why MCP is a big deal, we need to appreciate just how spectacularly bad the situation was before it.

EARLY 2023

Large Language Models (LLMs) become genuinely impressive. Everyone rushes to build assistants. The dream: AI that manages your life. The reality: AI that describes your life back to you very eloquently.

MID 2023

“Function calling” arrives. Now you can tell the AI: “hey, you can call these functions.” Progress! But every app invents its own format. A plugin for ChatGPT works nowhere else. A LangChain tool chain doesn’t talk to Claude. It’s the Wild West, but with JSON.

LATE 2023–2024

Developers build increasingly elaborate custom integrations. Everyone reinvents the wheel. Slightly differently. Slightly wrongly. A thousand incompatible “AI tool” standards bloom. This is the Tower of Babel, Silicon Valley edition.

NOVEMBER 2024

Anthropic releases the Model Context Protocol. An open standard. One protocol to rule them all. The developer community collectively exhales. Finally.

2025

MCP adoption explodes. OpenAI, Google, Microsoft all announce support. Hundreds of MCP servers appear on GitHub. Your AI can now read files, browse the web, query databases, control your computer, send Slack messages, and order pizza. (Well, almost.)

The key insight Anthropic had was embarrassingly simple: instead of every AI model learning to speak every tool’s language, make every tool learn one common language. The result is MCP.

What Is MCP, Actually?

MCP stands for Model Context Protocol. It’s an open standard (meaning anyone can use it, free of charge) that defines how AI models communicate with external tools and data sources.

Think of it as a formal language that both sides agree to speak. The AI model is one speaker. Your tool (a file reader, a database, a weather API, your smart fridge) is the other speaker. MCP is the language between them.

The one-sentence explanation:
MCP lets AI models talk to any tool through a single standardized protocol, so you write the connector once and it works everywhere.

Technically, MCP is a client-server architecture built on top of JSON-RPC 2.0. Don’t be scared by that. It means messages are passed as readable JSON objects, and there’s a strict format for how requests and responses look. Clean, simple, predictable.

The Architecture: Three Amigos

MCP has three main characters. Let’s meet them:

The Host

The application running the AI. Could be Claude Desktop, VS Code with Copilot, or your own app. The host is the conductor — it decides when the AI needs a tool and coordinates everything.

The Client

Technically a component inside the host. It handles the actual MCP communication — sends requests to servers, gets back results, feeds them to the AI. You don’t usually build this yourself.

The Server

This is what you build. An MCP server exposes capabilities — tools, resources, and prompts — that the AI can use. Your server could wrap a database, a REST API, the local file system, or anything else. This is where the magic you write lives.

Core Concepts: Tools, Resources & Prompts

MCP servers expose three types of things to AI models. Think of these as different kinds of “capabilities”:

For most real-world use cases you’ll mainly deal with Tools. That’s where the action is.

How They Talk: The MCP Message Format

MCP messages are JSON objects following the JSON-RPC 2.0 specification. Every single message — whether it’s a greeting, a tool call, or an error — follows the same envelope structure. Once you learn the envelope, the rest is just filling in the blanks.

The Anatomy of Every Message

All JSON-RPC messages share the same top-level fields. Let’s dissect them:

Phase 1 — The Handshake: initialize

Before any tools are called, the host and server must introduce themselves. This is the very first exchange that happens when Claude Desktop spawns your server process. Think of it as two people shaking hands and agreeing on a common language before getting to business.

1A. HOST → SERVER: INITIALIZE REQUEST

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",        // MCP spec version the host supports
    "capabilities": {
      "roots": { "listChanged": true },    // Host can notify server about root changes
      "sampling": {}                         // Host supports LLM sampling requests
    },
    "clientInfo": {
      "name": "Claude Desktop",
      "version": "0.7.0"
    }
  }
}

1B. SERVER → HOST: INITIALIZE RESPONSE

{
  "jsonrpc": "2.0",
  "id": 0,                                    // Same id — this is the matching reply
  "result": {
    "protocolVersion": "2024-11-05",        // Server confirms the version
    "capabilities": {
      "tools": { "listChanged": false }    // Server exposes tools (and won't hot-reload them)
    },
    "serverInfo": {
      "name": "my-first-mcp-server",
      "version": "1.0.0"
    }
  }
}

1C. HOST → SERVER: INITIALIZED NOTIFICATION (NO REPLY EXPECTED)

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
  // No "id" field — this is a notification, not a request.
  // Notifications are fire-and-forget; the server never replies.
}

After this three-step handshake, the connection is live and both sides know what the other can do. Now the real fun begins.

Phase 2 — Tool Discovery: tools/list

The host immediately asks: “OK, what tools do you have?” This lets the AI know its full menu of capabilities before the user types a single character.

2A. HOST → SERVER: TOOLS/LIST REQUEST

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
  // No "params" needed — just asking for the full list.
}

2B. SERVER → HOST: TOOLS/LIST RESPONSE (WITH FULL INPUTSCHEMA)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather for any city.",
        "inputSchema": {          // Standard JSON Schema object
          "type": "object",
          "properties": {
            "city": {
              "type": "string",
              "description": "City name, e.g. Belfast"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"],   // Constrained to specific values
              "default": "celsius"
            }
          },
          "required": ["city"]            // "unit" is optional, "city" is not
        }
      },
      {
        "name": "search_database",
        "description": "Search products by keyword with optional filters.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": { "type": "string" },
            "limit": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            },
            "tags": {
              "type": "array",              // Arrays of primitives are fine
              "items": { "type": "string" }
            }
          },
          "required": ["query"]
        }
      }
    ]
  }
}

The inputSchema is standard JSON Schema. You can use type, enum, minimum, maximum, default, array, nested object — any JSON Schema feature. The AI model reads this schema and uses it to build valid arguments automatically. Good schemas = fewer mistakes by the AI.

Phase 3 — Tool Execution: tools/call

The user says something. The AI decides a tool is needed. It fires a tools/callwith the arguments it constructed from the schema.

3A. SIMPLE CALL — ONE STRING ARGUMENT

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "city": "Belfast"           // Only the required field; "unit" uses its default
    }
  }
}

3B. COMPLEX CALL — MULTIPLE TYPES INCLUDING ARRAY

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_database",
    "arguments": {
      "query": "wireless headphones",
      "limit": 5,                  // integer
      "tags": ["bluetooth", "noise-cancelling"]  // array
    }
  }
}

3C. SUCCESS RESPONSE — TEXT CONTENT

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Current weather in Belfast: 12°C, wind 18 km/h"
      }
    ],
    "isError": false          // Optional. Explicitly marks success.
  }
}

3D. SUCCESS RESPONSE — MULTIPLE CONTENT BLOCKS

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 2 results for 'wireless headphones':"
      },
      {
        "type": "text",         // Second block — same message, more content
        "text": "1. Sony WH-1000XM5 — £279\n2. Bose QC45 — £249"
      }
      // Could also include "image" blocks with base64 data,
      // or "resource" blocks referencing URIs
    ]
  }
}

Phase 4 — When Things Go Wrong: Error Responses

There are two distinct flavours of error in MCP. Don’t mix them up — they mean very different things.

PROTOCOL ERROR — THE REQUEST ITSELF WAS MALFORMED

{
  "jsonrpc": "2.0",
  "id": 4,
  "error": {                         // "error" field, NOT "result"
    "code": -32602,                  // Standard JSON-RPC error code
    "message": "Invalid params",
    "data": {
      "details": "Required field 'city' is missing"
    }
  }
}

TOOL-LEVEL ERROR — THE TOOL RAN BUT THE OPERATION FAILED

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {                        // Still "result", NOT "error" !
    "content": [
      {
        "type": "text",
        "text": "City 'Narnia' not found in geocoding database."
      }
    ],
    "isError": true               // Flag tells the AI: tool ran, but reported failure
  }
}

Key distinction: A protocol error (using the “error” field) means the communication broke — bad JSON, unknown method, missing required fields. A tool error (using “result” with “isError”: true) means the tool ran fine but the operation itself failed — user not found, city doesn’t exist, API returned 404. Always use isError: true for business logic failures so the AI can read the message and react intelligently.

Bonus: Resource Reads and Notifications

Tools aren’t the only thing MCP can do. Here’s what a resource read looks like — useful when you want to expose file contents or database records the AI can browse:

RESOURCES/READ REQUEST AND RESPONSE

// Request
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "resources/read",
  "params": {
    "uri": "file:///home/user/notes.txt"    // Resource URIs identify the data source
  }
}
// Response
{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "contents": [
      {
        "uri": "file:///home/user/notes.txt",
        "mimeType": "text/plain",
        "text": "Buy milk. Deploy the thing. Don't forget stand-up."
      }
    ]
  }
}

And a server notification — fire-and-forget messages the server sends without being asked (no id, no reply expected):

SERVER → HOST NOTIFICATION (NO REPLY)

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed",
  // No "id" — this is a push notification.
  // The server is telling the host: "Hey, my tool list changed.
  //  Please call tools/list again to refresh."
}

Clean and readable. No magic, no wizardry. Just JSON going back and forth. This predictability is exactly what makes MCP powerful — any language, any framework, any tool can implement it.

Two Ways to Connect: stdio vs HTTP/SSE

MCP servers can communicate via two transport mechanisms:

stdio (Standard I/O) — The simplest option. Your server reads from stdin and writes to stdout. The host app spawns the server as a subprocess. Perfect for local tools running on the same machine.

HTTP + SSE (Server-Sent Events) — For remote servers. The client sends POST requests to the server, and the server streams events back. Use this when your MCP server lives on a different machine (a cloud server, a colleague’s computer, etc.).

Start with stdio. It’s simpler, requires no networking setup, and is perfect for local tooling. You can always switch to HTTP later.

Tutorial: Building server.py Step by Step

Enough theory. Let’s write the actual code. Below is a complete, annotated server.py that exposes three tools: a dad joke generator, a task list, and a real live weather lookup. We’ll build it section by section so nothing is a mystery.

📦Install first: pip install mcp — that’s the only dependency. Python 3.10+ required.

Part 1 — Imports & Server Instantiation

The MCP SDK ships everything you need in the mcp package. We create a Server instance and tell it our name and version — this is what Claude Desktop sees in the handshake.

server.py — Part 1: imports and setup

# Standard library — no extra installs needed for HTTP calls
import asyncio
import random
import json
import urllib.request
import urllib.parse
import sys                   # needed for stderr debug output
# MCP SDK - install with: pip install mcp
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp import types
# Create the server. The name/version appear during the MCP handshake.
# Claude Desktop displays this name in its connected servers list.
app = Server("my-first-mcp-server")

Part 2 — Declaring Tools with @app.list_tools()

This decorator registers the handler that responds to tools/list requests. The AI calls this automatically on startup to discover your full menu of capabilities. The descriptions you write here are read by the AI — write them like you’re explaining the tool to a smart colleague, not a compiler.

server.py — Part 2: tool declarations

@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        # ── Tool 1: dad_joke ──────────────────────────────────────
        # No arguments. The inputSchema is an empty object.
        # The AI will call this whenever the user needs cheering up.
        types.Tool(
            name="dad_joke",
            description="Returns a random, gloriously terrible dad joke. Use when morale is low.",
            inputSchema={
                "type": "object",
                "properties": {},    # no arguments - jokes are free
                "required": [],
            },
        ),
        # ── Tool 2: get_tasks ─────────────────────────────────────
        # One required string argument: username.
        # "required" list enforces that the AI must supply it.
        types.Tool(
            name="get_tasks",
            description="Returns the task list for a given user.",
            inputSchema={
                "type": "object",
                "properties": {
                    "username": {
                        "type": "string",
                        "description": "The username whose tasks to fetch, e.g. 'alice'",
                    },
                },
                "required": ["username"],
            },
        ),
        # ── Tool 3: get_weather ───────────────────────────────────
        # Calls the real Open-Meteo API. No API key required.
        # "unit" is optional - has a default value in the handler.
        types.Tool(
            name="get_weather",
            description="Get current weather for any city. Uses Open-Meteo (free, no API key needed).",
            inputSchema={
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name, e.g. Belfast, Tokyo, New York",
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "description": "Temperature unit. Defaults to celsius.",
                    },
                },
                "required": ["city"],   # "unit" is optional - omit from required
            },
        ),
    ]

Part 3 — Handling Tool Calls with @app.call_tool()

When the AI decides to invoke a tool, this handler fires. It receives the tool name and the arguments dict the AI built from your schema. Return a list of TextContent objects — even if there’s only one. Always return a list; the protocol expects it.

server.py — Part 3: tool logic

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
# ── dad_joke ──────────────────────────────────────────────
    if name == "dad_joke":
        jokes = [
            "Why don't scientists trust atoms? Because they make up everything.",
            "I told my wife she was drawing her eyebrows too high. She looked surprised.",
            "Why do programmers prefer dark mode? Because light attracts bugs.",
            "I asked my dog what two minus two is. He said nothing.",
            "Why did the MCP server go to therapy? Too many unhandled exceptions.",
        ]
        return [types.TextContent(type="text", text=random.choice(jokes))]
    # ── get_tasks ─────────────────────────────────────────────
    # In real life you'd query a DB here. We use a dict for clarity.
    if name == "get_tasks":
        username = arguments.get("username", "").lower()
        fake_tasks = {
            "alice": ["Review PR #42", "Update docs", "Fix that bug you've been ignoring"],
            "bob":   ["Stand-up meeting", "Drink coffee", "Question all life choices"],
        }
        tasks = fake_tasks.get(username, ["No tasks found. Either very productive or very lazy."])
        formatted = "\n".join(f"{i+1}. {t}" for i, t in enumerate(tasks))
        return [types.TextContent(type="text", text=f"Tasks for {username}:\n{formatted}")]
    # ── get_weather ───────────────────────────────────────────
    # Two HTTP calls: geocode the city name → get weather by lat/lon.
    # Uses urllib (stdlib) so no extra dependencies.
    if name == "get_weather":
        city = arguments.get("city", "")
        unit = arguments.get("unit", "celsius")   # default if AI omits it
        # Step 1 - turn city name into coordinates
        geo_url = (
            "https://geocoding-api.open-meteo.com/v1/search"
            f"?name={urllib.parse.quote(city)}&count=1"
        )
        with urllib.request.urlopen(geo_url) as r:
            geo = json.loads(r.read())
        if not geo.get("results"):
            # Tool ran fine, but the operation failed - use isError flag
            return [types.TextContent(type="text", text=f'City "{city}" not found.')]
        result = geo["results"][0]
        lat, lon, found_name = result["latitude"], result["longitude"], result["name"]
        # Step 2 - fetch current weather for those coordinates
        wx_url = (
            "https://api.open-meteo.com/v1/forecast"
            f"?latitude={lat}&longitude={lon}"
            f"¤t_weather=true&temperature_unit={unit}"
        )
        with urllib.request.urlopen(wx_url) as r:
            wx = json.loads(r.read())
        cw = wx["current_weather"]
        symbol = "°C" if unit == "celsius" else "°F"
        return [types.TextContent(            type="text",            text=f"{found_name}: {cw['temperature']}{symbol}, wind {cw['windspeed']} km/h",        )]
    # Unknown tool - raise so MCP returns a proper protocol error
    raise ValueError(f"Unknown tool: {name}")

Part 4 — Wiring Up stdio Transport

The final piece connects the server to the MCP host via stdin/stdout. stdio_server() returns two async streams; we hand them to app.run() and it takes care of the rest. The key thing to remember: never print() to stdout anywhere in your code — that channel belongs to MCP. Debug with sys.stderr only.

server.py — Part 4: entry point

async def main():
    # stdio_server() yields (read_stream, write_stream) for the MCP host.
    # Everything inside this block is the server's lifetime.
    async with stdio_server() as (read_stream, write_stream):
        print("MCP server started", file=sys.stderr)   # stderr is safe for debug
        await app.run(
            read_stream,
            write_stream,
            app.create_initialization_options(),
        )
if __name__ == "__main__":
    asyncio.run(main())

💡Why async? MCP uses async I/O because servers often wait on multiple things at once — the host, network calls, file reads. Python’s asyncio lets a single thread handle all of that without blocking. You don’t need to understand the internals; just know that every handler must be async def, and use await before any I/O call.

Connecting Your Server to Claude Desktop

Once you’ve written your server.py, plugging it into Claude Desktop takes two minutes. Download Claude Desktop from claude.ai/download — it’s free and has an MCP client built in. Then locate the config file for your OS:

Register your server by adding it to that file:

CLAUDE_DESKTOP_CONFIG.JSON

{
  "mcpServers": {
    "my-first-mcp-server": {
      "command": "python",
      "args": [
        "/absolute/path/to/my-first-mcp-server/server.py"
      ],
      "env": {
        "MY_API_KEY": "sk-..."    // Pass secrets here; read with os.environ in Python
      }
    }
  }
}

Important: Use the absolute path to your server.py file. No tildes, no relative paths. Get the path with pwd on Mac/Linux or cd on Windows, and paste the full thing in.

Fully quit Claude Desktop (not just close the window) and reopen it. Look for the 🔧 tools icon in the chat input — that means MCP is connected. Then just ask Claude naturally: “Tell me a dad joke” or “What tasks does Alice have?” — it figures out on its own when to call your tools. No special syntax needed.

Best Practices (a.k.a. Mistakes I’m Saving You From)

Write excellent descriptions

The AI reads your tool descriptions to decide when to use them. Vague descriptions = confused AI = bad results. Be specific: what does the tool do, when should it be used, what do the arguments mean?

Never print() to stdout for debug output

In stdio transport, stdout is the MCP communication channel. Any stray print() call will corrupt the protocol stream. Always write debug output to stderr: print(“debug”, file=sys.stderr).

Validate your inputs

The AI sometimes passes unexpected values. Check that required arguments exist. Validate formats. Return helpful error messages rather than cryptic crashes.

Keep tools focused

One tool, one job. Don’t build a do_everything() tool. Small, well-named tools are easier for the AI to reason about and call correctly. Think Unix philosophy: do one thing well.

Use environment variables for secrets

Never hardcode API keys. Pass them via the env key in your claude_desktop_config.json: “env”: { “API_KEY”: “your-key-here” }. Read with os.environ[“API_KEY”] in your server.

The MCP Ecosystem: You Don’t Have to Build Everything

Here’s some great news: the open-source community has already built hundreds of MCP servers you can just plug in and use. Some highlights:

Find these and more at github.com/modelcontextprotocol/servers — the official repo — and on mcp.so, a community directory. There’s a good chance what you need already exists.

Wrapping Up: Why This Matters

MCP isn’t just a neat technical standard. It represents a fundamental shift in what AI assistants actually are.

Before MCP: AI as an oracle. You ask, it tells. Great for knowledge questions. Useless for action.

After MCP: AI as an agent. You describe what you want, it figures out which tools to use, calls them, interprets the results, and gets the job done. The AI becomes an active participant rather than a fancy search engine.

The future isn’t AI that can describe how to fix your code. It’s AI that fixes your code, runs the tests, creates the PR, and messages your team. MCP is the foundation that makes all of that possible.

You’ve now seen the full picture: the history, the architecture, the wire format, and a working server from scratch. The next step is yours. Pick a tool you use daily — a database, an API, a local service — and wrap it in an MCP server. Once you’ve done it once, you’ll find excuses to do it for everything.

Happy building. 🚀

The Agentic Loop (How Claude Actually Thinks)

Before anything else, you need to understand what makes Claude Code different from your IDE’s autocomplete. Autocomplete guesses the next word. Claude Code runs a loop — it gathers context, takes action, verifies results, then repeats until the task is done. Think of it less like a text editor feature and more like a developer who works asynchronously while you make coffee.

The loop has three phases that blend together depending on the task:

The loop adapts to what you ask. A question might only hit phase 1. A bug fix cycles through all three phases multiple times. A full feature might chain dozens of tool calls before Claude surfaces for air. You’re part of the loop too — you can interrupt at any point with Ctrl+C and steer it in a different direction.

THE HONEST SUMMARY

Claude Code is basically a language model with access to your entire computer strapped to it. It can read everything, run anything you could run from a terminal, and it just keeps going until it either finishes the task or you tell it to stop. This is either exhilarating or terrifying depending on how much you trust your test coverage.

Sessions & How Claude Remembers (Or Doesn’t)

Here’s the thing about Claude: every session starts with a completely blank memory. No recollection of last week’s chat. No memory of that convention you mentioned. Tabula rasa. Every. Single. Time. If you don’t explicitly persist knowledge, it’s gone when the session closes.

This isn’t a bug — it’s how LLMs work. But Claude Code gives you two mechanisms to work around it:

How a session actually starts

When you run claude in a directory, here’s what happens in the first few seconds before you’ve typed anything:

1. **Settings load (all scopes)**Global ~/.claude/settings.json → project .claude/settings.json → local .claude/settings.local.json. Scalar settings use the most specific value; array settings (like permissions) merge across all scopes.
2. MCP servers connectAll configured MCP servers from .mcp.json and ~/.claude.json start up. Tool schemas are deferred and load on demand. If a server fails to connect, Claude continues without it — it just loses those tools.
3. CLAUDE.md files load into contextOrg-level → user-level (~/.claude/CLAUDE.md) → project-level (./CLAUDE.md) → local (./CLAUDE.local.md). Plus your ~/.claude/MEMORY.md auto memory. All of this costs context window tokens immediately.
4. Plugins activateAll enabled plugins load their skills, hooks, MCP servers, and settings. Run /reload-plugins to activate changes mid-session.
5. Session is readyYou see the prompt. Everything above has already happened. Claude now has your project context and is ready to work.

CONTEXT WINDOW BUDGET

Everything loaded at startup costs tokens before you type a single character. A bloated CLAUDE.md, a dozen MCP servers, and a large MEMORY.md can eat a significant chunk of your context window. Run /status to see current token usage. Use /compact when a session gets long.

The .claude Directory — Every Folder Explained

The .claude/ folder is Claude Code’s configuration home in your project. There’s also ~/.claude/ in your home directory for global settings. Here’s the complete layout with every file and folder you’ll actually encounter:

COMMIT STRATEGY

Everything marked committed should go in Git so your whole team gets the same Claude setup. Everything marked gitignored is personal — Claude automatically adds settings.local.json to your global Git ignore. Add CLAUDE.local.md to your project’s .gitignore manually.

CLAUDE.md — The Full Story

You’ve heard about CLAUDE.md. Everyone mentions it. But few people explain the entire system behind it, which has four separate scope levels that load in a specific order:

They load in that order — managed first, local last. More specific scopes appear later in the context window, giving them higher effective priority.

What to actually put in CLAUDE.md

The golden rule: add something to CLAUDE.md when Claude makes the same mistake a second time. Here’s a battle-tested example for a Spring Boot project:

SIZE MATTERS

Target under 200 lines per CLAUDE.md. Longer files still load fully but adherence drops. If it’s getting long, split topic-specific rules into .claude/rules/ files and skills for complex procedures — they load conditionally and save your context window.

Auto Memory (MEMORY.md)

This is the magical part most people miss. Claude can write its own notes — automatically. When you correct Claude, it optionally remembers that correction for next session in ~/.claude/MEMORY.md. The first 200 lines or 25KB load at the start of every session.

Enable it with /memory in session or toggle it in settings. Then: tell Claude something once, it remembers it forever (until you delete the entry). This is how you get a Claude that feels like it’s been on your team for months.

settings.json — The Enforcement Layer

There’s a critical distinction most people miss: CLAUDE.md is guidance Claude reads.settings.json is configuration Claude Code enforces. One is a polite suggestion. The other is a locked door.

Settings live in .claude/settings.json (project/team) and .claude/settings.local.json(personal overrides). Here’s what you can configure:

ALLOW VS DENY PRECEDENCE

Deny rules always win over allow rules. If you allow Bash(kubectl *) and deny Bash(kubectl delete *), the delete command is blocked. Patterns support wildcards — Bash(npm test *)matches any command starting with npm test.

rules/ — Scoped Instructions That Load On Demand

Once your CLAUDE.md hits 200 lines, start splitting it into .claude/rules/. Rules are Markdown files that can load conditionally based on which files Claude is working with — only when it reads a file that matches the rule’s path pattern. This keeps your global context lean while ensuring Claude gets the right rules at the right time.

THE REAL POWER

A rule file without paths: frontmatter loads every session like CLAUDE.md. A rule WITH paths:only loads when Claude reads a matching file. This means your Kafka rules don’t eat context window during a CLAUDE.md update, and your migration rules only appear when Claude actually opens a migration file.

skills/ — Your Custom Slash Commands

Skills are reusable prompts you or Claude can invoke by name using /skill-name. Think of them as saved workflows — things you do repeatedly that are more than a one-liner but less than a custom tool. You write the instructions once in a SKILL.md, and invoke it whenever you need it.

Now you type /db-migrate and Claude walks through all seven steps. No more explaining the process from scratch every time. Skills also accept arguments via $ARGUMENTS:

Usage: /review-pr 127 — Claude reviews MR #127 with your exact conventions baked in.

SKILLS VS COMMANDS

You may see references to .claude/commands/ in older docs — this is the same mechanism as skills. For new workflows, use skills/ instead: same /name invocation, plus you can bundle supporting files alongside the SKILL.md.

Hooks — The Automation Engine

Hooks are shell commands that fire automatically at specific points in Claude’s lifecycle. They’re deterministic — they always run when triggered, regardless of what Claude decides. This is the difference between “please format the file” (Claude might forget) and “PostToolUse hook runs Spotless” (it definitely happens).

Available hook events

PreToolUseFires before any tool call. Can block execution (exit 2). Use to protect files or validate commands.

PostToolUseFires after a tool completes. Perfect for auto-formatting files after Claude edits them.

NotificationFires when Claude needs your input. Desktop notification so you don’t stare at the terminal.

SessionStartFires when a session begins. Inject additional context, set environment, run setup scripts.

PreCompactFires before conversation compaction. Re-inject context that would otherwise be lost.

StopFires when Claude finishes a response. Useful for post-response validation or logging.

Practical examples for a Java/Spring Boot project

EXIT CODES MATTER

exit 0 = allow. exit 1 = warn Claude but let it continue. exit 2 = hard block — Claude gets told why and has to try something else. It’s the digital equivalent of a bouncer who also explains the dress code.

MCP — Connecting Claude to the World

Model Context Protocol (MCP) is an open standard for connecting AI to external tools. Without MCP, Claude can only see your filesystem and run terminal commands. With MCP, Claude can query your Jira board, check Sentry errors, read Slack messages, query your PostgreSQL database, and more — all without you copying and pasting anything.

THE MENTAL MODEL

MCP is how Claude gets a login to your tools. Without it: “here’s a pasted error from Sentry.” With it: “Claude, check what errors happened in prod in the last hour and correlate them with my recent commits.”

Three types of MCP servers

Project-scoped MCP (.mcp.json)

Put your team’s MCP servers in .mcp.json at the project root. This file gets committed to Git so everyone on the team gets the same tools:

User-scoped MCP (personal tools)

For tools only you need (not your team), use the –scope user flag. This writes to ~/.claude.json instead of .mcp.json:

CHANNELS: MCP THAT PUSHES TO CLAUDE

Normal MCP is pull — Claude queries a server when it needs something. Channels flip this: an MCP server pushes messages into your running session. This means Claude can react to CI results, monitoring alerts, or Slack messages while you’re doing something else. Enable with –channelsflag on startup.

Plugins — Package & Share Everything

Everything you’ve built — skills, hooks, MCP servers, rules — can be packaged into a plugin and shared with your team, your org, or the whole world. Plugins are just directories with a .claude-plugin/plugin.json manifest. They’re the difference between “config that lives in one project” and “config that lives everywhere.”

Standalone config vs plugins

Plugin structure

Installing a plugin

THE REAL VALUE

Your platform team builds a plugin once with all the Spring Boot conventions, Kafka rules, code review skills, and MCP servers your org uses. Every developer installs it once. Every project gets the same setup. No more “did you add the Flyway rules to your CLAUDE.md?” Slack messages.

Subagents — Claude Spawning Claude

This is the part where things get genuinely science-fiction. Subagents let Claude spin up other Claude instances to handle subtasks in parallel or in isolated contexts. The main Claude orchestrates; the subagents execute. Think distributed computing, but the workers are also AI and can also spawn more workers.

Subagents can maintain their own MEMORY.md too. Imagine a “database specialist” subagent that remembers every schema change it’s ever helped with. That’s the direction this is heading.

WHEN TO USE SUBAGENTS

For most day-to-day tasks, you don’t need subagents. They’re most useful when you have truly parallel workstreams (implement feature A and feature B simultaneously without conflicts), when you need a clean context for a specific task, or when you’re building automation pipelines that run without human interaction.

Complete Quick Reference

• .claude/settings.json — permissions + hooks + model config. Enforced, not just read.
• CLAUDE.md — persistent instructions. Team version in ./CLAUDE.md, personal in ~/.claude/CLAUDE.md.
• MEMORY.md — auto-written by Claude. Persists learnings across sessions (200 lines / 25KB limit).
• .claude/rules/ — conditional instruction files. Use paths: frontmatter to load only for relevant files.
• .claude/skills/ — custom /commands. Each skill = a folder with SKILL.md. Accepts $ARGUMENTS.
• hooks — deterministic automation. PreToolUse (block/allow), PostToolUse (format), Notification (alert).
• .mcp.json — team MCP servers (committed). ~/.claude.json for personal servers.
• Plugins — packaged, shareable bundles of skills + hooks + MCP + settings. Install with /plugin install.
• Subagents — parallel Claude instances for complex multi-track workflows. Three isolation levels.
• /init — always run first in a new project. Generates CLAUDE.md automatically.
• /compact — compresses long sessions. /clear = fresh start (CLAUDE.md reloads).
• /mcp — shows server status + tool count. /hooks — shows configured hooks. /memory — edit CLAUDE.md.