If you've been building AI applications, you've probably hit the same wall I did: getting your AI to actually do useful things with real data is a nightmare.
Your chatbot can write poetry, but can it check your GitHub PRs? Can it query your database? Can it read your Slack messages and actually help you?
That's where the Model Context Protocol (MCP) comes in. And trust me, once you understand it, you'll wonder how we ever built AI apps without it.
What is MCP, Really?
Think of MCP as USB-C for AI applications.
Just like USB-C gives you one standard port to connect your phone to chargers, monitors, keyboards, and everything else - MCP gives AI models one standard way to connect to databases, APIs, files, and tools.
Before MCP, if you wanted Claude to access your GitHub repos, you'd build a custom integration. Want it to also read Slack? Another custom integration. Database? Another one. Every AI app was reinventing the wheel.
MCP changes that. Build once, use everywhere.
The Architecture (Simple Version)
Let me break down MCP's architecture in a way that actually makes sense:
┌───────────────────────────────────────────────── ────────────┐
│ HOST │
│ (Claude Desktop, Cursor, Your App) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Client │ │ Client │ │ Client │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
└───────┼─────────────┼─────────────┼───────────── ────────────┘
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ GitHub │ │ Slack │ │Postgres │
│ Server │ │ Server │ │ Server │
└─────────┘ └─────────┘ └─────────┘
Three key players:
Each server is like a specialized translator. The GitHub server knows how to talk to GitHub. The Postgres server knows SQL. The AI just uses a standard protocol to talk to all of them.
What Can MCP Servers Actually Do?
MCP servers expose three types of capabilities:
1. Tools (Actions)
Things the AI can do. Create a PR, send a message, run a query.
// Example: A tool that creates GitHub issues
server.tool(
"create_issue",
"Create a new GitHub issue",
{
title: z.string(),
body: z.string(),
repo: z.string()
},
async ({ title, body, repo }) => {
const issue = await github.createIssue(repo, title, body);
return {
content: [{ type: "text", text: `Created issue #${issue.number}` }]
};
}
);
2. Resources (Data)
Information the AI can read. Files, database records, API responses.
// Example: Expose project files as resources
server.resource(
"file",
new ResourceTemplate("file://{path}", { list: undefined }),
async (uri) => {
const path = uri.pathname;
const content = await fs.readFile(path, "utf-8");
return { contents: [{ uri: uri.href, text: content }] };
}
);
3. Prompts (Templates)
Reusable instructions that guide how the AI interacts with tools.
// Example: Code review prompt template
server.prompt(
"code_review",
"Review code for best practices",
{ file: z.string() },
async ({ file }) => ({
messages: [{
role: "user",
content: {
type: "text",
text: `Review this file for bugs: ${file}`
}
}]
})
);
Who's Actually Using MCP?
This isn't just an Anthropic thing anymore. The adoption has been massive:
The message is clear: MCP is becoming the standard, not just an experiment.
Your First MCP Server (Step by Step)
Let's build a simple MCP server that gives Claude access to your local notes. This takes about 10 minutes.
Step 1: Set Up the Project
mkdir notes-mcp-server
cd notes-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
npx tsc --init
Step 2: Create the Server
Create src/index.ts:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import * as fs from "fs/promises";
import * as path from "path";
const NOTES_DIR = process.env.NOTES_DIR || "./notes";
const server = new McpServer({
name: "notes-server",
version: "1.0.0",
});
// Tool: List all notes
server.tool(
"list_notes",
"List all available notes",
{},
async () => {
const files = await fs.readdir(NOTES_DIR);
const notes = files.filter(f => f.endsWith(".md"));
return {
content: [{ type: "text", text: notes.join("\n") }]
};
}
);
// Tool: Read a specific note
server.tool(
"read_note",
"Read the contents of a note",
{ filename: z.string().describe("Name of the note file") },
async ({ filename }) => {
const filePath = path.join(NOTES_DIR, filename);
const content = await fs.readFile(filePath, "utf-8");
return {
content: [{ type: "text", text: content }]
};
}
);
// Tool: Create a new note
server.tool(
"create_note",
"Create a new note",
{
filename: z.string().describe("Name for the note file"),
content: z.string().describe("Content of the note")
},
async ({ filename, content }) => {
const filePath = path.join(NOTES_DIR, filename);
await fs.writeFile(filePath, content);
return {
content: [{ type: "text", text: `Created: ${filename}` }]
};
}
);
// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);
Step 3: Connect to Claude Code
claude mcp add notes-server node /path/to/dist/index.js
Or add to ~/.claude.json:
{
"mcpServers": {
"notes": {
"command": "node",
"args": ["/path/to/notes-mcp-server/dist/index.js"],
"env": {
"NOTES_DIR": "/Users/you/notes"
}
}
}
}
Now Claude can read, create, and manage your notes!
Setting Up MCP in Claude Code
Here's the practical guide for getting MCP working:
Basic Commands
# Add a server (HTTP transport - for remote servers)
claude mcp add notion --transport http https://mcp.notion.com/mcp
# Add a server (local stdio)
claude mcp add github -- npx -y @modelcontextprotocol/server-github
# List all servers
claude mcp list
# Remove a server
claude mcp remove github
Popular MCP Servers to Install
# GitHub - manage repos, PRs, issues
claude mcp add github -- npx -y @modelcontextprotocol/server-github
# Filesystem - read/write local files
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem /your/path
# PostgreSQL - query databases
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres
# Memory - persistent knowledge across sessions
claude mcp add memory -- npx -y @modelcontextprotocol/server-memory
# Git - repository operations
claude mcp add git -- npx -y @modelcontextprotocol/server-git
Top 10 MCP Servers You Should Know
Security Best Practices
MCP is powerful, which means security matters:
1. Never Hardcode Secrets
// Bad
"env": { "API_KEY": "sk-1234567890" }
// Good - use environment variables
"env": { "API_KEY": "$MY_API_KEY" }
2. Limit File Access
{
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/me/projects"
]
}
}
3. Use Docker for Isolation
docker run -d \
--name mcp-github \
-e GITHUB_TOKEN=$GITHUB_TOKEN \
ghcr.io/modelcontextprotocol/server-github
4. Audit Everything
Log every tool invocation with timestamps, user IDs, and inputs.
5. Short-Lived Tokens
Use OAuth 2.0 with short-lived tokens instead of long-lived API keys.
The Numbers: Why MCP Matters
Common Gotchas and Fixes
"Connection closed" on Windows
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-github"]
}
Server not showing tools
Restart Claude Code after adding servers.
Environment variables not working
Use full paths in your configuration.
What's Next for MCP?
The November 2025 spec brought:
Expect more first-party integrations from SaaS providers and better debugging tools.
Getting Started Checklist
Final Thoughts
MCP isn't just another protocol. It's the foundation for AI that actually does things.
We're moving from "AI that talks" to "AI that acts" - and MCP is the bridge.
The companies adopting it aren't doing it because it's trendy. They're doing it because it works.
If you're building anything with AI in 2025, you need to understand MCP. Start with one simple integration, see it work, and expand from there.
The future of AI is connected. MCP is how we get there.
Questions about MCP? Drop a comment - happy to help debug your setup!
Resources:
More...
Your chatbot can write poetry, but can it check your GitHub PRs? Can it query your database? Can it read your Slack messages and actually help you?
That's where the Model Context Protocol (MCP) comes in. And trust me, once you understand it, you'll wonder how we ever built AI apps without it.
What is MCP, Really?
Think of MCP as USB-C for AI applications.
Just like USB-C gives you one standard port to connect your phone to chargers, monitors, keyboards, and everything else - MCP gives AI models one standard way to connect to databases, APIs, files, and tools.
Before MCP, if you wanted Claude to access your GitHub repos, you'd build a custom integration. Want it to also read Slack? Another custom integration. Database? Another one. Every AI app was reinventing the wheel.
MCP changes that. Build once, use everywhere.
The Architecture (Simple Version)
Let me break down MCP's architecture in a way that actually makes sense:
┌───────────────────────────────────────────────── ────────────┐
│ HOST │
│ (Claude Desktop, Cursor, Your App) │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Client │ │ Client │ │ Client │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
└───────┼─────────────┼─────────────┼───────────── ────────────┘
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ GitHub │ │ Slack │ │Postgres │
│ Server │ │ Server │ │ Server │
└─────────┘ └─────────┘ └─────────┘
Three key players:
- Host - The AI application (Claude Desktop, Cursor IDE, your custom app)
- Client - Lives inside the host, manages connections to servers
- Server - Exposes tools, resources, and prompts to the AI
Each server is like a specialized translator. The GitHub server knows how to talk to GitHub. The Postgres server knows SQL. The AI just uses a standard protocol to talk to all of them.
What Can MCP Servers Actually Do?
MCP servers expose three types of capabilities:
1. Tools (Actions)
Things the AI can do. Create a PR, send a message, run a query.
// Example: A tool that creates GitHub issues
server.tool(
"create_issue",
"Create a new GitHub issue",
{
title: z.string(),
body: z.string(),
repo: z.string()
},
async ({ title, body, repo }) => {
const issue = await github.createIssue(repo, title, body);
return {
content: [{ type: "text", text: `Created issue #${issue.number}` }]
};
}
);
2. Resources (Data)
Information the AI can read. Files, database records, API responses.
// Example: Expose project files as resources
server.resource(
"file",
new ResourceTemplate("file://{path}", { list: undefined }),
async (uri) => {
const path = uri.pathname;
const content = await fs.readFile(path, "utf-8");
return { contents: [{ uri: uri.href, text: content }] };
}
);
3. Prompts (Templates)
Reusable instructions that guide how the AI interacts with tools.
// Example: Code review prompt template
server.prompt(
"code_review",
"Review code for best practices",
{ file: z.string() },
async ({ file }) => ({
messages: [{
role: "user",
content: {
type: "text",
text: `Review this file for bugs: ${file}`
}
}]
})
);
Who's Actually Using MCP?
This isn't just an Anthropic thing anymore. The adoption has been massive:
| OpenAI | Integrated into ChatGPT Desktop, Agents SDK |
| Google DeepMind | MCP support coming to Gemini models |
| Microsoft | Copilot Studio integration |
| Amazon AWS | Integration with AI services |
| Cursor | IDE-level MCP support |
| Replit | Enhanced AI coding features |
| Sourcegraph | Cody AI context awareness |
The message is clear: MCP is becoming the standard, not just an experiment.
Your First MCP Server (Step by Step)
Let's build a simple MCP server that gives Claude access to your local notes. This takes about 10 minutes.
Step 1: Set Up the Project
mkdir notes-mcp-server
cd notes-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
npx tsc --init
Step 2: Create the Server
Create src/index.ts:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import * as fs from "fs/promises";
import * as path from "path";
const NOTES_DIR = process.env.NOTES_DIR || "./notes";
const server = new McpServer({
name: "notes-server",
version: "1.0.0",
});
// Tool: List all notes
server.tool(
"list_notes",
"List all available notes",
{},
async () => {
const files = await fs.readdir(NOTES_DIR);
const notes = files.filter(f => f.endsWith(".md"));
return {
content: [{ type: "text", text: notes.join("\n") }]
};
}
);
// Tool: Read a specific note
server.tool(
"read_note",
"Read the contents of a note",
{ filename: z.string().describe("Name of the note file") },
async ({ filename }) => {
const filePath = path.join(NOTES_DIR, filename);
const content = await fs.readFile(filePath, "utf-8");
return {
content: [{ type: "text", text: content }]
};
}
);
// Tool: Create a new note
server.tool(
"create_note",
"Create a new note",
{
filename: z.string().describe("Name for the note file"),
content: z.string().describe("Content of the note")
},
async ({ filename, content }) => {
const filePath = path.join(NOTES_DIR, filename);
await fs.writeFile(filePath, content);
return {
content: [{ type: "text", text: `Created: ${filename}` }]
};
}
);
// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);
Step 3: Connect to Claude Code
claude mcp add notes-server node /path/to/dist/index.js
Or add to ~/.claude.json:
{
"mcpServers": {
"notes": {
"command": "node",
"args": ["/path/to/notes-mcp-server/dist/index.js"],
"env": {
"NOTES_DIR": "/Users/you/notes"
}
}
}
}
Now Claude can read, create, and manage your notes!
Setting Up MCP in Claude Code
Here's the practical guide for getting MCP working:
Basic Commands
# Add a server (HTTP transport - for remote servers)
claude mcp add notion --transport http https://mcp.notion.com/mcp
# Add a server (local stdio)
claude mcp add github -- npx -y @modelcontextprotocol/server-github
# List all servers
claude mcp list
# Remove a server
claude mcp remove github
Popular MCP Servers to Install
# GitHub - manage repos, PRs, issues
claude mcp add github -- npx -y @modelcontextprotocol/server-github
# Filesystem - read/write local files
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem /your/path
# PostgreSQL - query databases
claude mcp add postgres -- npx -y @modelcontextprotocol/server-postgres
# Memory - persistent knowledge across sessions
claude mcp add memory -- npx -y @modelcontextprotocol/server-memory
# Git - repository operations
claude mcp add git -- npx -y @modelcontextprotocol/server-git
Top 10 MCP Servers You Should Know
| Filesystem | Read/write local files | Development |
| GitHub | Repos, PRs, issues | Code reviews |
| PostgreSQL | Database queries | Data analysis |
| Slack | Messages, channels | Team communication |
| Memory | Persistent knowledge | Long-term context |
| Fetch | HTTP requests | API testing |
| Git | Version control | Code history |
| Puppeteer | Browser automation | Testing |
| Sequential Thinking | Multi-step reasoning | Problem solving |
| Google Drive | Document access | Content management |
Security Best Practices
MCP is powerful, which means security matters:
1. Never Hardcode Secrets
// Bad
"env": { "API_KEY": "sk-1234567890" }
// Good - use environment variables
"env": { "API_KEY": "$MY_API_KEY" }
2. Limit File Access
{
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/Users/me/projects"
]
}
}
3. Use Docker for Isolation
docker run -d \
--name mcp-github \
-e GITHUB_TOKEN=$GITHUB_TOKEN \
ghcr.io/modelcontextprotocol/server-github
4. Audit Everything
Log every tool invocation with timestamps, user IDs, and inputs.
5. Short-Lived Tokens
Use OAuth 2.0 with short-lived tokens instead of long-lived API keys.
The Numbers: Why MCP Matters
- 98.7% token reduction possible with code execution + MCP
- 60% fewer deployment issues with containerized MCP servers
- 78% of AI security incidents stem from poor access controls
- 3+ major AI platforms now support MCP
Common Gotchas and Fixes
"Connection closed" on Windows
{
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-github"]
}
Server not showing tools
Restart Claude Code after adding servers.
Environment variables not working
Use full paths in your configuration.
What's Next for MCP?
The November 2025 spec brought:
- Enhanced OAuth - Better enterprise auth
- Streamable HTTP - SSE deprecated for production
- Improved security docs - Official best practices
Expect more first-party integrations from SaaS providers and better debugging tools.
Getting Started Checklist
- [ ] Install Claude Code or your preferred MCP host
- [ ] Add your first server: claude mcp add memory
- [ ] Try GitHub integration with your token
- [ ] Explore official examples
- [ ] Build your first custom server
- [ ] Join the MCP community on GitHub
Final Thoughts
MCP isn't just another protocol. It's the foundation for AI that actually does things.
We're moving from "AI that talks" to "AI that acts" - and MCP is the bridge.
The companies adopting it aren't doing it because it's trendy. They're doing it because it works.
If you're building anything with AI in 2025, you need to understand MCP. Start with one simple integration, see it work, and expand from there.
The future of AI is connected. MCP is how we get there.
Questions about MCP? Drop a comment - happy to help debug your setup!
Resources:
More...