Understanding the Model Context Protocol (MCP)

The Model Context Protocol (MCP) is a revolutionary standard that enables AI models to securely access and interact with external data sources, tools, and services. This guide will help you understand MCP's core concepts, architecture, and how it transforms AI application development.

🎯 What is MCP?

MCP is an open standard that provides:

🔌 Universal connectivity between AI models and external systems
🛡️ Secure, controlled access to tools and data
🏗️ Standardized architecture for AI-powered applications
🔄 Bidirectional communication between clients and servers
📈 Scalable integration patterns for complex systems

Think of MCP as the "HTTP for AI" - a protocol that makes it easy for AI models to interact with any system in a standardized way.

🏛️ Core Architecture

The MCP Ecosystem

┌─────────────────┐    MCP Protocol    ┌─────────────────┐
│                 │◄──────────────────►│                 │
│   MCP Client    │                    │   MCP Server    │
│                 │                    │                 │
│ (AI Model/App)  │                    │ (Tools/Data/AI) │
└─────────────────┘                    └─────────────────┘
        │                                        │
        │                                        │
        ▼                                        ▼
┌─────────────────┐                    ┌─────────────────┐
│   Claude AI     │                    │   File System   │
│   ChatGPT       │                    │   Database      │
│   Custom Apps   │                    │   APIs          │
│   Agents        │                    │   Services      │
└─────────────────┘                    └─────────────────┘

Key Components

MCP Client - Consumes capabilities (AI models, applications)
MCP Server - Provides capabilities (tools, resources, prompts)
Transport Layer - Communication mechanism (STDIO, HTTP, WebSocket)
Protocol Messages - Standardized request/response format

🔧 Core Concepts

1. Tools

Tools are functions that AI models can call to perform actions.

php

// Example: Calculator tool
$server->tool(
    'calculate',
    'Perform mathematical calculations',
    [
        'type' => 'object',
        'properties' => [
            'expression' => ['type' => 'string']
        ]
    ],
    function (array $args): array {
        $result = eval("return {$args['expression']};");
        return [
            'content' => [
                ['type' => 'text', 'text' => "Result: {$result}"]
            ]
        ];
    }
);

When to use Tools:

Performing actions (send email, create file, API calls)
Calculations or data processing
External service integration
System operations

2. Resources

Resources provide access to data that AI models can read.

php

// Example: File resource
$server->resource(
    'project-readme',
    'file:///project/README.md',
    'text/markdown',
    function (): array {
        return [
            'contents' => [[
                'uri' => 'file:///project/README.md',
                'mimeType' => 'text/markdown',
                'text' => file_get_contents(__DIR__ . '/README.md')
            ]]
        ];
    }
);

When to use Resources:

Static or dynamic data access
File system content
Database queries
API responses
Configuration data

3. Prompts

Prompts are reusable conversation templates that guide AI interactions.

php

// Example: Code review prompt
$server->prompt(
    'code_review',
    'Review code for best practices and issues',
    [
        [
            'name' => 'code',
            'description' => 'Code to review',
            'required' => true
        ],
        [
            'name' => 'language',
            'description' => 'Programming language',
            'required' => true
        ]
    ],
    function (array $args): array {
        return [
            'description' => 'Code Review Assistant',
            'messages' => [
                [
                    'role' => 'user',
                    'content' => [
                        [
                            'type' => 'text',
                            'text' => "Please review this {$args['language']} code:\n\n{$args['code']}"
                        ]
                    ]
                ]
            ]
        ];
    }
);

When to use Prompts:

Standardized AI interactions
Complex query templates
Domain-specific guidance
Workflow automation

4. Sampling

Sampling allows servers to request AI model completions.

php

// Example: Content generation
$completion = $client->requestSampling([
    'messages' => [
        [
            'role' => 'user',
            'content' => [
                ['type' => 'text', 'text' => 'Generate a summary of this data...']
            ]
        ]
    ],
    'maxTokens' => 500
])->await();

When to use Sampling:

Content generation
Data analysis
Decision making
Text transformation

🔄 Protocol Flow

