|
| 1 | +# MCP Fundamentals - Core Concepts |
| 2 | + |
| 3 | +## What is MCP? |
| 4 | + |
| 5 | +**MCP = Model Context Protocol** |
| 6 | + |
| 7 | +It's a standardized way for AI models (like Claude) to interact with external systems. Instead of Claude having all knowledge and tools built-in, MCP lets you dynamically connect tools, data sources, and custom services. |
| 8 | + |
| 9 | +### The Problem It Solves |
| 10 | + |
| 11 | +Without MCP, here's how you'd give Claude access to a database: |
| 12 | + |
| 13 | +``` |
| 14 | +❌ Old Way: |
| 15 | +Claude Developer → Write custom API wrapper code |
| 16 | + → Handle authentication |
| 17 | + → Parse responses |
| 18 | + → Add error handling |
| 19 | + → Repeat for each tool |
| 20 | +``` |
| 21 | + |
| 22 | +With MCP: |
| 23 | + |
| 24 | +``` |
| 25 | +✅ MCP Way: |
| 26 | +Tool Creator → Build MCP Server (once) |
| 27 | + → Claude automatically knows how to use it |
| 28 | +Claude → No custom code needed |
| 29 | +``` |
| 30 | + |
| 31 | +## How MCP Works - The Flow |
| 32 | + |
| 33 | +Let's trace what happens when Claude needs to access a database: |
| 34 | + |
| 35 | +``` |
| 36 | +1. User: "What's in the user table?" |
| 37 | + └─→ Claude receives the question |
| 38 | +
|
| 39 | +2. Claude: "I need to query a database. Let me use the 'query-db' tool" |
| 40 | + └─→ Claude decides which tool to use |
| 41 | +
|
| 42 | +3. Claude → (via MCP) → Database Server |
| 43 | + Message: { "method": "tools/call", "params": { "name": "query-db", ... } } |
| 44 | + └─→ Sends JSON-RPC request over MCP |
| 45 | +
|
| 46 | +4. Database Server processes the request |
| 47 | + └─→ Queries the database |
| 48 | + Returns results |
| 49 | +
|
| 50 | +5. Server → (via MCP) → Claude |
| 51 | + Message: { "result": [ { "id": 1, "name": "Alice" }, ... ] } |
| 52 | + └─→ Sends JSON-RPC response |
| 53 | +
|
| 54 | +6. Claude: "The user table contains..." |
| 55 | + └─→ Answers the user using the results |
| 56 | +``` |
| 57 | + |
| 58 | +**Key insight**: MCP is JSON-RPC (Remote Procedure Call) over transport (stdio, HTTP, etc.) |
| 59 | + |
| 60 | +## The Three Main Concepts |
| 61 | + |
| 62 | +### 1. Tools |
| 63 | + |
| 64 | +**What**: Functions that Claude can call |
| 65 | + |
| 66 | +**Example**: A tool named `get-weather` that takes a city name and returns the weather |
| 67 | + |
| 68 | +```json |
| 69 | +{ |
| 70 | + "name": "get-weather", |
| 71 | + "description": "Get current weather for a city", |
| 72 | + "inputSchema": { |
| 73 | + "type": "object", |
| 74 | + "properties": { |
| 75 | + "city": { "type": "string" } |
| 76 | + }, |
| 77 | + "required": ["city"] |
| 78 | + } |
| 79 | +} |
| 80 | +``` |
| 81 | + |
| 82 | +**Why it matters**: Claude understands what the tool does, what inputs it needs, and when to use it |
| 83 | + |
| 84 | +**Real-world example**: |
| 85 | +- Query a database |
| 86 | +- Write a file |
| 87 | +- Call an external API |
| 88 | +- Execute a shell command |
| 89 | + |
| 90 | +### 2. Resources |
| 91 | + |
| 92 | +**What**: Readable data/information the server provides |
| 93 | + |
| 94 | +**Example**: A resource named `user-guide` that contains documentation |
| 95 | + |
| 96 | +Unlike tools (which are called with arguments), resources are just read. Claude can include them in its context to better understand how to solve problems. |
| 97 | + |
| 98 | +**Why it matters**: Helps Claude make better decisions by understanding your system's structure |
| 99 | + |
| 100 | +**Real-world example**: |
| 101 | +- Database schema documentation |
| 102 | +- File contents |
| 103 | +- API documentation |
| 104 | +- System configuration |
| 105 | + |
| 106 | +### 3. Sampling (Notifications) |
| 107 | + |
| 108 | +**What**: Server-initiated messages to Claude (not just Claude calling the server) |
| 109 | + |
| 110 | +**Why it matters**: Enables real-time notifications, event subscriptions, and streaming data |
| 111 | + |
| 112 | +**Real-world example**: |
| 113 | +- Alert when a server goes down |
| 114 | +- Stream log messages to Claude |
| 115 | +- Notify about job completion |
| 116 | + |
| 117 | +## Architecture Overview |
| 118 | + |
| 119 | +``` |
| 120 | +┌────────────────────────────────────────┐ |
| 121 | +│ Claude (Client) │ |
| 122 | +│ "I need to access external systems" │ |
| 123 | +└──────────────┬───────────────────────┘ |
| 124 | + │ |
| 125 | + │ MCP Protocol (JSON-RPC) |
| 126 | + │ Transport: stdio, HTTP, WebSocket, etc. |
| 127 | + │ |
| 128 | + ┌──────────┼──────────┬──────────┐ |
| 129 | + │ │ │ │ |
| 130 | +┌───▼──┐ ┌───▼──┐ ┌────▼───┐ ┌──▼────┐ |
| 131 | +│ File │ │ HTTP │ │Database│ │Custom │ |
| 132 | +│Server│ │Server│ │ Server │ │ Tools │ |
| 133 | +└──────┘ └──────┘ └────────┘ └───────┘ |
| 134 | + │ │ │ │ |
| 135 | + └─────────┼──────────┼──────────┘ |
| 136 | + │ │ |
| 137 | + (Each is an MCP Server) |
| 138 | +``` |
| 139 | + |
| 140 | +Each box (File Server, HTTP Server, etc.) is an **MCP Server** that Claude communicates with. |
| 141 | + |
| 142 | +## Request-Response Flow (Simplified) |
| 143 | + |
| 144 | +### 1. Claude Calls a Tool |
| 145 | + |
| 146 | +```json |
| 147 | +{ |
| 148 | + "jsonrpc": "2.0", |
| 149 | + "id": 1, |
| 150 | + "method": "tools/call", |
| 151 | + "params": { |
| 152 | + "name": "query-users", |
| 153 | + "arguments": { |
| 154 | + "status": "active" |
| 155 | + } |
| 156 | + } |
| 157 | +} |
| 158 | +``` |
| 159 | + |
| 160 | +**Breaking it down**: |
| 161 | +- `jsonrpc: "2.0"` - Protocol version (JSON-RPC standard) |
| 162 | +- `id: 1` - Request ID (to match with response) |
| 163 | +- `method: "tools/call"` - What we're asking for |
| 164 | +- `params` - The actual parameters (tool name + arguments) |
| 165 | + |
| 166 | +### 2. Server Responds |
| 167 | + |
| 168 | +```json |
| 169 | +{ |
| 170 | + "jsonrpc": "2.0", |
| 171 | + "id": 1, |
| 172 | + "result": [ |
| 173 | + { "id": 1, "name": "Alice", "status": "active" }, |
| 174 | + { "id": 2, "name": "Bob", "status": "active" } |
| 175 | + ] |
| 176 | +} |
| 177 | +``` |
| 178 | + |
| 179 | +**Breaking it down**: |
| 180 | +- `jsonrpc: "2.0"` - Same protocol version |
| 181 | +- `id: 1` - Matches the request ID |
| 182 | +- `result` - The actual result from the tool |
| 183 | + |
| 184 | +That's it! MCP is just a structured way to send requests and get responses. |
| 185 | + |
| 186 | +## Transport Layer |
| 187 | + |
| 188 | +MCP doesn't care *how* you send the messages. You can use: |
| 189 | + |
| 190 | +| Transport | Use When | Example | |
| 191 | +|-----------|----------|---------| |
| 192 | +| **stdio** | Local development, simple setup | Claude talks to server via stdin/stdout | |
| 193 | +| **HTTP** | Remote servers, web-based | Claude talks to server via HTTP requests | |
| 194 | +| **WebSocket** | Real-time communication | Live streaming of data to Claude | |
| 195 | +| **Custom** | Special needs | Use any protocol you want | |
| 196 | + |
| 197 | +**Most common**: stdio (for local development) and HTTP (for production) |
| 198 | + |
| 199 | +## Why MCP Matters for You |
| 200 | + |
| 201 | +### From Claude's Perspective |
| 202 | +✅ Can use external tools without developer rebuilding Claude |
| 203 | +✅ Tools are self-describing (built-in help) |
| 204 | +✅ No authentication logic needed |
| 205 | + |
| 206 | +### From Your Perspective |
| 207 | +✅ One standard way to integrate tools (not different APIs for each) |
| 208 | +✅ Easy to add/remove tools without changing Claude |
| 209 | +✅ Your tools can be used by any MCP client (not just Claude) |
| 210 | + |
| 211 | +### From a DevOps Perspective |
| 212 | +✅ Modular architecture (compose multiple tools) |
| 213 | +✅ Process isolation (each server is separate) |
| 214 | +✅ Configuration-driven (not hardcoded integrations) |
| 215 | + |
| 216 | +## A Real Example: The Database MCP Server |
| 217 | + |
| 218 | +Let's imagine you have a PostgreSQL database. You build an MCP server that: |
| 219 | + |
| 220 | +**Exposes these tools**: |
| 221 | +1. `query-users` - Search the users table |
| 222 | +2. `update-user` - Update a user record |
| 223 | +3. `create-user` - Add a new user |
| 224 | + |
| 225 | +**Exposes these resources**: |
| 226 | +1. `database-schema` - Documentation of the database structure |
| 227 | +2. `user-roles` - List of available user roles |
| 228 | + |
| 229 | +Now when you tell Claude "find all inactive users and update them", Claude: |
| 230 | +1. Reads the `database-schema` resource to understand the structure |
| 231 | +2. Calls `query-users` tool with `status: "inactive"` |
| 232 | +3. Gets back a list of inactive users |
| 233 | +4. Calls `update-user` for each user (or in a batch) |
| 234 | +5. Reports back to you with results |
| 235 | + |
| 236 | +**All without any custom code!** |
| 237 | + |
| 238 | +## Key Takeaway |
| 239 | + |
| 240 | +MCP is a bridge between Claude and your tools. It's: |
| 241 | +- **Standardized** - One way to integrate everything |
| 242 | +- **Simple** - Just JSON-RPC messages |
| 243 | +- **Composable** - Combine multiple servers |
| 244 | +- **Flexible** - Works with any language and transport |
| 245 | + |
| 246 | +--- |
| 247 | + |
| 248 | +**Next Step**: Ready to see how MCP actually works internally? Read [02-architecture.md](02-architecture.md) |
| 249 | + |
| 250 | +Or skip ahead if you want to start using it: [04-configuration.md](04-configuration.md) |
0 commit comments