DEV Community: Raghava Joijode

AI-Powered Content Management: Using MCP with AEM as a Cloud Service

Raghava Joijode — Tue, 03 Feb 2026 06:46:05 +0000

Whether you’re a developer orchestrating content workflows or a content author managing sites and assets, Adobe has integrated the Model Context Protocol (MCP) with AEM as a Cloud Service. This means you can now interact with AEM using natural language through AI tools like Claude, ChatGPT, Cursor, and Microsoft Copilot Studio—no API knowledge required.

What is MCP and Why Should You Care?

Model Context Protocol is a standardized way for applications to expose backend tools to Large Language Models (LLMs). Instead of manually crafting API calls, you can describe what you want in plain English, and the AI figures out which tools to use and how to chain them together.

Real example:
Instead of writing code to update content fragments across multiple pages, you can simply say:

“Update the hero banner for this spring campaign across all pages”

The LLM breaks this down, calls the right AEM MCP tools, and handles the implementation.

Who Benefits from MCP?

Different personas can leverage MCP in their preferred environments:

👨‍💻 Developers

Work in IDEs like Cursor to orchestrate content operations
Automate repetitive workflows with natural language commands
Integrate AEM operations into development pipelines

✍️ Content Authors & Practitioners

Manage sites, content fragments, and assets with AI assistance
Use familiar chat interfaces (ChatGPT, Claude) instead of AEM UI
Quickly find and update content across multiple pages

🏗️ Content Architects

Design and manage content fragment models
Coordinate large-scale content updates
Analyze content structure and relationships

Important: Authors should use the AI Assistant interface within AEM for operations that modify or delete content, as it includes built-in safeguards. MCP is better suited for developers orchestrating workflows and for read-only content exploration.

Key Benefits Across Teams

1. Natural Language Over Technical Complexity

No more memorizing API endpoints or AEM UI navigation paths. Describe what you need in plain English, and the AI handles the technical details.

Developer example:

“Create a new content fragment model for product reviews with fields for rating, title, and description”

Author example:

“Find all blog posts from last month that mention ‘sustainability’ and list their titles”

2. Consistent Experience Across Tools

Use the same AEM capabilities whether you’re in ChatGPT, Cursor, Claude, or Copilot Studio. Work in your preferred environment while accessing the same backend operations.

3. Security & Governance Preserved

All MCP operations run under your authenticated Adobe ID. Your existing AEM permissions apply—you can only do what you’re already authorized to do.

Available MCP Servers

Adobe provides two MCP endpoints at https://mcp.adobeaemcloud.com/adobe/mcp/:

Server	Endpoint	Purpose
Content	`/content`	Full CRUD operations for pages, fragments, and assets
Content (read-only)	`/content-readonly`	Safe read operations only

Supported Applications

AEM’s MCP integration works with:

✅ Anthropic Claude
✅ OpenAI ChatGPT
✅ Cursor IDE
✅ Microsoft Copilot Studio

Quick Setup Guide

Setting up MCP involves two steps:

Step 1: Configure Your MCP Client

The process is similar across all tools:

Add the AEM MCP Server URL
Example: https://mcp.adobeaemcloud.com/adobe/mcp/content-readonly
Authenticate with Adobe ID
You’ll be redirected to Adobe’s OAuth login
Your organization must permit the MCP client you’re using
Verify Tool Discovery
Once authenticated, the app discovers available AEM tools
You can list them by asking: “List all AEM MCP tools and what they do”

Step 2: Start Using It

Once configured, select the MCP server in your client and start prompting!

Real-World Workflows

Developer Workflows

Example 1: Automated Content Migration

Your prompt:

“List all content fragments using the old product model, export their data, and prepare a migration script to the new model”

What happens behind the scenes:

LLM lists all content fragment models
Searches for fragments using the specified model
Fetches fragment data including field values
Generates migration script with proper field mappings

Example 2: Environment Setup Verification

Your prompt:

“Check which environments are available and verify that all have the latest content fragment models deployed”

What happens:

Lists all environments and their licenses
Queries each environment for available models
Compares model versions across environments
Reports discrepancies

Content Author Workflows

Example 1: Bulk Content Updates

Your prompt:

“Update all product launch content fragments to reflect the new pricing for Q2”

What happens behind the scenes:

Searches for relevant content fragments
Resolves fragment paths to UUIDs
Fetches current fragment data
Applies updates using PATCH operations
Maintains optimistic concurrency with ETags

Example 2: Content Discovery & Publishing

Your prompt:

“Find all campaign banner images uploaded last week and show me which ones are published”

What happens:

Lists recent assets matching criteria
Filters by date and asset type
Checks publication status
Displays results with publishing state

Cross-Team Workflows

Example 3: Page Content Analysis

Your prompt:

“Get the hero banner content fragment used on the homepage and show me its current messaging”

What happens:

Retrieves page content
Extracts the fragment path
Resolves path to UUID
Fetches and displays fragment fields

Configuration Examples

For Developers: Cursor Setup

Ideal for developers who want AI assistance while coding:

Settings → MCP Servers
→ Add remote server
→ URL: https://mcp.adobeaemcloud.com/adobe/mcp/content
→ Complete Adobe OAuth flow
→ Enable/disable specific tools as needed

For Content Authors: Claude or ChatGPT Setup

Perfect for content teams who prefer chat-based workflows:

Claude:

Settings → Integrations → Model Context Protocol
→ Add server: https://mcp.adobeaemcloud.com/adobe/mcp/content-readonly
→ Authenticate with Adobe ID
→ Enable auto-confirm for read operations (optional)

ChatGPT:

Settings → Tools → Add MCP Server
→ URL: https://mcp.adobeaemcloud.com/adobe/mcp/content-readonly
→ Complete Adobe OAuth flow
→ Start querying your content

For Enterprise Teams: Microsoft Copilot Studio

Best for organizations wanting governed, shared access:

Create new agent → Tools → Add MCP Tool
→ URL: https://mcp.adobeaemcloud.com/adobe/mcp/content
→ Configure shared or dedicated connections
→ Set up auto-confirm or require user approval
→ Deploy across organization

Best Practices

⚠️ Critical Safety Note for Authors

Content authors should primarily use the AI Assistant interface within AEM for operations that modify or delete content. The AI Assistant has built-in safeguards specifically designed for content management scenarios.

MCP through external tools (ChatGPT, Claude, etc.) is powerful but requires more caution. Use it for:

✅ Content discovery and search
✅ Read-only analysis
✅ Exploring content structure
⚠️ Updates only after careful review

General Best Practices

1. Start with Read-Only for Exploration
Start with the /content-readonly endpoint when learning or exploring content. Switch to /content only when you need write access.

2. Review Before Confirming Writes
While some tools support auto-confirm, always review operations that modify or delete content. LLMs are powerful but not infallible.

3. Use Thinking Models for Complex Tasks
For multi-step operations or tasks involving different content types, enable “thinking mode” or similar features in your MCP client for better results.

4. Leverage Your Permissions
MCP respects your AEM role-based access. If you can’t do something manually in AEM, you can’t do it through MCP either.

Common Use Cases by Persona

For Developers

🔧 Environment Discovery: List available environments and licenses
🤖 Workflow Automation: Chain multiple operations for deployment pipelines
📊 Content Audits: Analyze content structure and model compliance
🔄 Bulk Migrations: Move content between models or environments

