Model Context Protocol (MCP) - A Complete Guide with Practical Examples

Introduction: What is MCP and Why Should You Care?

The Model Context Protocol (MCP) is an open standard that enables AI applications to securely connect to external data sources and tools. Think of it as a universal translator that allows AI models to interact with databases, APIs, file systems, and other services in a standardized, secure way.

Unlike traditional API integrations where each connection requires custom code, MCP provides a unified interface that AI models can use to access diverse external resources. This standardization dramatically reduces the complexity of building AI applications that need to interact with multiple data sources and tools.

The Problems MCP Solves

1. Integration Complexity

Traditional AI applications require custom integrations for each external service. Want to connect your AI to a database? Write custom code. Need file system access? More custom code. Each integration becomes a maintenance burden.

MCP Solution: One protocol, multiple connections. Write once, connect everywhere.

2. Security and Access Control

Giving AI models direct access to external systems poses significant security risks. How do you ensure the AI only accesses what it should?

MCP Solution: Built-in security model with fine-grained permissions and secure transport protocols.

3. Real-time Data Access

AI models often work with stale data or require complex workflows to access fresh information from external systems.

MCP Solution: Real-time streaming capabilities and efficient data synchronization.

4. Scalability Challenges

Managing multiple custom integrations becomes exponentially complex as your AI application grows.

MCP Solution: Standardized protocol that scales horizontally with consistent patterns.

Key Benefits of Using MCP

🔌 Plug-and-Play Architecture: Standard interfaces mean faster integration
🔒 Enhanced Security: Built-in authentication and authorization
📊 Real-time Data: Streaming capabilities for live data access
🚀 Improved Performance: Efficient transport protocols and caching
🛠️ Tool Interoperability: Consistent tool calling across different services
📈 Scalable: Easy to add new data sources and capabilities

Practical Examples

Let's explore how MCP works in practice through the examples. Each example demonstrates different aspects of MCP's capabilities.

Example 1: STDIO Transport with AI Integration

Purpose: Demonstrates how AI models can interact with MCP servers using standard input/output communication, enabling seamless integration with local tools and services.

Location: mcp-server/src/server/mcp-stdio-server.ts and mcp-server/src/client/stdio-client.ts

This example showcases:

// STDIO Server Setup
export class McpStdioServer {
  constructor() {
    this.server = new McpServer(
      {
        name: 'mcp-server-stdio',
        version: '1.0.0',
      },
      {
        capabilities: {
          tools: {},
          resources: {},
          prompts: {},
        },
      },
    )
  }

  async start(): Promise<void> {
    this.transport = new StdioServerTransport()
    await this.server.connect(this.transport)
  }
}

Key Features:

AI-Powered Client: Uses Google's Gemini AI to interact naturally with MCP tools
Interactive Interface: Command-line interface for testing MCP capabilities
Validation & Error Handling: Robust input validation and error management
Tool Discovery: Automatic discovery and usage of available MCP tools

Real-world Application: Perfect for local AI assistants, command-line tools, and development environments where the AI needs to interact with local services.

Example 2: HTTP Streamable Transport with Real-time Capabilities

Purpose: Demonstrates how MCP can work over HTTP with Server-Sent Events (SSE) for real-time data streaming, enabling web-based AI applications with live data feeds.

Location: mcp-server/src/server/mcp-stream-http-server.ts and mcp-server/src/client/stream-http-client.ts

This example implements:

export class MCPStreamHTTP {
  // Multi-session support for concurrent connections
  httpTransports: { [sessionId: string]: StreamableHTTPServerTransport } = {}

  async handlePostRequest(req: Request, res: Response) {
    // Handle MCP requests over HTTP
    if (!sessionId && this.isInitializeRequest(req.body)) {
      const transport = new StreamableHTTPServerTransport({
        sessionIdGenerator: () => randomUUID(),
      })
      await this.server.connect(transport)
    }
  }

  async handleGetRequest(req: Request, res: Response) {
    // Establish SSE streaming for real-time updates
    const transport = this.httpTransports[sessionId]
    await transport.handleRequest(req, res)
  }
}

Key Features:

Multi-Session Support: Handle multiple concurrent AI clients
Real-time Streaming: Server-Sent Events for live data updates
HTTP-based: Works with standard web infrastructure
Session Management: Persistent connections with unique session IDs

Real-world Application: Web-based AI dashboards, real-time monitoring systems, and collaborative AI applications where multiple users need live data updates.

Example 3: Comprehensive MCP Primitives - Tools, Resources, and Prompts

Purpose: Demonstrates the three core MCP primitives that enable rich AI interactions with external systems.

Location: mcp-server/src/mcp-primitives.ts

Tools: AI-Callable Functions

Tools allow AI models to perform actions in external systems:

// User Management Tools
this.server.registerTool(
  'createUser',
  {
    title: 'Create User',
    description:
      'Create a new user with first_name, last_name, email, and gender',
    inputSchema: {
      first_name: z.string().describe("User's first name"),
      last_name: z.string().describe("User's last name"),
      email: z.string().email().describe('Valid email address'),
      gender: z.string().describe("User's gender"),
    },
  },
  async ({ first_name, last_name, email, gender }) => {
    const userData = { first_name, last_name, email, gender }
    const newId = randomUUID()
    const response = await axios.post(`${JSON_SERVER_URL}/users`, {
      ...userData,
      id: newId,
    })

    return {
      content: [
        {
          type: 'text',
          text: `User created successfully with ID: ${newId}\n${JSON.stringify(
            response.data,
            null,
            2,
          )}`,
        },
      ],
    }
  },
)

