MCP Deep-Dive

This document provides a comprehensive overview of the architecture and interaction between the MCP Client and MCP Server, highlighting the roles of Tools, Resources, and Prompts in the system.

---

Overview

The MCP (Model-Computer Protocol) facilitates structured interactions between the MCP Client and Server through three primary components:

• Tools : Model-controlled
• Resources : Application-controlled
• Prompts : User-controlled

---

Client-Server Interaction Diagram

+-----------------------+                   +-------------------+
|    MCP Client         | <-------------->  |    MCP Server     |
|-----------------------|                   |-------------------|
| Invokes Tools         |                   | Exposes Tools     |
| Queries for Resources |                   | Exposes Resources |
| Interpolates Prompts  |                   | Exposes Prompts   |
+-----------------------+                   +-------------------+

Deep Dive into MCP Components

1.Tools: Empowering AI with Actionable Functions

What are Tools?

• Executable functions that AI can invoke
• Designed to be automatically called by the AI model
• Provide concrete actions and computations

Characteristics:

• Model-controlled
• Can perform various actions like:
  • Retrieve/search data
  • Send messages
  • Update database records

What Makes a Tool Powerful?

Tools are the executable functions that transform AI from a passive information processor to an active problem-solver. They are the bridge between computational thinking and practical action.

Example (Math Calculator):

@mcp.tool()
def add(a: float, b: float) -> float:
    """
    Add two numbers together.
    
    Args:
        a: First number
        b: Second number
        
    Returns:
        Sum of a and b
    """
    return a + b

@mcp.tool()
def subtract(a: float, b: float) -> float:
    """
    Subtract the second number from the first.
    
    Args:
        a: Number to subtract from
        b: Number to subtract
        
    Returns:
        Difference between a and b
    """
    return a - b

@mcp.tool()
def multiply(a: float, b: float) -> float:
    """
    Multiply two numbers together.
    
    Args:
        a: First number
        b: Second number
        
    Returns:
        Product of a and b
    """
    return a * b

@mcp.tool()
def divide(a: float, b: float) -> str:
    """
    Divide the first number by the second.
    
    Args:
        a: Numerator
        b: Denominator
        
    Returns:
        Result of division or error message
    """
    if b == 0:
        return "Error: Division by zero is not allowed"
    return str(a / b)

Tool Design Principles

1. Atomic Functionality

   • Each tool should do one thing well
   • Focus on a specific, well-defined task
   • Avoid complex, multi-step operations

2. Robust Error Handling

   • Division by zero prevention
   • Type-safe operations
   • Clear error messaging

3. Type Annotations

   • Use Python type hints
   • Clearly define input and output types
   • Enable automatic validation

Advanced Tool Patterns

Async Tools

@mcp.tool()
async def fetch_weather(location: str) -> dict:
    """Fetch real-time weather data"""
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.weather.com/{location}")
        return response.json()

Tools with Complex Input Validation

from pydantic import BaseModel, Field
from typing import List

class EmailAnalysisRequest(BaseModel):
    emails: List[str] = Field(..., min_items=1, max_items=100)
    analysis_type: str = Field(default="basic")

@mcp.tool()
def analyze_emails(request: EmailAnalysisRequest) -> dict:
    """Perform comprehensive email analysis"""
    # Validated input automatically handled
    results = {
        'total_emails': len(request.emails),
        'analysis_type': request.analysis_type
    }
    return results

---

2.Resources: Data Access and Context

What are Resources?

• Expose data from various sources
• Controlled by the application
• Provide context and information

Characteristics:

• Application-controlled
• Can include various data types:
  • Files
  • Database records
  • API responses

Resource Types and Patterns

1. Static Resources

@mcp.resource("config://application")
def get_app_configuration() -> str:
    """Provide static application configuration"""
    return json.dumps({
        'version': '1.0.0',
        'environment': 'production',
        'features': ['authentication', 'logging']
    })

2. Dynamic Resources

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> dict:
    """Dynamically fetch user profile based on ID"""
    # Implement database or API lookup
    return user_database.get_profile(user_id)

Resource Access Patterns

1. Direct Resource Retrieval

# Fetch a specific resource
user_profile = client.read_resource("user://123/profile")

2. Resource Listing

# List available resources
available_resources = client.list_resources()

Example (Math Calculator Help Resource):

@mcp.resource("calculator://help")
def calculator_help() -> str:
    """Provide comprehensive calculator usage instructions"""
    return """
    # Basic Math Calculator Usage Guide

    ## Supported Operations
    - Addition: `add(a, b)` 
      - Adds two numbers together
    
    - Subtraction: `subtract(a, b)`
      - Subtracts the second number from the first
    
    - Multiplication: `multiply(a, b)`
      - Multiplies two numbers
    
    - Division: `divide(a, b)`
      - Divides first number by second
      - Prevents division by zero

    ## Example Usage
    - Add 5 and 3: `add(5, 3)` → Returns 8
    - Divide 10 by 2: `divide(10, 2)` → Returns 5.0
    """

When to Use Resources vs Tools

Resources and Tools serve different purposes in the MCP architecture, and understanding when to use each is crucial:

Use Resources When:

• You need to provide static or reference information
• The data doesn't need to perform an action, just be available
• The content should be explicitly selected by the user or application
• You want to provide context without computation
• Information needs to be cached or available throughout multiple interactions
• The data is read-only and doesn't change the system state

Use Tools When:

• You need to perform a computation or action
• The functionality requires user input to be processed
• The operation may change system state
• You want the AI model to automatically determine when to use the functionality
• The response depends on dynamic processing rather than static data
• The operation needs to interact with external systems or APIs

Key Differences:

• Control: Resources are application-controlled, whereas Tools are model-controlled
• Purpose: Resources provide data, Tools perform actions
• Invocation: Resources must be explicitly requested, Tools can be suggested by the AI
• State: Resources are typically read-only, Tools can modify state

---

3.Prompts: Guided AI Interactions

What are Prompts?

• Pre-defined interaction templates
• User-controlled workflow guidance
• Standardize complex interactions

Characteristics:

• User-controlled
• Provide structured interaction patterns

Potential Prompt Examples:

• Document Q&A
• Code review templates
• Analysis guidelines
• Structured output generation
• Transcript summaries
• JSON output generation

Understanding Prompts

Prompts are structured templates that guide AI interactions, providing context, constraints, and workflow patterns.

Prompt Anatomy

@mcp.prompt()
def math_problem_solving() -> List[Message]:
    """Guide users through mathematical problem-solving"""
    return [
        UserMessage("I need help solving a math problem."),
        AssistantMessage("I can help you use our calculator tools to solve it step by step."),
        SystemMessage("Encourage breaking down complex problems into simple operations.")
    ]

Prompt Design Strategies

1. Context Provision

   • Include relevant background information
   • Set clear expectations
   • Provide step-by-step guidance

2. Multi-stage Prompts

@mcp.prompt()
def troubleshooting_workflow(error_log: str) -> List[Message]:
    return [
        UserMessage(f"I'm experiencing this error: {error_log}"),
        AssistantMessage("Let's diagnose the issue step by step."),
        UserMessage("What have you already tried?"),
        SystemMessage("Guide the user through systematic troubleshooting.")
    ]

Resource Integration in Prompts

@mcp.prompt()
def project_analysis_prompt(project_files: List[Resource]) -> List[Message]:
    """Analyze project structure using multiple resources"""
    return [
        UserMessage("Please analyze the following project structure:"),
        ResourceMessage(project_files),
        AssistantMessage("I'll provide a comprehensive project assessment.")
    ]

How Prompts are Invoked in Claude Desktop

In Claude Desktop, prompts provide a structured way for users to engage with the AI. Here's how the prompt invocation process works:

1. Prompt Discovery:

   • Claude Desktop displays available prompts from connected MCP servers
   • These appear in a searchable menu, typically accessible via a "/" command
   • Prompts are categorized based on their server origins and functionality

2. Prompt Selection:

   • User selects a prompt from the menu
   • If the prompt requires arguments, Claude Desktop presents a form interface
   • The user fills in required parameters (e.g., selecting files, entering text input)

3. Execution Flow:

   • Claude Desktop sends a prompts/get request to the MCP server
   • The server processes the arguments and returns a sequence of messages
   • These messages are automatically inserted into the conversation
   • Claude responds to the structured prompt, following the intended workflow

4. Visual Indication:

   • Prompts appear visually distinct in the conversation
   • Users can see which server provided the prompt
   • The conversation maintains the context established by the prompt

This user-initiated approach ensures that prompts are explicitly chosen rather than automatically triggered, maintaining user control over the conversation flow.

Effective Prompt Engineering in MCP

Creating effective prompts in MCP requires understanding both the technical implementation and the principles of prompt engineering:

1. Clear Purpose and Context

   • Define the specific goal of each prompt
   • Provide sufficient context for the AI to understand the task
   • Include examples that demonstrate expected outputs

2. Structured Progression

   • Break complex workflows into logical steps
   • Use a sequence of messages to guide the interaction
   • Consider the conversation as a whole, not just individual messages

3. Balancing Specificity and Flexibility

   @mcp.prompt()
   def data_analysis_prompt(dataset_name: str) -> List[Message]:
       return [
           SystemMessage("You are a specialized data analyst. Follow these guidelines:"),
           UserMessage(f"Analyze the {dataset_name} dataset focusing on these aspects:"),
           UserMessage("1. Key metrics and distributions\n2. Anomalies or outliers\n3. Correlations between variables"),
           UserMessage("Please present your findings clearly, with important insights highlighted.")
       ]
   

4. Incorporating Dynamic Elements

   • Use template parameters to customize prompts for specific use cases
   • Pull in contextual information from resources when appropriate
   • Allow for user-specific customization where valuable

5. Testing and Refinement

   • Evaluate prompt effectiveness in real interactions
   • Refine based on user feedback and AI responses
   • Iterate on prompts to improve clarity and effectiveness

6. Documentation

   • Provide clear descriptions for each prompt
   • Document expected arguments and their formats
   • Include example scenarios to guide users

By applying these principles, you can create prompts that effectively guide AI interactions while maintaining flexibility for different user needs and contexts.

Bringing It All Together

The Model Context Protocol represents a significant evolution in how AI systems interact with data, tools, and user workflows. By understanding and effectively implementing Tools, Resources, and Prompts, developers can create rich, interactive experiences that leverage the strengths of both AI models and computational systems.

Each component plays a distinct yet complementary role:

• Tools enable action and computation
• Resources provide context and data
• Prompts structure and guide interactions

As you develop your own MCP servers, consider how each component can be leveraged to create intuitive, powerful AI experiences that solve real problems for your users. The best implementations will balance flexibility with structure, giving AI the guidance it needs while allowing it enough freedom to provide genuinely helpful responses.