For Content Authors

📄 Content Search: Find pages and fragments by criteria
✏️ Quick Updates: Modify fragment fields across multiple instances
🖼️ Asset Management: Search, organize, and check publication status
📋 Content Reports: Generate lists of content matching specific criteria

For Content Architects

🧩 Model Management: Inspect and understand content fragment models
🔍 Structure Analysis: Map relationships between pages, fragments, and assets
📈 Usage Patterns: Identify which models and templates are most used
🎯 Governance: Ensure content follows established patterns and models

Authentication & Security

MCP uses OAuth integration with Adobe’s identity system:

Authenticate with your Adobe ID
System verifies the MCP client is permitted
Confirms the requested server is allowed
Issues tokens for subsequent tool calls
All operations respect your AEM permissions

This ensures AI-assisted work follows the same security model as manual operations.

Limitations to Know

Currently optimized for ChatGPT, Claude, Cursor, and MS Copilot Studio
Want to use a different client? Contact Adobe at aemcs-mcp-feedback@adobe.com
LLMs can occasionally produce inconsistent results—always verify outputs
Human oversight is essential, especially for production content

Managing MCP Access (Admins)

Administrators can:

Restrict specific MCP servers at organization, program, or environment level
Disable specific MCP clients based on organizational policies
Request support for additional clients by contacting Adobe

All MCP servers are allowed by default, and the four supported clients are pre-permitted.

Final Thoughts

MCP integration with AEM represents a fundamental shift in how different teams interact with content management systems:

Developers can orchestrate complex workflows using natural language instead of writing integration code
Content authors can query and explore content through familiar chat interfaces
Content architects can analyze and govern content structure more efficiently

The key is understanding which tool fits your workflow:

For developers: Cursor or Copilot Studio for IDE-integrated workflows
For content authors: ChatGPT or Claude for chat-based exploration (use AEM’s AI Assistant for content modifications)
For everyone: The /content-readonly endpoint for safe exploration

The technology is evolving rapidly. Tasks that require multiple prompts today may work seamlessly tomorrow. Start experimenting with read-only operations, build confidence, and always maintain human oversight for critical content operations.

Ready to get started?

Choose your preferred MCP client based on your role
Configure it with the appropriate AEM MCP endpoint
Authenticate with your Adobe ID
Start with simple read queries
Gradually expand to more complex workflows

Which persona are you—developer, author, or architect? How do you plan to use MCP with AEM? Share in the comments!

Resources:

Official AEM MCP Documentation

Revolutionising Content Management: An Introduction to AEM Business Agents

Raghava Joijode — Sun, 23 Nov 2025 17:06:43 +0000

While exploring Adobe Experience Manager's latest AI capabilities, I came across Business Agents in AEM as a Cloud Service. Here's what I learned about this interesting development in enterprise content management.

What I Discovered About Business Agents

Business Agents are essentially AI-powered assistants that live inside AEM as a Cloud Service. The interesting part is how Adobe has broken down different content management challenges into specialized agents rather than creating one general-purpose AI tool.

What caught my attention is that these aren't just experimental features—they're production-ready tools designed to handle real enterprise workflows. Though it's worth noting they're only available for AEM as a Cloud Service and Edge Delivery Services, not the older versions.

The Five Agents: My Observations

Experience Production Agent

This one tackles something I've seen teams struggle with constantly: keeping content fresh and consistent at scale.

What I found interesting:

It's specifically designed for high-volume, repetitive tasks
The claim is, it can turn weeks-long processes into days or hours
Seems focused on maintaining consistency across multiple touchpoints

My takeaway: This could be valuable for teams managing large product catalogs or multi-regional content where manual updates become a bottleneck.

Content Optimization Agent

This agent surprised me with its approach to asset editing. Instead of requiring specific tools or technical skills, it accepts natural language instructions.

Key observations:

You describe what you want in plain English, and it executes the edits
Can generate multiple variations for different channels automatically
Handles background changes, visual property adjustments, and rendition creation

Learning: This could significantly reduce the back-and-forth between content creators and design teams. Instead of "can you make this image work for mobile," you just tell the agent what you need.

Discovery Agent

I initially thought this was just another search tool, but there's more nuance here.

What makes it different:

Searches across multiple content types: Assets, Content Fragments, and Adaptive Forms
Claims to be "click-free"—interpreting intent rather than requiring exact queries
Understands context, not just keywords

Observation: In large AEM implementations where content is scattered across complex folder structures, this could save considerable time. The challenge with traditional search is knowing what you're looking for; this seems to help with the "I need something like..." scenarios.

Development Agent

As someone interested in development workflows, this one intrigued me.

What it aims to do:

Assist with code creation and debugging in the AEM context
Help with deployment and optimization
Support both developers and administrators

My thoughts: The value here likely depends on how well it understands AEM-specific patterns and best practices. Generic AI coding assistants exist, but one trained on AEM's architecture could be genuinely helpful for common tasks like component development or troubleshooting.

Governance Agent

This is the "compliance officer" of the group.

Key functions:

Enforces security and regulatory policies automatically
Maintains brand consistency
Validates content before publication

Learning: In regulated industries or large enterprises with strict brand guidelines, having automated policy enforcement could prevent costly mistakes. The interesting part is it works proactively rather than just flagging issues after they occur.

Platform Constraints Worth Noting

Through my research, I learned about some important limitations:

Available only on:

AEM as a Cloud Service
Edge Delivery Services

Not available on:

AEM 6.5 or 6.5 LTS
On-premises deployments
Managed Services

This is a significant consideration for organizations still running older AEM versions. Migration to Cloud Service is a prerequisite, which isn't always a trivial decision.

Bigger Picture Observations

Looking at Business Agents as a whole, a few patterns emerge:

Specialization over generalization: Rather than one AI that does everything, Adobe created specialized agents for specific workflows. This seems more practical than a single general-purpose assistant.

Natural language as interface: Multiple agents use plain English instructions. This lowers the barrier to entry for non-technical users, though I'm curious how well it handles ambiguous requests.

Automation of tedious work: The common thread is automating tasks that are necessary but time-consuming—the kind of work that teams often delay because it's high-effort and low-creativity.

Governance as a first-class concern: Including a dedicated Governance Agent signals that Adobe is thinking about enterprise requirements, not just productivity gains.

Questions I Still Have

While learning about these agents, some questions came up:

How do these agents learn from your specific organization's patterns and preferences?
What's the computational cost? Are there usage limits or pricing considerations?
How do they handle edge cases or ambiguous instructions?
What's the feedback mechanism when an agent gets something wrong?

Practical Implications

If I were evaluating these for a project, here's what I'd consider:

For content-heavy organizations: The Experience Production and Content Optimization agents could provide immediate ROI if you're constantly producing variations of similar content.

For teams with complex repositories: The Discovery Agent addresses a real pain point—finding content quickly without knowing exact locations or names.

For development teams: The Development Agent's value would depend heavily on the quality of its AEM-specific knowledge. Worth testing with real use cases.

For regulated industries: The Governance Agent could reduce compliance risk, but I'd want to understand exactly what policies it can enforce and how it's configured.

Final Thoughts

Business Agents represent Adobe's bet on AI for enterprise content management. The specialization approach makes sense—different workflows need different capabilities.

The cloud-only availability is both a limitation and a signal: Adobe is clearly focusing innovation on the Cloud Service platform. For organizations planning AEM implementations, this trend is worth considering.