Available Tools:

createUser: Create new users in the system
updateUser: Modify existing user information
deleteUser: Remove users from the system
startDataStream: Initiate real-time data streaming

Resources: Data Access Points

Resources provide AI models with access to external data:

// Resource for accessing all users
this.server.registerResource(
  'users',
  'users://all',
  {
    title: 'All Users',
    description: 'Retrieve all users from the system',
    mimeType: 'application/json',
  },
  async () => {
    const response = await axios.get(`${JSON_SERVER_URL}/users`)
    return {
      contents: [
        {
          uri: 'users://all',
          mimeType: 'application/json',
          text: JSON.stringify(response.data, null, 2),
        },
      ],
    }
  },
)

Available Resources:

users://all: Access to all users in the system
users://user/{id}: Access to specific user by ID

Prompt Templates: Structured AI Interactions

Prompt templates provide reusable patterns for AI interactions:

this.server.registerPrompt(
  'generate-user-prompt',
  {
    title: 'Generate User Creation Prompt',
    description: 'Generate a ready-to-use AI prompt for creating a user',
    argsSchema: {
      first_name: z.string().describe("User's first name"),
      last_name: z.string().describe("User's last name"),
      email: z.string().email().describe('Valid email address'),
      gender: z.string().describe("User's gender"),
    },
  },
  ({ first_name, last_name, email, gender }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Create a new user with the following information:
- First Name: ${first_name}
- Last Name: ${last_name}  
- Email: ${email}
- Gender: ${gender}

Please use the createUser tool to add this user to the system.`,
        },
      },
    ],
  }),
)

Example 4: Data Backend with JSON Server

Purpose: Provides a simple REST API backend that demonstrates how MCP can integrate with existing web services and databases.

Location: json-server/ directory

This component:

Mock Database: JSON-based data storage for testing
REST API: Standard HTTP endpoints for CRUD operations
Integration Target: Demonstrates how MCP tools can interact with external APIs

Configuration:

{
  "scripts": {
    "start": "json-server --watch users.json --port 4000"
  }
}

Real-world Application: Represents any REST API, database service, or web service that your AI applications need to interact with.

Architecture Overview

The complete system demonstrates a layered architecture with clear separation of concerns:

Real-world Applications

1. AI-Powered Customer Support

Tools: Create tickets, update customer info, search knowledge base
Resources: Access customer data, product documentation
Prompts: Standard response templates

2. Development Assistant

Tools: Run code, deploy applications, manage repositories
Resources: Access codebases, documentation, logs
Prompts: Code review templates, debugging guides

3. Business Intelligence

Tools: Generate reports, update dashboards, send notifications
Resources: Access databases, analytics platforms
Prompts: Report templates, analysis frameworks

4. Content Management

Tools: Publish articles, moderate comments, schedule posts
Resources: Access CMS data, media libraries
Prompts: Content creation templates

Getting Started

To run the examples in this repository:

Prerequisites

# Install dependencies
cd mcp-server && npm install
cd ../json-server && npm install

Start the Data Backend

cd json-server
npm start
# Server runs on http://localhost:4000

Run STDIO Example

cd mcp-server
npm run build

# Terminal 1: Start STDIO client with AI integration
node build/client/stdio-client.js

Run HTTP Streaming Example

# Terminal 1: Start HTTP server
node build/index.js

# Terminal 2: Start streaming client
node build/client/stream-http-client.js

Best Practices for MCP Implementation

1. Security First

Implement proper authentication
Use least-privilege access
Validate all inputs
Secure transport protocols

2. Error Handling

Graceful degradation
Clear error messages
Proper logging
Retry mechanisms

3. Performance

Efficient data serialization
Connection pooling
Caching strategies
Streaming for large datasets

4. Monitoring

Track usage metrics
Monitor performance
Log errors and warnings
Health checks

Conclusion

The Model Context Protocol represents a significant step forward in AI application development. By providing a standardized way for AI models to interact with external systems, MCP:

Reduces Development Time: Standard protocols mean less custom integration code
Improves Security: Built-in security models and transport encryption
Enables Real-time AI: Streaming capabilities for live data access
Scales Naturally: Consistent patterns that grow with your application

The examples in this repository demonstrate practical implementations that you can adapt for your own projects. Whether you're building local AI tools with STDIO transport or web-based applications with HTTP streaming, MCP provides the foundation for robust, scalable AI integrations.

Next Steps

Explore the Examples: Run through each example to understand the different transport methods
Adapt for Your Use Case: Modify the tools, resources, and prompts for your specific needs
Build Custom Integrations: Create your own MCP servers for your existing APIs and services
Join the Community: Contribute to the growing ecosystem of MCP tools and integrations

The future of AI applications lies in seamless integration with existing systems, and MCP provides the standardized foundation to make that future a reality.

Ready to start building? Clone this repository and explore the examples to see MCP in action!

Repository: MCP Crash Course Examples