Basic Request-Response Cycle

Client Discovery:

php

// Client discovers server capabilities
$capabilities = $client->initialize()->await();
$tools = $client->listTools()->await();
$resources = $client->listResources()->await();
$prompts = $client->listPrompts()->await();

Tool Execution:

php

// Client calls a tool
$result = $client->callTool('calculate', [
    'expression' => '2 + 2'
])->await();

Resource Access:

php

// Client reads a resource
$content = $client->readResource('file:///data/config.json')->await();

Prompt Usage:

php

// Client gets a prompt template
$prompt = $client->getPrompt('code_review', [
    'code' => $sourceCode,
    'language' => 'php'
])->await();

Message Types

Requests

initialize - Establish connection and capabilities
tools/list - Get available tools
tools/call - Execute a tool
resources/list - Get available resources
resources/read - Read resource content
prompts/list - Get available prompts
prompts/get - Get prompt template
sampling/createMessage - Request AI completion

Responses

Success responses with requested data
Error responses with error codes and messages
Progress notifications for long-running operations

Notifications

notifications/cancelled - Operation cancelled
notifications/progress - Progress updates
notifications/initialized - Initialization complete

🌐 Transport Layers

STDIO Transport

Best for: Command-line tools, desktop applications

php

// Server
$transport = new StdioServerTransport();

// Client
$transport = new StdioClientTransport(['php', 'server.php']);

Characteristics:

Process-to-process communication
Simple to implement and debug
Perfect for local integrations
Used by Claude Desktop

HTTP Transport

Best for: Web services, microservices, cloud deployments

php

// Server
$transport = new HttpServerTransport(['host' => 'localhost', 'port' => 8080]);

// Client
$transport = new HttpClientTransport('http://localhost:8080');

Characteristics:

Network-based communication
Scalable and distributed
Standard web protocols
Load balancing support

WebSocket Transport

Best for: Real-time applications, persistent connections, multiple concurrent clients

php

// Server with configuration
$transport = new WebSocketServerTransport([
    'host' => '127.0.0.1',
    'port' => 8080,
    'maxConnections' => 100
]);

// Client
$transport = new WebSocketClientTransport('ws://localhost:8080');

Characteristics:

Bidirectional real-time communication
Low latency
Persistent connections
Perfect for interactive applications

🔐 Security Model

Authentication

php

// OAuth 2.0 Bearer Token
$server->setAuthProvider(new OAuth2Provider([
    'bearer_token' => 'your-secure-token'
]));

// Custom Authentication
$server->setAuthProvider(new CustomAuthProvider([
    'validate' => function($credentials) {
        return validateUser($credentials);
    }
]));

Authorization

php

// Tool-level permissions
$server->tool(
    'admin_tool',
    'Administrative function',
    $schema,
    function($args, $context) {
        if (!$context->user->hasRole('admin')) {
            throw new McpError(ErrorCode::Forbidden, 'Admin access required');
        }
        // Tool logic here
    }
);

Safe Execution

php

// Input validation
$server->tool(
    'file_reader',
    'Read file contents',
    [
        'type' => 'object',
        'properties' => [
            'path' => [
                'type' => 'string',
                'pattern' => '^[a-zA-Z0-9./\-_]+$' // Restrict allowed characters
            ]
        ]
    ],
    function($args) {
        // Validate path is safe
        if (!isSafePath($args['path'])) {
            throw new McpError(ErrorCode::InvalidParams, 'Invalid path');
        }

        return readFile($args['path']);
    }
);

🏗️ Design Patterns

1. Service-Oriented Architecture

php

// Database Service Server
$dbServer = new McpServer(new Implementation('database-service'));
$dbServer->tool('query', 'Execute database query', $schema, $queryHandler);
$dbServer->tool('insert', 'Insert database record', $schema, $insertHandler);

// File Service Server
$fileServer = new McpServer(new Implementation('file-service'));
$fileServer->tool('read', 'Read file', $schema, $readHandler);
$fileServer->tool('write', 'Write file', $schema, $writeHandler);