What's most interesting to me is the shift from "AI as a feature" to "AI as a workflow participant." These agents aren't just enhancing existing tasks; they're potentially changing how teams structure their content operations.

Reference:

AEM Business Agents Documentation

Drop your thoughts in the comments or connect with me on LinkedIn. Are you considering Business Agents for your AEM implementation? What challenges are you hoping they’ll solve?

Production-Ready MCP Servers: Security, Performance & Deployment

Raghava Joijode — Tue, 18 Nov 2025 02:06:29 +0000

Part 3 of 3 in the MCP Server Series

In Part 1, we explored MCP concepts. In Part 2, we built a working server. Now it's time to make it production-ready.

Moving from a prototype to production means addressing security, performance, reliability, and maintainability. This post covers everything you need to deploy MCP servers safely at scale.

Series Navigation:

Part 1: Understanding MCP conceptually
Part 2: Building your first MCP server
Part 3 (This post): Security, performance, and production deployment

Security: The Most Critical Consideration

MCP servers can read your data, execute commands, and modify systems. Security isn't optional—it's existential.

The Core Security Model

Remember: MCP servers run locally by default. They communicate via stdio (standard input/output), not network ports. This provides baseline security:

✅ Process isolation - Only the parent application can communicate with the server

✅ No network exposure - Unlike REST APIs, stdio servers don't open ports

✅ Explicit configuration - Users must manually add servers to their config

But this isn't enough for production.

1. Authentication & Authorization

Even though MCP servers run locally, you should still validate requests:

import os
from functools import wraps

# Load from environment variable, not hardcoded
VALID_API_KEY = os.getenv("MCP_API_KEY")

def require_auth(func):
    """Decorator to enforce authentication on tool calls"""
    @wraps(func)
    async def wrapper(name: str, arguments: dict):
        auth_token = arguments.get("auth_token")

        if not auth_token or auth_token != VALID_API_KEY:
            return [TextContent(
                type="text",
                text="Authentication failed. Invalid or missing auth_token."
            )]

        # Remove auth_token from arguments before processing
        clean_args = {k: v for k, v in arguments.items() if k != "auth_token"}
        return await func(name, clean_args)

    return wrapper

@app.call_tool()
@require_auth
async def call_tool(name: str, arguments: dict):
    # Your tool implementation
    pass

Update your tool schemas to require auth:

Tool(
    name="get_customer",
    description="Retrieve customer information by ID",
    inputSchema={
        "type": "object",
        "properties": {
            "auth_token": {
                "type": "string",
                "description": "Authentication token (required)"
            },
            "customer_id": {
                "type": "string",
                "description": "Customer's unique ID"
            }
        },
        "required": ["auth_token", "customer_id"]
    }
)

2. Principle of Least Privilege

Never expose more than absolutely necessary:

# BAD: Exposing raw SQL execution
Tool(
    name="execute_query",
    description="Run any SQL query",
    inputSchema={"type": "object", "properties": {"sql": {"type": "string"}}}
)

# GOOD: Specific, limited operations
Tool(
    name="get_customer",
    description="Retrieve customer by ID (read-only)",
    inputSchema={"type": "object", "properties": {"customer_id": {"type": "string"}}}
)

Tool(
    name="update_customer_email",
    description="Update customer email only (requires admin)",
    inputSchema={
        "type": "object",
        "properties": {
            "customer_id": {"type": "string"},
            "new_email": {"type": "string"}
        }
    }
)

3. Input Validation & Sanitization

Always validate and sanitize inputs:

import re
from typing import Optional

def validate_customer_id(customer_id: str) -> Optional[str]:
    """Validate customer ID format"""
    # Only allow alphanumeric characters and hyphens
    if not re.match(r'^[a-zA-Z0-9-]+$', customer_id):
        return "Invalid customer ID format"

    # Check length
    if len(customer_id) > 50:
        return "Customer ID too long"

    return None

def validate_email(email: str) -> Optional[str]:
    """Basic email validation"""
    email_regex = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    if not re.match(email_regex, email):
        return "Invalid email format"
    return None

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_customer":
        customer_id = arguments.get("customer_id")

        # Validate input
        error = validate_customer_id(customer_id)
        if error:
            return [TextContent(type="text", text=f"Error: {error}")]

        # Safe to proceed
        customer = await get_customer_from_db(customer_id)
        # ...

4. SQL Injection Prevention

NEVER construct SQL queries with string concatenation:

# DANGEROUS - SQL Injection vulnerability
async def get_customer_bad(customer_id: str):
    query = f"SELECT * FROM customers WHERE id = '{customer_id}'"
    # If customer_id = "1' OR '1'='1", you've exposed everything!
    result = await conn.fetchrow(query)

# SAFE - Parameterized queries
async def get_customer_safe(customer_id: str):
    query = "SELECT * FROM customers WHERE id = $1"
    result = await conn.fetchrow(query, customer_id)
    return result

5. Secrets Management

Never hardcode secrets:

# BAD
DATABASE_URL = "postgresql://user:password123@localhost/db"
API_KEY = "sk-1234567890"

# GOOD - Use environment variables
import os

DATABASE_URL = os.getenv("DATABASE_URL")
API_KEY = os.getenv("API_KEY")

if not DATABASE_URL or not API_KEY:
    raise ValueError("Missing required environment variables")

For production, use proper secrets management:

AWS Secrets Manager
HashiCorp Vault
Azure Key Vault
Google Secret Manager

6. Rate Limiting

Prevent abuse with rate limiting:

from collections import defaultdict
from datetime import datetime, timedelta
import asyncio

class RateLimiter:
    def __init__(self, max_requests: int, time_window: int):
        self.max_requests = max_requests
        self.time_window = time_window  # seconds
        self.requests = defaultdict(list)

    def is_allowed(self, user_id: str) -> bool:
        now = datetime.now()
        cutoff = now - timedelta(seconds=self.time_window)

        # Remove old requests
        self.requests[user_id] = [
            req_time for req_time in self.requests[user_id]
            if req_time > cutoff
        ]

        # Check if under limit
        if len(self.requests[user_id]) >= self.max_requests:
            return False

        # Record this request
        self.requests[user_id].append(now)
        return True

# Create rate limiter: 100 requests per hour
rate_limiter = RateLimiter(max_requests=100, time_window=3600)

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    user_id = arguments.get("user_id", "default")

    if not rate_limiter.is_allowed(user_id):
        return [TextContent(
            type="text",
            text="Rate limit exceeded. Please try again later."
        )]

    # Process request
    # ...

7. Audit Logging

Log every operation for security monitoring:

import logging
import json
from datetime import datetime

# Configure structured logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    # Log the request
    logger.info(
        "MCP tool called",
        extra={
            "tool_name": name,
            "arguments": json.dumps(arguments),
            "timestamp": datetime.utcnow().isoformat(),
            "user_id": arguments.get("user_id", "unknown")
        }
    )

    try:
        result = await execute_tool(name, arguments)

        # Log success
        logger.info(
            "MCP tool completed successfully",
            extra={"tool_name": name, "user_id": arguments.get("user_id")}
        )

        return result
    except Exception as e:
        # Log failure
        logger.error(
            "MCP tool failed",
            extra={
                "tool_name": name,
                "error": str(e),
                "user_id": arguments.get("user_id")
            }
        )
        raise

