DEV Community

krlz
krlz

Posted on

The Complete Guide to Model Context Protocol (MCP): Connect AI to Everything in 2025

#ai #programming #tutorial #typescript

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.

MCP is like USB-C for AI

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  │
   └─────────┘   └─────────┘   └─────────┘
Enter fullscreen mode Exit fullscreen mode

Three key players:

  1. Host - The AI application (Claude Desktop, Cursor IDE, your custom app)
  2. Client - Lives inside the host, manages connections to servers
  3. 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}` }] 
    };
  }
);
Enter fullscreen mode Exit fullscreen mode

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 }] };
  }
);
Enter fullscreen mode Exit fullscreen mode

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}` 
      }
    }]
  })
);
Enter fullscreen mode Exit fullscreen mode

Who's Actually Using MCP?

This isn't just an Anthropic thing anymore. The adoption has been massive:

Tech companies adopting new standards

Company How They're Using MCP
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
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

Step 3: Connect to Claude Code 

claude mcp add notes-server node /path/to/dist/index.js
Enter fullscreen mode Exit fullscreen mode

Or add to ~/.claude.json:

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/path/to/notes-mcp-server/dist/index.js"],
      "env": {
        "NOTES_DIR": "/Users/you/notes"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Now Claude can read, create, and manage your notes!

Setting Up MCP in Claude Code

Developer working on 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Top 10 MCP Servers You Should Know

Server What It Does Use Case
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" }
Enter fullscreen mode Exit fullscreen mode

2. Limit File Access 

{
  "filesystem": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "/Users/me/projects"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

3. Use Docker for Isolation 

docker run -d \
  --name mcp-github \
  -e GITHUB_TOKEN=$GITHUB_TOKEN \
  ghcr.io/modelcontextprotocol/server-github
Enter fullscreen mode Exit fullscreen mode

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"]
}
Enter fullscreen mode Exit fullscreen mode

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:

Top comments (0)