// API Gateway Server
$apiServer = new McpServer(new Implementation('api-gateway'));
$apiServer->tool('proxy_request', 'Proxy API request', $schema, $proxyHandler);

2. Plugin Architecture

php

// Plugin Manager Server
class PluginServer extends McpServer {
    private array $plugins = [];

    public function loadPlugin(string $pluginClass): void {
        $plugin = new $pluginClass();

        // Register plugin tools
        foreach ($plugin->getTools() as $tool) {
            $this->tool($tool['name'], $tool['description'], $tool['schema'], $tool['handler']);
        }

        // Register plugin resources
        foreach ($plugin->getResources() as $resource) {
            $this->resource($resource['name'], $resource['uri'], $resource['mimeType'], $resource['handler']);
        }

        $this->plugins[] = $plugin;
    }
}

🚀 Real-World Use Cases

1. AI-Powered Development Tools

php

// Code Analysis Server
$server->tool('analyze_code', 'Analyze code quality', $schema, function($args) {
    $ast = parseCode($args['code']);
    $issues = analyzeAST($ast);
    return formatIssues($issues);
});

$server->tool('suggest_improvements', 'Suggest code improvements', $schema, function($args) {
    $suggestions = analyzeCodeQuality($args['code']);
    return formatSuggestions($suggestions);
});

$server->resource('project-metrics', 'project://metrics', 'application/json', function() {
    return ['contents' => [['uri' => 'project://metrics', 'mimeType' => 'application/json', 'text' => json_encode(getProjectMetrics())]]];
});

2. Business Process Automation

php

// CRM Integration Server
$server->tool('create_lead', 'Create new lead', $schema, function($args) {
    return $this->crmApi->createLead($args);
});

$server->tool('send_follow_up', 'Send follow-up email', $schema, function($args) {
    return $this->emailService->sendTemplate($args['template'], $args['contact']);
});

$server->resource('crm-pipeline', 'crm://pipeline', 'application/json', function() {
    return ['contents' => [['uri' => 'crm://pipeline', 'mimeType' => 'application/json', 'text' => json_encode($this->crmApi->getPipelineData())]]];
});

3. Content Management

php

// Content Server
$server->tool('generate_content', 'Generate content', $schema, function($args) {
    return $this->aiService->generateContent($args['prompt'], $args['style']);
});

$server->tool('optimize_seo', 'Optimize content for SEO', $schema, function($args) {
    return $this->seoService->optimizeContent($args['content']);
});

$server->resource('cms-templates', 'cms://templates', 'application/json', function() {
    return ['contents' => [['uri' => 'cms://templates', 'mimeType' => 'application/json', 'text' => json_encode($this->cms->getTemplates())]]];
});

🔮 Advanced Concepts

Error Handling

php

// Structured error responses
throw new McpError(
    ErrorCode::InvalidParams,           // Standard JSON-RPC error code
    'Invalid parameters',
    [
        'parameter' => 'email',
        'issue' => 'Invalid email format',
        'expected' => 'user@domain.com'
    ]
);

Progress Reporting

php

// Long-running operations with progress
$server->tool('process_large_file', 'Process large file', $schema, function($args) {
    $file = $args['file'];
    $totalLines = countLines($file);

    for ($i = 0; $i < $totalLines; $i++) {
        processLine($file, $i);

        // Report progress
        if ($i % 100 === 0) {
            $this->sendProgress([
                'progress' => $i / $totalLines,
                'message' => "Processed {$i}/{$totalLines} lines"
            ]);
        }
    }

    return ['content' => [['type' => 'text', 'text' => "Processed {$totalLines} lines successfully"]]];
});

Resource Subscriptions

php

// Dynamic resources that can change
$server->resource('system-stats', 'live://system-stats', 'application/json', function() {
    return [
        'contents' => [[
            'uri' => 'live://system-stats',
            'mimeType' => 'application/json',
            'text' => json_encode([
                'cpu' => getCpuUsage(),
                'memory' => getMemoryUsage(),
                'disk' => getDiskUsage(),
                'timestamp' => time()
            ])
        ]]
    ];
});