Performance Optimization

Performance matters, especially when serving multiple AI agents or handling high request volumes.

1. Connection Pooling

Don't create new database connections for every request:

import asyncpg
from contextlib import asynccontextmanager

class DatabasePool:
    def __init__(self, database_url: str):
        self.database_url = database_url
        self.pool = None

    async def initialize(self):
        self.pool = await asyncpg.create_pool(
            self.database_url,
            min_size=5,
            max_size=20,
            command_timeout=60
        )

    async def close(self):
        if self.pool:
            await self.pool.close()

    @asynccontextmanager
    async def acquire(self):
        async with self.pool.acquire() as connection:
            yield connection

# Global pool instance
db_pool = DatabasePool(DATABASE_URL)

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_customer":
        async with db_pool.acquire() as conn:
            result = await conn.fetchrow(
                "SELECT * FROM customers WHERE id = $1",
                arguments["customer_id"]
            )
            return [TextContent(type="text", text=json.dumps(dict(result)))]

2. Caching

Cache frequently accessed data:

from functools import lru_cache
import asyncio
from datetime import datetime, timedelta

class AsyncCache:
    def __init__(self, ttl_seconds: int = 300):
        self.cache = {}
        self.ttl = ttl_seconds

    def get(self, key: str):
        if key in self.cache:
            data, timestamp = self.cache[key]
            if datetime.now() - timestamp < timedelta(seconds=self.ttl):
                return data
            else:
                del self.cache[key]
        return None

    def set(self, key: str, value):
        self.cache[key] = (value, datetime.now())

cache = AsyncCache(ttl_seconds=300)  # 5 minute cache

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_customer":
        customer_id = arguments["customer_id"]
        cache_key = f"customer:{customer_id}"

        # Check cache
        cached_data = cache.get(cache_key)
        if cached_data:
            logger.info(f"Cache hit for {cache_key}")
            return [TextContent(type="text", text=cached_data)]

        # Fetch from database
        async with db_pool.acquire() as conn:
            result = await conn.fetchrow(
                "SELECT * FROM customers WHERE id = $1",
                customer_id
            )
            data = json.dumps(dict(result))

            # Store in cache
            cache.set(cache_key, data)

            return [TextContent(type="text", text=data)]

3. Async Operations

Use async for I/O operations to handle concurrent requests efficiently:

import httpx
import asyncio

async def fetch_multiple_apis(customer_id: str):
    """Fetch data from multiple sources concurrently"""
    async with httpx.AsyncClient() as client:
        # Run these concurrently instead of sequentially
        results = await asyncio.gather(
            client.get(f"https://api1.com/customer/{customer_id}"),
            client.get(f"https://api2.com/orders/{customer_id}"),
            client.get(f"https://api3.com/preferences/{customer_id}"),
            return_exceptions=True  # Don't fail if one API is down
        )

        # Process results
        customer_data = {}
        for i, result in enumerate(results):
            if isinstance(result, Exception):
                logger.warning(f"API {i+1} failed: {result}")
            else:
                customer_data[f"source_{i+1}"] = result.json()

        return customer_data

4. Timeouts

Always set timeouts to prevent hanging operations:

import asyncio

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    try:
        # Set 30 second timeout
        result = await asyncio.wait_for(
            execute_tool_logic(name, arguments),
            timeout=30.0
        )
        return result
    except asyncio.TimeoutError:
        logger.error(f"Tool {name} timed out after 30 seconds")
        return [TextContent(
            type="text",
            text="Operation timed out. Please try again or contact support."
        )]

Error Handling & Resilience

Production systems fail. Handle it gracefully.

1. Comprehensive Error Handling

from typing import List
import traceback

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> List[TextContent]:
    try:
        # Validate tool exists
        if name not in AVAILABLE_TOOLS:
            return [TextContent(
                type="text",
                text=f"Unknown tool: {name}. Available tools: {', '.join(AVAILABLE_TOOLS)}"
            )]

        # Execute tool
        result = await execute_tool_logic(name, arguments)
        return result

    except ValueError as e:
        # User input errors
        logger.warning(f"Validation error in {name}: {e}")
        return [TextContent(type="text", text=f"Invalid input: {str(e)}")]

    except PermissionError as e:
        # Authorization errors
        logger.warning(f"Permission denied for {name}: {e}")
        return [TextContent(type="text", text="Permission denied. Please check your credentials.")]

    except asyncpg.PostgresError as e:
        # Database errors
        logger.error(f"Database error in {name}: {e}")
        return [TextContent(type="text", text="Database error. Please try again later.")]

    except httpx.HTTPError as e:
        # External API errors
        logger.error(f"External API error in {name}: {e}")
        return [TextContent(type="text", text="External service unavailable. Please try again later.")]

    except Exception as e:
        # Catch-all for unexpected errors
        logger.error(f"Unexpected error in {name}: {e}\n{traceback.format_exc()}")
        return [TextContent(
            type="text",
            text="An unexpected error occurred. The issue has been logged and will be investigated."
        )]

2. Retry Logic

Implement retries for transient failures:

import asyncio
from typing import TypeVar, Callable

T = TypeVar('T')

async def retry_with_backoff(
    func: Callable,
    max_attempts: int = 3,
    initial_delay: float = 1.0,
    backoff_factor: float = 2.0
) -> T:
    """Retry function with exponential backoff"""

    delay = initial_delay
    last_exception = None

    for attempt in range(max_attempts):
        try:
            return await func()
        except Exception as e:
            last_exception = e
            logger.warning(
                f"Attempt {attempt + 1}/{max_attempts} failed: {e}"
            )

            if attempt < max_attempts - 1:
                await asyncio.sleep(delay)
                delay *= backoff_factor

    # All retries failed
    raise last_exception

# Usage
async def fetch_customer_with_retry(customer_id: str):
    return await retry_with_backoff(
        lambda: fetch_customer_from_api(customer_id),
        max_attempts=3
    )

3. Circuit Breaker

Prevent cascading failures:

from enum import Enum
from datetime import datetime, timedelta

class CircuitState(Enum):
    CLOSED = "closed"  # Normal operation
    OPEN = "open"      # Failing, reject requests
    HALF_OPEN = "half_open"  # Testing if service recovered

class CircuitBreaker:
    def __init__(
        self,
        failure_threshold: int = 5,
        timeout_seconds: int = 60,
        expected_exception: type = Exception
    ):
        self.failure_threshold = failure_threshold
        self.timeout = timedelta(seconds=timeout_seconds)
        self.expected_exception = expected_exception

        self.failure_count = 0
        self.last_failure_time = None
        self.state = CircuitState.CLOSED

    async def call(self, func):
        if self.state == CircuitState.OPEN:
            if datetime.now() - self.last_failure_time > self.timeout:
                self.state = CircuitState.HALF_OPEN
                logger.info("Circuit breaker entering HALF_OPEN state")
            else:
                raise Exception("Circuit breaker is OPEN")

        try:
            result = await func()
            self._on_success()
            return result
        except self.expected_exception as e:
            self._on_failure()
            raise e

    def _on_success(self):
        self.failure_count = 0
        self.state = CircuitState.CLOSED

    def _on_failure(self):
        self.failure_count += 1
        self.last_failure_time = datetime.now()

        if self.failure_count >= self.failure_threshold:
            self.state = CircuitState.OPEN
            logger.error("Circuit breaker opened due to repeated failures")

# Usage
external_api_breaker = CircuitBreaker(failure_threshold=5, timeout_seconds=60)

async def call_external_api(customer_id: str):
    return await external_api_breaker.call(
        lambda: fetch_from_external_api(customer_id)
    )

Deployment Strategies

1. Environment Configuration

Use different configs for dev/staging/prod:

import os
from enum import Enum

class Environment(Enum):
    DEVELOPMENT = "development"
    STAGING = "staging"
    PRODUCTION = "production"

class Config:
    def __init__(self):
        self.env = Environment(os.getenv("ENVIRONMENT", "development"))
        self.database_url = os.getenv("DATABASE_URL")
        self.log_level = os.getenv("LOG_LEVEL", "INFO")
        self.enable_caching = os.getenv("ENABLE_CACHING", "true").lower() == "true"
        self.rate_limit = int(os.getenv("RATE_LIMIT", "100"))

    @property
    def is_production(self):
        return self.env == Environment.PRODUCTION

config = Config()

# Use config throughout your code
if config.enable_caching:
    # Use cache
    pass

2. Docker Deployment

Create a Dockerfile:

FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy server code
COPY customer_server.py .

# Non-root user for security
RUN useradd -m mcpuser
USER mcpuser

# Run the server
CMD ["python", "customer_server.py"]

docker-compose.yml:

version: '3.8'

services:
  mcp-server:
    build: .
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/customers
      - ENVIRONMENT=production
      - LOG_LEVEL=INFO
    depends_on:
      - db
    restart: unless-stopped

  db:
    image: postgres:15
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=pass
      - POSTGRES_DB=customers
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

3. Monitoring & Observability

Add health checks and metrics:

from prometheus_client import Counter, Histogram, start_http_server
import time

# Metrics
tool_calls_total = Counter('mcp_tool_calls_total', 'Total tool calls', ['tool_name', 'status'])
tool_duration = Histogram('mcp_tool_duration_seconds', 'Tool execution time', ['tool_name'])

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    start_time = time.time()

    try:
        result = await execute_tool_logic(name, arguments)
        tool_calls_total.labels(tool_name=name, status='success').inc()
        return result
    except Exception as e:
        tool_calls_total.labels(tool_name=name, status='error').inc()
        raise
    finally:
        duration = time.time() - start_time
        tool_duration.labels(tool_name=name).observe(duration)

# Start Prometheus metrics server (on a different port)
start_http_server(8000)

Real-World Considerations

Scaling Horizontally

For high-traffic scenarios:

Deploy multiple MCP server instances
Use a load balancer (though most MCP servers are stdio-based and tied to a single client)
Consider transitioning to HTTP-based MCP servers for true horizontal scaling

Data Privacy

PII Handling: Minimize exposure of personally identifiable information
Data Retention: Implement policies for log data
GDPR/CCPA Compliance: Ensure audit logs can be purged on request
Encryption: Use TLS for remote MCP servers

Maintenance

Versioning: Use semantic versioning for your MCP servers
Deprecation Strategy: Give users notice before removing tools
Backward Compatibility: Don't break existing tool contracts
Documentation: Maintain up-to-date API documentation

Checklist: Production Readiness

Before deploying to production, verify:

[ ] Authentication implemented
[ ] Input validation on all tools
[ ] SQL injection prevention (parameterized queries)
[ ] Secrets stored in environment variables or secrets manager
[ ] Rate limiting configured
[ ] Comprehensive audit logging
[ ] Error handling for all failure scenarios
[ ] Timeouts set on all external calls
[ ] Connection pooling for databases
[ ] Caching strategy implemented
[ ] Monitoring and metrics collection
[ ] Health checks configured
[ ] Environment-specific configurations
[ ] Docker/containerization setup
[ ] Documentation updated
[ ] Load testing completed

Conclusion: From Prototype to Production

The journey from "it works on my machine" to production-ready is significant, but following these practices will give you a robust, secure, and performant MCP server.

Key takeaways:

Security first - Never compromise on authentication, validation, and logging
Performance matters - Use pooling, caching, and async operations
Fail gracefully - Comprehensive error handling and resilience patterns
Monitor everything - You can't fix what you can't see
Plan for scale - Even if you don't need it today

MCP servers bridge AI capabilities with real-world systems. Building them responsibly means respecting the power they wield.

Series Wrap-Up

What we covered:

Part 1: MCP concepts and why they matter
Part 2: Building your first MCP server
Part 3: Making it production-ready

You now have everything you need to build secure, performant MCP servers that can power real-world AI applications.

What will you build? Share your MCP projects in the comments—I'd love to see what the community creates!

Additional Resources

Thanks for following this series! If you found it valuable, consider following for more posts on AI engineering, backend development, and modern software practices. Have questions? Drop them in the comments or reach out directly.

Building Your First MCP Server: A Practical Guide

Raghava Joijode — Sat, 08 Nov 2025 08:47:20 +0000

Part 2 of 3 in the MCP Server Series

In Part 1, we explored what MCP servers are and why they matter. Now it's time to build one.

By the end of this tutorial, you'll have a working MCP server that connects your AI to real data and tools. We'll cover both Python and TypeScript implementations, so you can choose what fits your stack.

Series Navigation:

Part 1: Understanding MCP conceptually
Part 2 (This post): Building your first MCP server
Part 3: Security, performance, and production deployment

Who This Guide Is For

Prerequisites:

Basic Python or TypeScript/Node.js knowledge
Familiarity with async/await patterns
Understanding of JSON and APIs (REST experience is helpful)
30-45 minutes to follow along

You'll learn:

How to choose between Python and TypeScript for MCP
Building a complete, working MCP server
Connecting your server to Claude
Testing with Claude Desktop

Python vs TypeScript: Which Should You Use?

This is the most common question I see. Both languages have official MCP SDK support, but they excel in different scenarios.

Python: The AI-Native Choice

Why Python dominates MCP development:

FastMCP (part of the official SDK) has 3.7k+ GitHub stars
Minimal boilerplate - get servers running in minutes
Direct integration with AI/ML libraries (TensorFlow, PyTorch, pandas)
Perfect for data science and analytics workflows
Cleaner syntax for rapid prototyping

Best for:

Data-heavy operations (analytics, ML inference, data transformation)
Scientific computing integrations
Existing Python ecosystems (Django, FastAPI applications)
Teams prioritizing development speed

Popular frameworks:

FastMCP - Official, minimal config, best community support
FastAPI-MCP - Zero-config for existing FastAPI apps

TypeScript/Node.js: The Integration Powerhouse

Why TypeScript shines for MCP:

Superior I/O performance for concurrent operations
Event-driven architecture handles multiple simultaneous AI requests
Exceptional protocol handling (STDIO, SSE, WebSocket)
Massive NPM ecosystem (350k+ packages)
Perfect for IDE extensions and developer tools

Best for:

High-concurrency scenarios (many AI agents making requests)
Real-time streaming applications
VS Code extensions and developer tooling
Orchestrating multiple external APIs
Network-heavy operations

Popular frameworks:

EasyMCP - Express-like API, great developer experience
Official MCP TypeScript SDK - Production-ready reference

My Recommendation

Choose Python if:

You're processing data, running ML models, or doing scientific computing
Your team works primarily in Python
You value faster development and cleaner code

Choose TypeScript if:

You need high concurrency and raw I/O performance
You're building IDE extensions or developer tools
You're primarily orchestrating external API calls

Reality check: Both work excellently. For this tutorial, I'll show Python (it's more beginner-friendly), but I'll link to TypeScript equivalents.

Building the Customer Data MCP Server (Python)

Let's build a practical MCP server that gives AI access to customer data. This mirrors real-world use cases like customer support, CRM integration, or sales automation.

Step 1: Install Dependencies

# Create a new directory
mkdir customer-mcp-server
cd customer-mcp-server

# Install MCP SDK
pip install mcp

# Optional: Create virtual environment first
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install mcp

Step 2: Create the Server

Create customer_server.py:

from mcp.server import Server
from mcp.types import Tool, TextContent
import mcp.server.stdio
import json

# Sample in-memory database (in production, this would be a real database)
CUSTOMERS = {
    "1": {
        "name": "Alice Johnson",
        "email": "alice@example.com",
        "tier": "premium",
        "orders": 24
    },
    "2": {
        "name": "Bob Smith",
        "email": "bob@example.com",
        "tier": "standard",
        "orders": 5
    },
    "3": {
        "name": "Carol Davis",
        "email": "carol@example.com",
        "tier": "premium",
        "orders": 47
    }
}

# Create the MCP server instance
app = Server("customer-data-server")

@app.list_tools()
async def list_tools() -> list[Tool]:
    """
    Define the tools available to AI.
    This is like creating an API documentation that the AI can read.
    """
    return [
        Tool(
            name="get_customer",
            description="Retrieve detailed customer information by their ID. "
                       "Use this when you need to look up a specific customer's "
                       "email, tier status, or order count.",
            inputSchema={
                "type": "object",
                "properties": {
                    "customer_id": {
                        "type": "string",
                        "description": "The customer's unique identifier (e.g., '1', '2', '3')"
                    }
                },
                "required": ["customer_id"]
            }
        ),
        Tool(
            name="list_premium_customers",
            description="Get a list of all customers with premium tier status. "
                       "Useful for identifying high-value customers or sending "
                       "premium-only communications.",
            inputSchema={
                "type": "object",
                "properties": {}
            }
        ),
        Tool(
            name="search_customers",
            description="Search for customers by name (case-insensitive). "
                       "Returns all customers whose names contain the search query.",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "The name or partial name to search for"
                    }
                },
                "required": ["query"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    """
    Handle tool execution requests from the AI.
    This is where the actual work happens.
    """

    if name == "get_customer":
        customer_id = arguments["customer_id"]
        customer = CUSTOMERS.get(customer_id)

        if customer:
            result = json.dumps(customer, indent=2)
        else:
            result = f"Customer with ID '{customer_id}' not found"

        return [TextContent(type="text", text=result)]

    elif name == "list_premium_customers":
        premium = [
            {"id": cid, **cdata}
            for cid, cdata in CUSTOMERS.items()
            if cdata["tier"] == "premium"
        ]
        return [TextContent(type="text", text=json.dumps(premium, indent=2))]

    elif name == "search_customers":
        query = arguments["query"].lower()
        results = [
            {"id": cid, **cdata}
            for cid, cdata in CUSTOMERS.items()
            if query in cdata["name"].lower()
        ]

        if results:
            result_text = json.dumps(results, indent=2)
        else:
            result_text = f"No customers found matching '{arguments['query']}'"

        return [TextContent(type="text", text=result_text)]

    else:
        raise ValueError(f"Unknown tool: {name}")

async def main():
    """
    Run the MCP server using stdio transport.
    This allows it to communicate with AI clients through standard input/output.
    """
    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
        await app.run(
            read_stream,
            write_stream,
            app.create_initialization_options()
        )

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Step 3: Test the Server Standalone

Before connecting to AI, let's verify it runs:

python customer_server.py

The server will start and wait for input. If there are no errors, you're good! Press Ctrl+C to stop it.

What we just built:

✅ Three tools the AI can use
✅ Clear descriptions so AI knows when to use each tool
✅ Type-safe input validation
✅ Helpful error messages

Connecting Your MCP Server to Claude

Now let's connect this server to Claude so it can actually use these tools.

Method 1: Claude Desktop (Easiest)

This is the fastest way to see your MCP server in action.

Step 1: Find your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Step 2: Edit the config (create the file if it doesn't exist):

{
  "mcpServers": {
    "customer-data": {
      "command": "python",
      "args": ["/absolute/path/to/customer_server.py"]
    }
  }
}

Important: Use the absolute path to your Python file!

Step 3: Restart Claude Desktop completely (Quit and reopen)

Step 4: Test it! In Claude Desktop, try:

Who are our premium customers?

Claude should automatically use your list_premium_customers tool and return the results!

Try these prompts:

"Look up customer 1"
"Search for customers with 'smith' in their name"
"What's Alice's email address?"

You'll see Claude automatically choosing the right tools based on your descriptions.

Method 2: Programmatic Connection (For Custom Apps)

If you're building your own AI application, here's how to connect programmatically:

import anthropic
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import asyncio

ANTHROPIC_API_KEY = "your-api-key-here"

async def run_ai_with_mcp():
    """Connect Claude to your MCP server programmatically"""

    # 1. Configure the MCP server connection
    server_params = StdioServerParameters(
        command="python",
        args=["customer_server.py"]
    )

    # 2. Start the MCP server and create a session
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:

            # 3. Initialize and discover available tools
            await session.initialize()
            tools_response = await session.list_tools()

            print(f"Connected! Available tools: {[t.name for t in tools_response.tools]}\n")

            # 4. Convert MCP tools to Claude's expected format
            claude_tools = [{
                "name": tool.name,
                "description": tool.description,
                "input_schema": tool.inputSchema
            } for tool in tools_response.tools]

            # 5. Create Claude client
            client = anthropic.Anthropic(api_key=ANTHROPIC_API_KEY)

            # 6. Send a user query
            user_message = "Can you find all premium customers and tell me their names?"
            print(f"User: {user_message}\n")

            messages = [{"role": "user", "content": user_message}]

            # 7. Conversation loop with tool usage
            while True:
                response = client.messages.create(
                    model="claude-sonnet-4-20250514",
                    max_tokens=4096,
                    tools=claude_tools,
                    messages=messages
                )

                # Add Claude's response to conversation
                messages.append({
                    "role": "assistant",
                    "content": response.content
                })

                # Check if Claude wants to use tools
                if response.stop_reason == "tool_use":
                    tool_results = []

                    # Execute each tool call through MCP
                    for block in response.content:
                        if block.type == "tool_use":
                            print(f"Claude is calling: {block.name}")
                            print(f"With arguments: {json.dumps(block.input, indent=2)}\n")

                            # Execute via MCP server
                            result = await session.call_tool(block.name, block.input)

                            print(f"Result: {result.content[0].text}\n")

                            tool_results.append({
                                "type": "tool_result",
                                "tool_use_id": block.id,
                                "content": result.content[0].text
                            })

                    # Send tool results back to Claude
                    messages.append({
                        "role": "user",
                        "content": tool_results
                    })
                else:
                    # Claude provided final answer
                    final_text = next(
                        (block.text for block in response.content if hasattr(block, "text")),
                        None
                    )

                    if final_text:
                        print(f"Claude: {final_text}")
                    break

if __name__ == "__main__":
    asyncio.run(run_ai_with_mcp())

Save this as test_client.py and run:

python test_client.py

Expected output:

Connected! Available tools: ['get_customer', 'list_premium_customers', 'search_customers']

User: Can you find all premium customers and tell me their names?

Claude is calling: list_premium_customers
With arguments: {}

Result: [
  {
    "id": "1",
    "name": "Alice Johnson",
    ...
  },
  ...
]

Claude: I found 2 premium customers: Alice Johnson and Carol Davis.

TypeScript Version (For Node.js Developers)

If you prefer TypeScript, here's the equivalent server:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const CUSTOMERS: Record<string, any> = {
  "1": { name: "Alice Johnson", email: "alice@example.com", tier: "premium" },
  "2": { name: "Bob Smith", email: "bob@example.com", tier: "standard" },
};

const server = new Server(
  { name: "customer-data-server", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "get_customer",
      description: "Retrieve customer information by ID",
      inputSchema: {
        type: "object",
        properties: {
          customer_id: { type: "string", description: "Customer's unique ID" }
        },
        required: ["customer_id"]
      }
    },
    {
      name: "list_premium_customers",
      description: "Get all premium tier customers",
      inputSchema: { type: "object", properties: {} }
    }
  ]
}));