// Notify clients of changes
$server->onResourceChange('live://system-stats', function() {
    // Resource content has changed
});

🎓 Learning Path

Beginner Level

Start with Examples: Run hello-world server and client
Understand Tools: Create simple tools with basic input/output
Explore Resources: Add static and dynamic resources
Try Transports: Test STDIO and HTTP transports

Intermediate Level

Error Handling: Implement robust error handling
Authentication: Add security to your servers
Complex Tools: Build tools that interact with external APIs
Resource Management: Create dynamic, data-driven resources

Advanced Level

Custom Transports: Build custom transport layers
Protocol Extensions: Extend MCP for specialized use cases
Performance Optimization: Scale servers for production
Architecture Patterns: Design complex, distributed MCP systems

🌟 Benefits of MCP

For Developers

🚀 Rapid Development: Standard patterns and tools
🔒 Built-in Security: Authentication and authorization
🧪 Easy Testing: Standardized interfaces
📚 Rich Ecosystem: Growing library of servers and tools

For AI Applications

🎯 Focused Capabilities: Specific, well-defined tools
🔄 Dynamic Content: Real-time data access
🛡️ Controlled Access: Secure, permission-based operations
📈 Scalable Architecture: From simple tools to complex systems

For Organizations

🏗️ Standardized Integration: Consistent approach across teams
🔧 Modular Architecture: Composable, reusable components
📊 Better Governance: Centralized control and monitoring
💰 Cost Effective: Reduced development and maintenance costs

🎯 Next Steps

Now that you understand MCP's core concepts:

Try the Examples: Start with Quick Start and First Server
Build Something: Create a server for your specific use case
Explore Integration: Connect MCP to your existing systems
Join the Community: Contribute to the MCP ecosystem

MCP represents the future of AI-system integration - secure, standardized, and infinitely extensible. Welcome to the revolution! 🚀

Understanding the Model Context Protocol (MCP) ​

🎯 What is MCP? ​

🏛️ Core Architecture ​

The MCP Ecosystem ​

Key Components ​

🔧 Core Concepts ​

1. Tools ​

2. Resources ​

3. Prompts ​

4. Sampling ​

🔄 Protocol Flow ​

Basic Request-Response Cycle ​

Message Types ​

Requests ​

Responses ​

Notifications ​

🌐 Transport Layers ​

STDIO Transport ​

HTTP Transport ​

WebSocket Transport ​

🔐 Security Model ​

Authentication ​

Authorization ​

Safe Execution ​

🏗️ Design Patterns ​

1. Service-Oriented Architecture ​

2. Plugin Architecture ​

🚀 Real-World Use Cases ​

1. AI-Powered Development Tools ​

2. Business Process Automation ​

3. Content Management ​

🔮 Advanced Concepts ​

Error Handling ​

Progress Reporting ​

Resource Subscriptions ​

🎓 Learning Path ​

Beginner Level ​

Intermediate Level ​

Advanced Level ​

🌟 Benefits of MCP ​

For Developers ​

For AI Applications ​

For Organizations ​

🎯 Next Steps ​

Understanding the Model Context Protocol (MCP)

🎯 What is MCP?

🏛️ Core Architecture

The MCP Ecosystem

Key Components

🔧 Core Concepts

1. Tools

2. Resources

3. Prompts

4. Sampling

🔄 Protocol Flow

Basic Request-Response Cycle

Message Types

Requests

Responses

Notifications

🌐 Transport Layers

STDIO Transport

HTTP Transport

WebSocket Transport

🔐 Security Model

Authentication

Authorization

Safe Execution

🏗️ Design Patterns

1. Service-Oriented Architecture

2. Plugin Architecture

🚀 Real-World Use Cases

1. AI-Powered Development Tools

2. Business Process Automation

3. Content Management

🔮 Advanced Concepts

Error Handling

Progress Reporting

Resource Subscriptions

🎓 Learning Path

Beginner Level

Intermediate Level

Advanced Level

🌟 Benefits of MCP

For Developers

For AI Applications

For Organizations

🎯 Next Steps