server.setRequestHandler("tools/call", async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_customer") {
    const customer = CUSTOMERS[args.customer_id];
    return {
      content: [{
        type: "text",
        text: customer ? JSON.stringify(customer, null, 2) : "Customer not found"
      }]
    };
  }

  if (name === "list_premium_customers") {
    const premium = Object.entries(CUSTOMERS)
      .filter(([_, data]) => data.tier === "premium")
      .map(([id, data]) => ({ id, ...data }));
    return {
      content: [{ type: "text", text: JSON.stringify(premium, null, 2) }]
    };
  }

  throw new Error(`Unknown tool: ${name}`);
});

const transport = new StdioServerTransport();
await server.connect(transport);

Install dependencies:

npm init -y
npm install @modelcontextprotocol/sdk zod

Expanding Your Server: Adding Real Functionality

Our example uses in-memory data, but here's how to connect to real systems:

Connecting to PostgreSQL

import asyncpg

async def get_customer_from_db(customer_id: str):
    conn = await asyncpg.connect('postgresql://user:pass@localhost/db')
    try:
        result = await conn.fetchrow(
            'SELECT * FROM customers WHERE id = $1',
            customer_id
        )
        return dict(result) if result else None
    finally:
        await conn.close()

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "get_customer":
        customer = await get_customer_from_db(arguments["customer_id"])
        # ... rest of the code

Calling External APIs

import httpx

async def create_support_ticket(title: str, description: str):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            'https://api.your-ticketing-system.com/tickets',
            headers={'Authorization': f'Bearer {TICKET_API_KEY}'},
            json={'title': title, 'description': description}
        )
        return response.json()

Reading Files

import aiofiles

async def read_log_file(filename: str):
    async with aiofiles.open(f'/var/log/{filename}', 'r') as f:
        return await f.read()

Testing Best Practices

Before deploying, test your MCP server thoroughly:

1. Unit Test Individual Tools

import pytest

@pytest.mark.asyncio
async def test_get_customer():
    result = await call_tool("get_customer", {"customer_id": "1"})
    data = json.loads(result[0].text)
    assert data["name"] == "Alice Johnson"
    assert data["tier"] == "premium"

@pytest.mark.asyncio
async def test_customer_not_found():
    result = await call_tool("get_customer", {"customer_id": "999"})
    assert "not found" in result[0].text.lower()

2. Test with Claude Desktop First

Before writing complex client code, always test with Claude Desktop. It's the fastest way to:

Verify tool descriptions are clear
Catch input schema issues
See how Claude interprets your tools

3. Add Logging

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@app.call_tool()
async def call_tool(name: str, arguments: dict):
    logger.info(f"Tool called: {name} with args: {arguments}")
    # ... rest of implementation

Common Pitfalls & Solutions

Issue: "Server not responding"

Solution: Check absolute paths in config. Use which python or where python to find the correct Python path.

Issue: "Tool not being called"

Solution: Improve tool descriptions. Be specific about when to use each tool.

Issue: "Arguments are wrong"

Solution: Make your inputSchema more detailed with better descriptions for each property.

Issue: "Server crashes on certain inputs"

Solution: Add proper error handling and validation in call_tool().

What's Next?

You now have a working MCP server! But before deploying to production, there are critical considerations around security, authentication, and performance.

In Part 3, we'll cover:

Production security best practices
Authentication and authorization
Rate limiting and error handling
Performance optimization
Deployment strategies
Monitoring and debugging

Resources

Code Repository: [GitHub link - add yours]
Official MCP Python SDK
Official MCP TypeScript SDK
Example MCP Servers
Claude Desktop Download

Questions? Drop them in the comments. Share your MCP server projects—I'd love to see what you're building!

Follow for Part 3 where we make this production-ready with security, performance optimization, and deployment strategies.

MCP Servers Explained: Why They're More Than Just APIs for AI

Raghava Joijode — Sat, 01 Nov 2025 13:42:18 +0000

Part 1 of 3 in the MCP Server Series

If you're building AI applications, you've probably hit this wall: how do you give your AI access to real-time data and tools without compromising security or writing integration code for every single service?

I recently discovered Model Context Protocol (MCP) servers, and they've changed how I think about AI integrations. This is the first post in a three-part series where I'll take you from understanding MCP conceptually to building production-ready servers.

In this series:

Part 1 (This post): Understanding what MCP is and why it matters
Part 2: Building your first MCP server with hands-on code
Part 3: Security, performance, and production deployment

Let's start with the fundamentals.

The Problem MCP Solves

Imagine you're building an AI assistant for customer support. You need it to:

Look up customer information in your CRM
Create support tickets in Jira
Send follow-up emails
Check order status in your database

Your current options all have serious drawbacks:

Option 1: Embed Everything in Prompts

The approach: Include all customer data, product info, and relevant context directly in your prompts.

Problems:

Expensive - Token costs explode with large data dumps
Context limits - Models have finite context windows (even with 200k tokens, you can't fit everything)
Stale data - Information becomes outdated the moment you embed it
Privacy concerns - Sending sensitive data through API calls repeatedly

Option 2: Give AI Direct Database Access

The approach: Provide the AI with database credentials or API keys to query directly.

Problems:

Security nightmare - AI has unrestricted access to everything
No audit trail - Hard to track what the AI accessed or modified
Dangerous operations - Nothing prevents the AI from deleting records or exposing sensitive data
Compliance issues - Violates most data governance policies

Option 3: Build Custom APIs for Each AI Platform

The approach: Create separate integration layers for Claude, GPT, Gemini, etc.

Problems:

Maintenance hell - Each AI platform has different formats and requirements
Redundant code - Writing the same logic multiple times
Scaling nightmare - N AI models × M tools = exponential complexity
Slow iteration - Changes require updating multiple integrations

None of these feel right. That's where MCP comes in.

What is MCP?

Model Context Protocol (MCP) is an open standard that provides a unified way for AI applications to connect with external data sources and tools. Think of it as a secure, AI-optimized middleware layer between your AI models and your systems.

Released by Anthropic in November 2024, MCP solved what developers called the "N×M problem"—where each AI model (N) needed separate integration code for every tool (M). As both multiplied, this created an exponential explosion of integration work.

The Core Idea

Instead of building custom integrations for every AI-tool combination, you build one MCP server that:

Exposes your tools and data in a standardized format
Works with any MCP-compatible AI (Claude, potentially GPT, or custom models)
Handles security, authentication, and business logic in one place

Write once, use everywhere.

How MCP Works (Simple Mental Model)

Think of MCP servers like a smart waiter at a restaurant:

Without MCP:

Every customer (AI model) speaks a different language
Each needs different menu formats
Kitchen (your systems) must handle requests from all of them differently

With MCP:

The waiter (MCP server) speaks all languages
Translates orders into one standard format the kitchen understands
Ensures customers can only order what's on the menu (security)
Handles special requests, allergies, and modifications (business logic)

Beyond Data Retrieval: MCP Servers Can DO Things

When I first heard "MCP servers," I assumed they were just for fetching data. I was wrong.

MCP servers can perform three types of operations:

1. Read Operations (Data Retrieval)

Query databases and return results
Search through documents or knowledge bases
Fetch real-time information from APIs
Monitor system metrics and logs

Example: "What are this customer's recent orders?"

2. Write Operations (Taking Actions)

Create support tickets
Send emails or notifications
Update database records
Deploy code or restart services
Approve or reject workflows

Example: "Create a high-priority ticket for this issue and notify the team lead."

3. Complex Orchestrations (Multi-Step Workflows)

Run tests, analyze results, and create pull requests if they pass
Search documentation, extract insights, update a dashboard, and notify stakeholders
Process uploaded files, extract data, validate it, and store in database

Example: "Analyze this bug report, check if it's a duplicate, create a ticket if new, and notify the relevant team based on the component affected."

The AI doesn't just read—it executes real work.

Why Not Just Use Regular APIs?

This is the question everyone asks. After all, MCP servers often wrap existing REST APIs or database connections internally. So what value does MCP actually add?

Here are five critical advantages:

1. Standardization Across AI Platforms

Without MCP:

Claude expects: {name: "search", parameters: {...}}
GPT expects: {function: "search", arguments: {...}}
Gemini expects: {tool_name: "search", input: {...}}

With MCP:

One tool definition works everywhere:
Tool(name="search", description="...", inputSchema={...})

You write the integration once, and it works with any MCP-compatible AI system.

2. AI-Optimized Interface Design

Traditional APIs are built for developers. MCP is built for AI models.

Regular API:

GET /customers?id=123
Response: {...customer data...}

MCP Tool:

Tool(
    name="get_customer",
    description="Retrieve customer information by ID. Use this when you need 
                 to look up a customer's email, tier, or purchase history.",
    inputSchema={
        "type": "object",
        "properties": {
            "customer_id": {
                "type": "string",
                "description": "The customer's unique identifier"
            }
        }
    }
)

The semantic descriptions and parameter constraints guide the AI's decision-making. The model understands when to use this tool and what arguments to provide.

3. Security & Granular Scoping

Direct API access is all-or-nothing. MCP lets you expose exactly what the AI needs:

✅ AI can: Read customer names and emails
✅ AI can: Create support tickets
✅ AI can: Search order history

❌ AI cannot: Delete customer records
❌ AI cannot: Access payment information
❌ AI cannot: Modify pricing data

You define the boundary at the MCP server level, not by hoping the AI "behaves."

4. Abstraction & Complexity Hiding

Your MCP server might:

Call 5 different microservices
Merge and transform the responses
Apply caching for performance
Implement retry logic for failures
Handle pagination automatically
Apply business rules before returning data

The AI just sees: get_customer_summary(id) → clean, structured data

This abstraction is powerful. The AI doesn't need to understand your system architecture, API rate limits, or data transformation logic.

5. State Management & Context

MCP can maintain context across multiple requests:

Without MCP:

AI: Call API 1
AI: Call API 2 with results from API 1
AI: Call API 3 with results from API 2

Each call is independent, no shared state.

With MCP:

AI: Start analysis workflow
MCP Server: Executes multi-step process internally
MCP Server: Returns final result

The server manages intermediate state, databases connections, and session data.

The Bottom Line

Analogy: You could give a junior developer full production database credentials and tell them "be careful," or you could give them a well-documented SDK with guardrails. MCP is the SDK for AI.

The MCP Ecosystem in 2025

Since the November 2024 release, the MCP ecosystem has exploded. Here are some of the most impactful MCP servers being used in production:

Development & DevOps

GitHub MCP - Create issues, review PRs, merge code, trigger CI/CD pipelines
Filesystem MCP - Read, write, and manipulate files with proper permissions
Docker MCP - Manage containers, deploy services, view logs

Data & Search

PostgreSQL/MySQL MCP - Secure database querying with read-only modes
Brave Search MCP - Privacy-first web search for AI research
Elasticsearch MCP - Full-text search across your documents

Communication & Collaboration

Slack MCP - Post messages, create channels, manage workflows
Email MCP - Compose and send emails with templates
Google Drive MCP - Search and retrieve documents

Business Tools

Jira MCP - Create tickets, update status, assign tasks
Salesforce MCP - Query CRM data, update opportunities
Stripe MCP - Look up payment info, create invoices (read-only for safety)

The pattern: Take any system your team uses daily, wrap it in an MCP server, and suddenly your AI can interact with it naturally.

Real-World Impact: A Quick Example

Let me show you the difference MCP makes with a real scenario:

Before MCP

User: "What's the status of order #12345 and can you email the customer with an update?"

Process:

Developer writes custom code to connect AI to order database
Developer writes separate code to connect AI to email service
Developer adds error handling for both
Developer tests with Claude
Customer switches to GPT → developer rewrites everything
Time to implement: 2-3 days
Maintenance burden: Ongoing

After MCP

User: "What's the status of order #12345 and can you email the customer with an update?"

Process:

AI calls get_order_status(order_id="12345") via MCP
AI calls send_email(to=customer_email, subject="...", body="...") via MCP
Both tools were already defined in MCP servers
Works with any MCP-compatible AI (Claude, GPT if they adopt it, custom models)
Time to implement: Tools already exist, 0 minutes
Maintenance burden: Update MCP server once, works everywhere

The AI went from useless to productive in seconds instead of days.

What Makes This Different From GraphQL, gRPC, or Other Protocols?

Fair question. Here's the key distinction:

GraphQL, gRPC, REST → Designed for developer-to-service communication
MCP → Designed for AI-to-service communication

MCP is optimized for:

Semantic descriptions AI models can parse
Tool discovery (AI can ask "what can I do?")
Streaming responses for long operations
Context that persists across tool calls
Standardized error handling AI can interpret

You could build all this on top of GraphQL, but then you'd just be reinventing MCP.

Coming Up in Part 2

Now you understand what MCP is and why it matters. But understanding concepts is different from building working systems.

In Part 2, we'll get hands-on:

Comparing Python vs TypeScript/Node.js for MCP servers
Building a complete MCP server from scratch
Connecting it to Claude and seeing it work
Testing with Claude Desktop for immediate feedback

Want to Go Deeper?

Resources:

Questions? Drop them in the comments. I'm documenting my journey learning MCP and I'd love to hear about your use cases.

Building AI applications? Follow me for Part 2 where we write actual MCP server code, and Part 3 where we tackle security and production deployment.