DEV Community: Chandra Shettigar

Building Your First MCP Server

Chandra Shettigar — Sat, 14 Jun 2025 05:12:27 +0000

A hands-on tutorial to create an MCP-enabled product database service

In our previous posts, we've seen what MCP is and why it matters. Now let's get our hands dirty and build an actual MCP server that any AI agent can use.

We'll create a Product Database MCP Server that exposes product information through standardized MCP tools. By the end, you'll have a working MCP server and understand exactly how to make any service AI-agent ready.

🚀 Want to jump straight to the code? Check out the complete implementation on GitHub: mcp-product-search-service

Current MCP Ecosystem Reality

What works today:

MCP protocol specification is stable
You can build MCP servers (like we're about to do)
HTTP-based integration works universally

What's still developing:

Official Python MCP libraries may have different APIs than shown
AI agent framework MCP support varies by platform
Ecosystem tooling is rapidly emerging

Bottom line: Focus on the HTTP API patterns shown here - they're universal and future-proof regardless of how MCP libraries evolve.

What We're Building

A product database service that provides:

search_products: Find products by name or category
get_product_details: Get detailed information about a specific product
check_inventory: Check stock levels for a product
REST API endpoints: Direct HTTP access alongside MCP protocol
Comprehensive testing: Full test suite with 18+ tests
Docker support: Containerized development environment

Prerequisites

We'll use a modern Python stack with FastAPI and handle MCP protocol manually:

# Clone the complete project (when available)
git clone git@github.com:devteds/mcp-test-service.git
cd mcp-product-search-service

# Or start from scratch with these dependencies
pip install fastapi uvicorn pydantic pytest httpx

Note: We're implementing the MCP protocol directly rather than relying on potentially unstable MCP libraries.

Step 1: Project Structure

Unlike simple single-file examples, we'll build a proper service:

mcp-product-search-service/
├── mcp_service/
│   ├── __init__.py
│   ├── __main__.py          # Entry point for python -m mcp_service
│   ├── main.py              # Application startup
│   ├── server.py            # FastAPI app configuration
│   ├── handlers.py          # MCP protocol handlers
│   ├── models.py            # Pydantic data models
│   └── data.py              # Product database
├── tests/
│   ├── test_server.py       # Basic server tests
│   └── test_product_service.py  # MCP functionality tests
├── requirements.txt
├── pyproject.toml
└── README.md

Step 2: The Product Database

First, let's set up our product data in mcp_service/data.py:

"""Product database for the MCP service."""

# Our sample product database
PRODUCTS = [
    {
        "id": "1",
        "name": "iPhone 15 Pro",
        "category": "Electronics",
        "price": 999.99,
        "stock": 50,
        "description": "Latest iPhone with titanium design"
    },
    {
        "id": "2", 
        "name": "MacBook Air M3",
        "category": "Electronics", 
        "price": 1299.99,
        "stock": 25,
        "description": "Lightweight laptop with M3 chip"
    },
    {
        "id": "3",
        "name": "Nike Air Max",
        "category": "Footwear",
        "price": 129.99, 
        "stock": 100,
        "description": "Classic running shoes"
    },
    {
        "id": "4",
        "name": "Coffee Maker Pro",
        "category": "Appliances",
        "price": 199.99,
        "stock": 15,
        "description": "Professional grade coffee maker"
    }
]

def search_products(query: str = "", category: str = "") -> list:
    """Search for products by name or category"""
    results = []

    for product in PRODUCTS:
        name_match = query.lower() in product["name"].lower() if query else True
        category_match = category.lower() == product["category"].lower() if category else True

        if name_match and category_match:
            results.append({
                "id": product["id"],
                "name": product["name"], 
                "category": product["category"],
                "price": product["price"]
            })

    return results

def get_product_details(product_id: str) -> dict:
    """Get detailed information about a specific product"""
    for product in PRODUCTS:
        if product["id"] == product_id:
            return product
    return {"error": "Product not found"}

def check_inventory(product_id: str) -> dict:
    """Check stock levels for a product"""
    for product in PRODUCTS:
        if product["id"] == product_id:
            return {
                "product_id": product_id,
                "product_name": product["name"],
                "stock": product["stock"],
                "in_stock": product["stock"] > 0
            }
    return {"error": "Product not found"}

Step 3: MCP Protocol Implementation

The heart of our MCP server is in mcp_service/handlers.py. Here's how we handle MCP messages:

from fastapi import APIRouter
from pydantic import BaseModel
from typing import Dict, Any, Optional
from .data import search_products, get_product_details, check_inventory

router = APIRouter()

class MCPRequest(BaseModel):
    id: str
    method: str
    params: Dict[str, Any] = {}

class MCPResponse(BaseModel):
    id: str
    result: Optional[Dict[str, Any]] = None
    error: Optional[Dict[str, Any]] = None

@router.post("/mcp/message", response_model=MCPResponse)
async def handle_mcp_message(request: MCPRequest) -> MCPResponse:
    """Handle incoming MCP messages for product operations."""
    try:
        if request.method == "capabilities":
            return MCPResponse(
                id=request.id,
                result={
                    "capabilities": {
                        "tools": [
                            {
                                "name": "search_products",
                                "description": "Search for products by name or category",
                                "parameters": {
                                    "query": {"type": "string", "description": "Search query"},
                                    "category": {"type": "string", "description": "Product category"}
                                }
                            },
                            {
                                "name": "get_product_details", 
                                "description": "Get detailed information about a specific product",
                                "parameters": {
                                    "product_id": {"type": "string", "required": True}
                                }
                            },
                            {
                                "name": "check_inventory",
                                "description": "Check stock levels for a product",
                                "parameters": {
                                    "product_id": {"type": "string", "required": True}
                                }
                            }
                        ]
                    }
                }
            )

        elif request.method == "search_products":
            query = request.params.get("query", "")
            category = request.params.get("category", "")
            results = search_products(query, category)
            return MCPResponse(
                id=request.id,
                result={"products": results, "count": len(results)}
            )

        elif request.method == "get_product_details":
            product_id = request.params.get("product_id")
            if not product_id:
                return MCPResponse(
                    id=request.id,
                    error={"code": -32602, "message": "Missing required parameter: product_id"}
                )

            product = get_product_details(product_id)
            return MCPResponse(id=request.id, result=product)

        elif request.method == "check_inventory":
            product_id = request.params.get("product_id")
            if not product_id:
                return MCPResponse(
                    id=request.id,
                    error={"code": -32602, "message": "Missing required parameter: product_id"}
                )

            inventory = check_inventory(product_id)
            return MCPResponse(id=request.id, result=inventory)

        else:
            return MCPResponse(
                id=request.id,
                error={"code": -32601, "message": f"Method '{request.method}' not found"}
            )

    except Exception as e:
        return MCPResponse(
            id=request.id,
            error={"code": -32603, "message": f"Internal error: {str(e)}"}
        )

Step 4: Start Your MCP Server

Our service includes a proper entry point in mcp_service/main.py:

"""Main entry point for the MCP service."""

import uvicorn

def main():
    """Main entry point for the MCP service."""
    uvicorn.run(
        "mcp_service.server:create_app",
        factory=True,
        host="0.0.0.0",
        port=8000,
        reload=True,
        log_level="info"
    )

if __name__ == "__main__":
    main()

Start the server:

python -m mcp_service

You should see:

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [7014] using WatchFiles
INFO:     Started server process [7017]
INFO:     Application startup complete.

Step 5: Test Your MCP Server

Test MCP Protocol Directly

# Test capabilities discovery
curl -X POST http://localhost:8000/api/v1/mcp/message \
  -H "Content-Type: application/json" \
  -d '{"id": "1", "method": "capabilities", "params": {}}'

# Search for products
curl -X POST http://localhost:8000/api/v1/mcp/message \
  -H "Content-Type: application/json" \
  -d '{"id": "2", "method": "search_products", "params": {"query": "iPhone"}}'

# Get product details
curl -X POST http://localhost:8000/api/v1/mcp/message \
  -H "Content-Type: application/json" \
  -d '{"id": "3", "method": "get_product_details", "params": {"product_id": "1"}}'

Test REST API Endpoints

Our service also provides REST endpoints for direct access:

# Search products via REST
curl "http://localhost:8000/api/v1/products/search?query=MacBook"

# Get product details via REST  
curl "http://localhost:8000/api/v1/products/2"

# Check inventory via REST
curl "http://localhost:8000/api/v1/products/3/inventory"

# Get available categories
curl "http://localhost:8000/api/v1/categories"

Step 6: Automated Testing

Our service includes comprehensive tests. Run them with:

pytest tests/ -v

Sample test output:

tests/test_product_service.py::TestMCPEndpoints::test_search_products_message PASSED
tests/test_product_service.py::TestMCPEndpoints::test_get_product_details_message PASSED
tests/test_product_service.py::TestMCPEndpoints::test_check_inventory_message PASSED
tests/test_server.py::test_root_endpoint PASSED

============================================ 18 passed in 0.40s ============================================

Step 7: Connect to an AI Agent

Here's how an AI agent would discover and use your MCP server. We'll show multiple approaches since MCP client libraries are still evolving:

Using Direct HTTP (Recommended - Universal)

import asyncio
import httpx

class MCPProductClient:
    """A client for interacting with our Product Search MCP server."""

    def __init__(self, base_url: str = "http://localhost:8000"):
        self.base_url = base_url

    async def discover_capabilities(self):
        """Discover what tools the MCP server provides."""
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/api/v1/mcp/message",
                json={
                    "id": "capabilities",
                    "method": "capabilities",
                    "params": {}
                }
            )
            return response.json()

    async def call_tool(self, tool_name: str, arguments: dict):
        """Call a tool on the MCP server."""
        async with httpx.AsyncClient() as client:
            response = await client.post(
                f"{self.base_url}/api/v1/mcp/message",
                json={
                    "id": f"call_{tool_name}",
                    "method": tool_name,
                    "params": arguments
                }
            )
            return response.json()

    async def search_products(self, query: str = "", category: str = ""):
        """Search for products."""
        result = await self.call_tool("search_products", {
            "query": query,
            "category": category
        })
        return result.get("result", {})

# Usage example
async def demo():
    client = MCPProductClient("http://localhost:8000")

    # Discover available tools
    capabilities = await client.discover_capabilities()
    tools = capabilities["result"]["capabilities"]["tools"]
    print("Available tools:", [tool["name"] for tool in tools])

    # Search for electronics
    electronics = await client.search_products(category="Electronics")
    print(f"Found {electronics['count']} electronics")

    # Get product details
    product_result = await client.call_tool("get_product_details", {"product_id": "1"})
    iphone = product_result["result"]
    print(f"iPhone: {iphone['name']} - ${iphone['price']}")

# Run the demo
asyncio.run(demo())

Using Hypothetical MCP Library (Future)

# Note: This example uses hypothetical MCP client patterns
# Actual implementation may vary based on MCP library evolution

try:
    from mcp import types  # May not exist yet

    class TypedMCPClient:
        """Example using potential future MCP types for better type safety."""

        def __init__(self, base_url: str = "http://localhost:8000"):
            self.base_url = base_url

        async def call_tool_typed(self, tool_name: str, arguments: dict):
            """Call a tool using potential future MCP types."""
            # This is conceptual - actual MCP library API may differ
            async with httpx.AsyncClient() as client:
                response = await client.post(
                    f"{self.base_url}/api/v1/mcp/message",
                    json={
                        "id": "typed_call",
                        "method": tool_name,
                        "params": arguments or {}
                    }
                )
                return response.json()

except ImportError:
    print("MCP library not available - use direct HTTP approach above")

Integration with AI Frameworks

# Example of how this might integrate with LangChain (conceptual)
class MCPTool:
    """Wrapper to use our MCP server as a LangChain tool."""

    def __init__(self, mcp_client: MCPProductClient):
        self.client = mcp_client

    async def search_products(self, query: str, category: str = ""):
        """LangChain-compatible tool for product search."""
        result = await self.client.search_products(query, category)
        return f"Found {result['count']} products: {result['products']}"

    async def get_product(self, product_id: str):
        """LangChain-compatible tool for product details."""
        result = await self.client.call_tool("get_product_details", {"product_id": product_id})
        return result["result"]

What Just Happened?

You built a MCP ecosystem!

Proper Project Structure: Modular, testable, maintainable code
MCP Protocol: Full JSON-RPC 2.0 implementation with error handling
Tool Discovery: AI agents can discover capabilities automatically
Dual Interface: Both MCP protocol and REST API access
Comprehensive Testing: 18+ tests covering all functionality

The Power of What You Built

Your MCP server can now be used by:

Any HTTP client via direct API calls (works today)
Future MCP-compatible clients using the MCP protocol
AI agent frameworks with MCP support or custom HTTP adapters
Applications that implement MCP client functionality
Direct integration in any system that can make HTTP requests

Reality Check: While MCP is designed to work with any AI agent framework, most frameworks are still adding MCP support. However, your server provides both MCP protocol and REST API access, making it universally accessible.

Key Features of Our Implementation

🔍 Discovery Endpoint

The capabilities method tells AI agents exactly what your service can do:

{
  "capabilities": {
    "tools": [
      {"name": "search_products", "description": "Search for products by name or category"},
      {"name": "get_product_details", "description": "Get detailed information about a specific product"},
      {"name": "check_inventory", "description": "Check stock levels for a product"}
    ]
  }
}

🛡️ Error Handling

Proper MCP error codes and messages:

-32601: Method not found
-32602: Invalid parameters
-32603: Internal error

📊 Structured Responses

All responses follow MCP protocol with proper id, result, and error fields.

Adding More Functionality

Want to add a new tool? Just add a method to your handlers:

elif request.method == "update_inventory":
    product_id = request.params.get("product_id")
    new_stock = request.params.get("new_stock")

    if not product_id or new_stock is None:
        return MCPResponse(
            id=request.id,
            error={"code": -32602, "message": "Missing required parameters"}
        )

    # Update logic here (in real app, update database)
    result = {"product_id": product_id, "new_stock": new_stock, "updated": True}

    return MCPResponse(id=request.id, result=result)

That's it! Any AI agent using your MCP server will automatically discover and can use the new tool.

Real-World Next Steps

To make this production-ready:

Replace sample data with real database (PostgreSQL, MongoDB, etc.)
Add authentication for secure access (API keys, JWT tokens)
Implement rate limiting to prevent abuse
Add comprehensive logging for monitoring and debugging
Deploy to cloud (AWS, GCP, Azure, etc.)
Add more tools (create, update, delete products)
Add data validation and sanitization
Implement caching for better performance

Complete Implementation

📚 Repository Note: The complete implementation is here - https://github.com/devteds/mcp-test-service. The patterns shown here are tested and work, but check the latest MCP documentation for any protocol updates.

The implementation would include:

✅ Complete MCP server implementation
✅ Comprehensive test suite (18+ tests)
✅ Docker development environment
✅ API documentation
✅ Usage examples

Key Takeaways

MCP servers are powerful - standardized protocol for AI integration
HTTP-first approach ensures universal compatibility
Tool discovery makes your services self-documenting for AI agents
Production patterns matter - proper structure, testing, error handling
Focus on business logic, not integration complexity
MCP libraries are evolving - HTTP APIs provide stability

🧪 Testing Note: The code shown has been tested locally but MCP libraries evolve rapidly. The HTTP-based approach provides maximum compatibility regardless of library changes.

⚠️ Important Note: The AI space evolves incredibly fast. MCP is still in early stages and may evolve significantly - what we know today might look different in a few months. Also note that this example MCP server hasn't been tested by integrating into any MCP host yet.

The key is building your foundation in AI concepts and staying adaptable as the ecosystem matures. Keep learning, keep experimenting!

📝 Code Note: The code examples use direct HTTP implementation of MCP protocol for maximum compatibility. Official MCP libraries may have different APIs - always refer to current MCP documentation for the latest patterns.

Next up: We'll explore the full MCP ecosystem and see real-world examples of MCP servers in production.

What You Built Today

✅ MCP server with proper structure

✅ Tool discovery capability for AI agents

✅ Comprehensive testing and error handling

✅ Universal HTTP compatibility regardless of MCP library evolution

✅ Foundation for real-world deployment

Ready to turn your services into MCP servers? Clone this repository!

MCP vs Direct APIs: A Side-by-Side Example

Chandra Shettigar — Sat, 14 Jun 2025 04:51:18 +0000

See exactly how MCP standardizes AI agent development

In our previous post, we introduced MCP as "HTTP for AI agents." In this post, let's see this in action with a bit more detailed example that shows the difference between building AI agents with traditional integrations vs. the MCP approach.

Important Context: MCP is still early-stage, and most services don't have MCP servers yet. This example shows the vision of where MCP is heading and the problems it aims to solve.

The Scenario: Building a Smart Travel Assistant

You're building an AI assistant that helps users plan trips. It needs to:

Get weather forecasts
Find nearby restaurants
Book hotels

Let's see how you'd build this today vs. with MCP.

The Traditional Approach: Integration Complexity

Weather Service Integration

import requests
import os

class WeatherService:
    def __init__(self):
        self.api_key = os.getenv('WEATHER_API_KEY')
        self.base_url = 'https://api.openweathermap.org/data/2.5'

    def get_current_weather(self, city):
        try:
            response = requests.get(
                f"{self.base_url}/weather",
                params={
                    'q': city,
                    'appid': self.api_key,
                    'units': 'metric'
                }
            )

            response.raise_for_status()
            data = response.json()

            # Transform to our format
            return {
                'temperature': data['main']['temp'],
                'description': data['weather'][0]['description'],
                'humidity': data['main']['humidity']
            }
        except requests.RequestException as error:
            print(f'Weather service failed: {error}')
            raise

Restaurant Service Integration

class RestaurantService:
    def __init__(self):
        self.api_key = os.getenv('YELP_API_KEY')
        self.base_url = 'https://api.yelp.com/v3'

    def find_restaurants(self, location, cuisine):
        try:
            response = requests.get(
                f"{self.base_url}/businesses/search",
                params={
                    'location': location,
                    'categories': cuisine,
                    'limit': 10
                },
                headers={
                    'Authorization': f'Bearer {self.api_key}',
                    'Accept': 'application/json'
                }
            )

            response.raise_for_status()
            data = response.json()

            # Different data format, different transformation
            return [
                {
                    'name': business['name'],
                    'rating': business['rating'],
                    'address': business['location']['address1'],
                    'phone': business.get('phone', '')
                }
                for business in data['businesses']
            ]
        except requests.RequestException as error:
            print(f'Restaurant service failed: {error}')
            raise

Hotel Service Integration

class HotelService:
    def __init__(self):
        self.api_key = os.getenv('BOOKING_API_KEY')
        self.base_url = 'https://api.booking.com/v1'

    def search_hotels(self, city, check_in, check_out):
        try:
            # Yet another authentication method
            response = requests.post(
                f"{self.base_url}/hotels/search",
                headers={
                    'X-API-Key': self.api_key,
                    'Content-Type': 'application/json'
                },
                json={
                    'destination': city,
                    'check_in': check_in,
                    'check_out': check_out,
                    'adults': 1
                }
            )

            # Different error handling pattern
            if response.status_code == 429:
                raise Exception('Rate limited - try again later')

            response.raise_for_status()
            data = response.json()

            # Another data transformation pattern
            return [
                {
                    'name': hotel['hotel_name'],
                    'price': hotel['price_per_night'],
                    'rating': hotel['guest_rating'],
                    'availability': hotel['available_rooms'] > 0
                }
                for hotel in data['results']
            ]
        except requests.RequestException as error:
            print(f'Hotel service failed: {error}')
            raise

The AI Agent Code

class TravelAgent:
    def __init__(self):
        self.weather_service = WeatherService()
        self.restaurant_service = RestaurantService()
        self.hotel_service = HotelService()

    def plan_trip(self, destination, dates):
        try:
            # Each service has its own calling pattern
            weather = self.weather_service.get_current_weather(destination)
            restaurants = self.restaurant_service.find_restaurants(destination, 'restaurants')
            hotels = self.hotel_service.search_hotels(destination, dates['check_in'], dates['check_out'])

            return {
                'weather': weather,
                'restaurants': restaurants,
                'hotels': hotels
            }
        except Exception as error:
            print(f'Trip planning failed: {error}')
            raise

What's Challenging About This Approach?

3 different authentication patterns: API key in URL, Bearer token, custom header
3 different error handling approaches: Different HTTP status codes, rate limiting
3 different data transformation needs: Each API returns data in its own format
Integration maintenance burden: Updates to any API require changes across all consumers
Hard to extend: Adding a new service means learning another API pattern

Note: This could be improved with better architecture (adapters, factories, etc.), but the core complexity remains.

The MCP Vision: Standardized Communication

Reality Check: Most of these MCP servers don't exist yet - someone would need to build them. But here's what it would look like:

# Conceptual MCP approach - not production code
from mcp_client import MCPClient

class TravelAgentMCP:
    def __init__(self):
        self.mcp_client = MCPClient()

        # Connect to MCP servers (these would need to be built/deployed)
        self.services = {
            'weather': 'mcp://weather-service',
            'restaurants': 'mcp://yelp-service', 
            'hotels': 'mcp://booking-service'
        }

    def plan_trip(self, destination, dates):
        try:
            # Same calling pattern for all services
            weather = self.mcp_client.call_tool(
                self.services['weather'], 
                'get_current_weather', 
                {'city': destination}
            )

            restaurants = self.mcp_client.call_tool(
                self.services['restaurants'],
                'find_restaurants',
                {'location': destination, 'cuisine': 'restaurants'}
            )

            hotels = self.mcp_client.call_tool(
                self.services['hotels'],
                'search_hotels',
                { 
                    'city': destination, 
                    'check_in': dates['check_in'], 
                    'check_out': dates['check_out']
                }
            )

            return {'weather': weather, 'restaurants': restaurants, 'hotels': hotels}

        except Exception as error:
            # Standardized error handling across all MCP services
            print(f'Trip planning failed: {error}')
            raise

The Key Differences

Traditional Approach

Multiple integration patterns to learn and maintain
Service-specific error handling and authentication
Direct coupling between agent and API formats
Repetitive integration work across different projects

MCP Approach

One integration pattern that works for all MCP services
Standardized error handling and authentication
Abstraction layer between agent and underlying APIs
Reusable integration work - write MCP server once, use everywhere

The Reality: Complexity Transfer, Not Elimination

Important: MCP doesn't eliminate integration complexity - it centralizes and standardizes it.

Someone still needs to:

Build MCP servers for each service (weather, restaurants, hotels)
Handle authentication to underlying APIs
Transform data formats within the MCP server
Manage MCP server reliability and performance

The advantage: This work is done once per service rather than once per consumer application.

Adding a New Service

Traditional way: Each application team writes their own integration:

# Team A writes this
class FlightServiceA:
    # 50 lines of integration code

# Team B writes this  
class FlightServiceB:
    # Another 50 lines, slightly different

MCP way: One team writes an MCP server, everyone uses it:

# One team builds: mcp://flight-service (50+ lines in the MCP server)
# Every team uses: one line
self.services['flights'] = 'mcp://flight-service'

Tool Discovery: The Dynamic Advantage

One of MCP's most powerful features is tool discovery:

# Conceptual example
tools = self.mcp_client.list_tools(self.services['weather'])

print(tools)
# Output:
# [
#   {'name': 'get_current_weather', 'description': 'Get current weather for a city'},
#   {'name': 'get_forecast', 'description': 'Get 5-day weather forecast'},
#   {'name': 'get_weather_alerts', 'description': 'Get severe weather alerts'}
# ]

This enables AI agents to dynamically discover capabilities and adapt their behavior - something that's much harder with traditional integrations.

The Deeper Advantage: Enabling AI Intelligence

The real power of MCP lies in standardization, enabling smarter AI behavior. When all tools follow the same interface pattern, LLMs can:

Dynamically choose tools based on user prompts
Adapt to workflow context (customer support vs development workflows)
Combine tools intelligently across different domains
Learn new capabilities without code changes

Traditional integrations require developers to hard-code which API to use when. With MCP, the AI agent can make these decisions contextually and dynamically.

Current State vs Future Vision

Today:

MCP protocol exists and is being adopted
Few production MCP servers available
Early adopters building their own MCP servers
Mainly useful for organizations building multiple AI agents

Future Vision:

Marketplace of MCP servers for common services
AI agents that dynamically discover and combine capabilities
Ecosystem effects where adding one MCP server benefits all agents

The Bottom Line

Traditional integration: Each team builds custom connections - like every household having different electrical outlets.

MCP integration: Standardized protocol that enables ecosystem growth - like having universal electrical outlets that any device can use.

The question isn't whether MCP eliminates complexity (it doesn't), but whether standardizing that complexity creates enough ecosystem value to justify the transition.

Next up: We'll build our first MCP server and see exactly how to make any service AI-agent ready.

Key Takeaways

MCP standardizes communication rather than eliminating complexity
Someone still builds the integrations - just once per service instead of per consumer
Tool discovery enables dynamic AI behavior that's hard with traditional APIs
Early stage but promising - ecosystem effects grow with adoption
Consider MCP when building for multiple AI agents or planning for future AI capabilities

⚠️ Important Note: The AI space evolves incredibly fast. MCP is still in early stages and may evolve significantly - what we know today might look different in a few months. The key is building your foundation in AI concepts and staying adaptable as the ecosystem matures. Keep learning, keep experimenting!

📝 Code Note: The code examples in this series are simplified for illustration purposes. Actual MCP implementations may require additional setup, error handling, and configuration. Always refer to official MCP documentation for production code.

Ready to try building an MCP server yourself? The next post will show you exactly how to do it!

What is MCP? Think HTTP for AI Agents

Chandra Shettigar — Sun, 08 Jun 2025 19:56:21 +0000

Understanding Model Context Protocol through familiar analogies

The Problem: AI Agents Can't Talk to Your Systems

Imagine you're building an AI travel assistant. You want it to:

Check flight prices on Expedia
Book hotels through Booking.com
Get weather forecasts
Access your customer database

Today, you'd need to write custom code for each service. Different APIs, different authentication methods, different data formats. It's like the early days of the web before HTTP standardized how browsers talk to servers.

Enter MCP: The HTTP of AI

Model Context Protocol (MCP) is to AI agents what HTTP is to web browsers - a standardized way to communicate.

Just like HTTP lets any browser talk to any web server, MCP lets any AI agent talk to any MCP-enabled service using the same protocol.

A Simple Analogy

Without MCP (like early internet):

AI Agent ── custom code ──> Expedia API
AI Agent ── different code ──> Weather API  
AI Agent ── another format ──> Your Database

With MCP (like modern web):

AI Agent ── MCP Protocol ──> Any MCP Service

Real-World Comparison

HTTP/REST World

# Every developer knows this pattern
import requests

response = requests.get('https://api.weather.com/current', 
                       params={'location': 'San Francisco'},
                       headers={'Authorization': 'Bearer token'})
data = response.json()

MCP World

# Similar standardization for AI agents
data = mcp_client.call_tool('weather_service', 'get_current_weather', {
    'location': 'San Francisco'
})

The Key Insight

HTTP standardized: How browsers request web pages
MCP standardizes: How AI agents request tools and data

Just as HTTP enabled the web ecosystem to flourish (any browser can access any website), MCP enables the AI ecosystem to flourish (any AI agent can use any MCP service).

What This Means for Developers

Before MCP:

Custom integration for every service
Different error handling for each API
Reinventing authentication wheels
Agent-specific tool implementations

With MCP:

One protocol to learn
Consistent error handling
Standardized authentication
Write once, use anywhere tools

The Bigger Picture

MCP is protocol standardization. Like HTTP standardized how browsers communicate with web servers, MCP standardizes how AI agents communicate with services and tools.

When you build an MCP service, any MCP-compatible AI agent can instantly use it. When you build an AI agent, it can instantly use thousands of MCP services.

That's the power of standardization.

Next up: We'll see MCP vs API with a bit more detailed examples.

Quick Takeaways

MCP is a protocol, not an application or framework
Think HTTP for AI - standardizes communication between agents and services
Solves integration complexity that every AI developer faces today
Enables ecosystem growth like HTTP enabled the web

Building Real-time Apps with Rails 8, Hotwire & ActionCable in Production

Chandra Shettigar — Tue, 25 Feb 2025 19:30:18 +0000

Rails 8 brings big improvements to real-time updates with Hotwire and ActionCable. Locally, everything works smoothly—your browser talks directly to the Rails app, and WebSockets handle real-time updates instantly. But in production, things are different:

Web traffic passes through load balancers and Kubernetes (or other orchestration tools).
Jobs run in separate containers, not inside your Rails app.
Redis is no longer required for ActionCable — it can now use your database (MySQL/PostgreSQL).

Let's compare Rails 8 real-time setup in local vs. production and walk through the key changes you need to make.

1. How Rails 8 Handles Real-time Updates Locally

In local development, everything is simple:

Your browser connects directly to Rails (Puma server).
WebSockets are handled inside Puma (/cable endpoint).
Jobs run inside Puma (if using Async adapter).

Flow in Local Setup:

Browser → Puma (Rails) → WebSockets (ActionCable)
          ↑            ↓
         Jobs (ActiveJob, Sidekiq, etc.)

How it Works in Local:

The browser opens a WebSocket connection to /cable.
Turbo Streams subscribe to updates using turbo_stream_from.
When a new message is created in Rails, it:
- Calls broadcast_append_to, which sends the update over WebSockets.
- The UI updates instantly, no page reload needed.

Easy setup—no external dependencies like Redis or a separate database for WebSockets.

2. How Rails 8 Handles Real-time Updates in Production

Once you deploy to AWS + Kubernetes, things change:

Browsers don’t directly talk to Puma. Instead, traffic goes through a load balancer (AWS ALB, NGINX Ingress, etc.).
Jobs run in separate pods (like Sidekiq workers).
WebSockets need to work across multiple app instances.
Redis is no longer required — Rails 8 supports database-backed pub/sub for ActionCable.

Flow in Production Setup:

Browser → AWS Load Balancer → Kubernetes Ingress → Rails Pod (Puma)
                                          |
                                          ├→ Sidekiq Pod (Runs Jobs)
                                          ├→ Database (Stores ActionCable Messages)

How it Works in Production:

The browser opens a WebSocket connection via the load balancer and ingress controller.
ActionCable listens for changes in either Redis or the database (Rails 8 default).
When a job (e.g., a new chat message) runs in a separate container, it:
- Inserts a message into the database (if using DB pub/sub).
- OR Publishes to Redis (if using Redis pub/sub).
ActionCable picks up the new message and sends it to all subscribed clients via WebSockets.

Database-backed ActionCable (Rails 8) reduces dependency on Redis.
Jobs can now update WebSockets even if they run in separate pods.

3. Setting Up WebSockets in Production

Step 1: Configure ActionCable to Use the Database

In Rails 8, you can now store WebSocket updates in MySQL or PostgreSQL instead of Redis.

Edit config/cable.yml:

production:
  adapter: postgresql
  url: postgresql://prod-db-host/myapp_prod

Or Mysql

production:
  adapter: mysql2
  url: mysql2://prod-db-host/myapp_prod

Now, ActionCable will store real-time updates in the database instead of Redis.

Step 2: Create the ActionCable Database Table

Run the migration:

bin/rails action_cable:install
bin/rails db:migrate

This creates a pub/sub table for WebSocket messages.

4. Handling WebSockets with Load Balancers & Kubernetes

AWS Load Balancer: Enable WebSockets

If you're using AWS ALB, make sure WebSockets are enabled:

aws elbv2 modify-listener --load-balancer-arn YOUR_LB_ARN --protocol HTTP2

Kubernetes Ingress: Allow WebSocket Connections

If using NGINX Ingress, add WebSocket support in ingress.yaml:

nginx.ingress.kubernetes.io/websocket-services: "rails-app"
nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"

Now, WebSocket connections won’t be blocked by the load balancer.

5. Updating Real-time Messages in Production

Using Turbo Streams in Rails 8

In your Message model, automatically broadcast updates:

class Message < ApplicationRecord
  after_create_commit do
    broadcast_append_to "chat_room_#{chat_room_id}", target: "messages"
  end
end

This will work locally and in production, regardless of whether you use Redis or the database.

6. Stimulus for Real-time UI Updates

We can use Stimulus to auto-scroll chat messages when new ones arrive.

Create chat_controller.js:

import { Controller } from "@hotwired/stimulus"

export default class extends Controller {
  connect() {
    this.element.addEventListener("turbo:before-stream-render", this.newMessage.bind(this));
  }

  newMessage() {
    this.element.scrollTop = this.element.scrollHeight;
  }
}

Attach It to the Messages Box

<div id="messages" data-controller="chat">
  <%= turbo_stream_from "chat_room_#{chat_room.id}" %>
  <%= render @messages %>
</div>

Now, new messages trigger turbo:before-stream-render, scrolling the chat automatically.

7. Summary: Rails 8 Local vs. Production

Feature	Local (Puma Only)	Production (AWS + K8s)
WebSockets	Handled by Puma	Needs ALB + Ingress Config
Job Execution	Inside Puma	Runs in Sidekiq Pod
Broadcast Mechanism	Direct Turbo Stream	DB Pub/Sub OR Redis
Scaling	Works out of the box	Requires WebSocket Load Balancing

8. Final Thoughts

With Rails 8, real-time updates are easier than ever: No more Redis dependency—ActionCable can now use MySQL/PostgreSQL.

Works with Kubernetes and AWS Load Balancers.
Turbo Streams + Stimulus keep things simple.

Scaling Rails Background Jobs in Kubernetes: From Queue to HPA

Chandra Shettigar — Fri, 21 Feb 2025 05:58:43 +0000

Ever tried processing a million records in a Rails controller action? Yeah, that's not going to end well. Your users will be staring at a spinning wheel, your server will be gasping for resources, and your ops team will be giving you that "we need to talk" look.

The Problem: Long-Running Requests

Picture this: Your Rails app needs to:

Generate complex reports from millions of records
Process large file uploads
Send thousands of notifications
Sync data with external systems

Doing any of these in a controller action means:

Timeout issues (Nginx, Rails, Load Balancer)
Blocked server resources
Poor user experience
Potential data inconsistency if the request fails

Step 1: Moving to Background Processing

First, let's move these long-running tasks to background jobs:

# app/controllers/reports_controller.rb
class ReportsController < ApplicationController
  def create
    report_id = SecureRandom.uuid
    ReportGenerationJob.perform_later(
      user_id: current_user.id,
      report_id: report_id,
      parameters: report_params
    )

    render json: { 
      report_id: report_id,
      status: 'processing',
      status_url: report_status_path(report_id)
    }
  end
end

# app/jobs/report_generation_job.rb
class ReportGenerationJob < ApplicationJob
  queue_as :reports

  def perform(user_id:, report_id:, parameters:)
    # Process report
    report_data = generate_report(parameters)

    # Store results
    store_report(report_id, report_data)

    # Notify user
    ReportMailer.completed(user_id, report_id).deliver_now
  end
end

Great! Now our users get immediate feedback, and our server isn't blocked. But we've just moved the problem - now it's in our job queue.

The Scaling Challenge

A single Rails worker instance with Sidekiq needs proper configuration for queues and concurrency. Here's a basic setup:

# config/initializers/sidekiq.rb
# Note: This is a simplified example to demonstrate the concept.
# Actual syntax might vary based on your Sidekiq version and requirements.

Sidekiq.configure_server do |config|
  # Configure Redis connection
  config.redis = { url: ENV.fetch('REDIS_URL', 'redis://localhost:6379/0') }

  # Configure concurrency based on environment
  config.options[:concurrency] = case Rails.env
    when 'production'
      ENV.fetch('SIDEKIQ_CONCURRENCY', 25).to_i
    else
      10
  end
end

# Queue configuration with weights for priority
config.options[:queues] = [
  ['critical', 5],      # Higher weight = higher priority
  ['sequential', 3],
  ['default', 2],
  ['low', 1]
]

And in your config/sidekiq.yml:

# Note: This is a simplified example. Adjust based on your needs
:verbose: false
:concurrency: <%= ENV.fetch("SIDEKIQ_CONCURRENCY", 25) %>
:timeout: 25

# Environment-specific configurations
production:
  :concurrency: <%= ENV.fetch("SIDEKIQ_CONCURRENCY", 25) %>
  :queues:
    - [critical, 5]
    - [sequential, 3]
    - [default, 2]
    - [low, 1]

This gives us 25 concurrent jobs in production, but what happens when:

We have 1000 reports queued up
Some jobs need to run sequentially (like financial transactions)
Different jobs need different resources
We have mixed workloads (quick jobs vs long-running jobs)

Queue Strategy: Not All Jobs Are Equal

Let's organize our jobs based on their processing requirements:

class FinancialTransactionJob < ApplicationJob
  queue_as :sequential
  sidekiq_options retry: 3, backtrace: true

  def perform(transaction_id)
    # Must process one at a time
    process_transaction(transaction_id)
  end
end

class ReportGenerationJob < ApplicationJob
  queue_as :default
  sidekiq_options retry: 5, backtrace: true

  def perform(report_id)
    # Can process many simultaneously
    generate_report(report_id)
  end
end

class NotificationJob < ApplicationJob
  queue_as :low
  sidekiq_options retry: 3

  def perform(user_ids)
    # Quick jobs, high volume
    send_notifications(user_ids)
  end
end

Enter Kubernetes HPA: Dynamic Worker Scaling

Now we can set up our worker deployment and HPA:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: rails-workers
spec:
  template:
    spec:
      containers:
      - name: sidekiq
        image: myapp/rails:latest
        command: ["bundle", "exec", "sidekiq"]
        env:
        - name: RAILS_ENV
          value: "production"
        - name: SIDEKIQ_CONCURRENCY
          value: "25"
        resources:
          requests:
            memory: "1Gi"
            cpu: "1"
          limits:
            memory: "2Gi"
            cpu: "2"
---
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: rails-workers
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: rails-workers
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Pods
    pods:
      metric:
        name: sidekiq_queue_depth
      target:
        type: AverageValue
        averageValue: 100
  behavior:
    scaleUp:
      stabilizationWindowSeconds: 60
      policies:
      - type: Pods
        value: 2
        periodSeconds: 60
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
      - type: Pods
        value: 1
        periodSeconds: 60

This setup gives us:

Minimum 2 worker pods (50 concurrent jobs)
Maximum 10 worker pods (250 concurrent jobs)
Automatic scaling based on queue depth
Conservative scale-down to prevent thrashing
Resource limits to protect our cluster

Monitoring and Fine-Tuning

To make this work smoothly, monitor:

Queue depths by queue type
Job processing times
Error rates
Resource utilization

Add Prometheus metrics:

# config/initializers/sidekiq.rb
Sidekiq.configure_server do |config|
  config.on(:startup) do
    queue_depth_gauge = Prometheus::Client.registry.gauge(
      :sidekiq_queue_depth,
      docstring: 'Sidekiq queue depth',
      labels: [:queue]
    )

    Sidekiq::Scheduled::Poller.new.poll do
      Sidekiq::Queue.all.each do |queue|
        queue_depth_gauge.set(
          { queue: queue.name },
          queue.size
        )
      end
    end
  end
end

Best Practices and Gotchas

Queue Isolation
- Separate queues for different job types
- Consider dedicated workers for critical queues
- Use queue priorities effectively
Resource Management
- Set appropriate memory/CPU limits
- Monitor job memory usage
- Use batch processing for large datasets
Error Handling
- Implement retry strategies
- Set up dead letter queues
- Monitor failed jobs
Scaling Behavior
- Set appropriate scaling thresholds
- Use stabilization windows
- Consider time-of-day patterns

Conclusion

By combining Rails' background job capabilities with Kubernetes' scaling features, we can build a robust, scalable system for processing long-running tasks. The key is to:

Move long-running tasks to background jobs
Organize queues based on job characteristics
Configure worker processes appropriately
Use HPA for dynamic scaling
Monitor and adjust based on real-world usage

Remember: The goal isn't just to scale - it's to provide a reliable, responsive system that efficiently processes work while maintaining data consistency and user experience.

Authentication Without Complexity: Rails' Built-in Solution

Chandra Shettigar — Sat, 25 Jan 2025 22:52:32 +0000

In an industry where adding a simple login system often means wrestling with gem dependencies and configuration files, Rails has taken a refreshingly contrarian stance: what if authentication could be both secure and simple?

The typical authentication story in web development reads like a cautionary tale: start with a third-party gem, sprinkle in some middleware, juggle configuration files, and pray nothing breaks during the next framework update. It's a complexity tax we've been paying for so long that we've forgotten to question it.

Rails 8 suggests a different path. Let's explore how a single generator command challenges years of authentication complexity.

1. Generate Authentication System

# Generate the authentication system
rails generate authentication

This generates a focused set of files - notably fewer than traditional authentication gems, but that's by design:

# Generated migrations
db/migrate/YYYYMMDDHHMMSS_create_users.rb
db/migrate/YYYYMMDDHHMMSS_create_sessions.rb

# Generated models
app/models/user.rb
app/models/session.rb
app/models/current.rb

# Generated controllers
app/controllers/sessions_controller.rb    # Handles sign in/out
app/controllers/passwords_controller.rb   # Handles password reset

# Generated views
app/views/passwords/new.html.erb         # Password reset request
app/views/passwords/edit.html.erb        # Password reset form

# Generated mailers
app/mailers/passwords_mailer.rb
app/views/passwords_mailer/reset.html.erb
app/views/passwords_mailer/reset.text.erb

2. Set Up Landing Page

# Generate home controller for public landing 
rails generate controller Home index

# config/routes.rb
Rails.application.routes.draw do

  # Authentication routes added
  resource :session
  resources :passwords, param: :token
  # - new_session_path (GET) -> Sign in form
  # - session_path (POST) -> Create session (sign in)
  # - session_path (DELETE) -> Sign out
  # - new_password_path (GET) -> Password reset request
  # - edit_password_path (GET) -> Password reset form
  # - password_path (PATCH) -> Update password

  root "home#index"

  # Some user dashboard 
  resources :dashboard
end

3. Run Migrations

rails db:migrate

This sets up:

Users table with secure password handling
Sessions table for managing sign-ins

4. Add User Registration

Rails intentionally leave registration open-ended - because no two applications handle user signup the same way and it makes sense not to include it in the auth generator. Here's a minimal implementation:

# app/controllers/registrations_controller.rb
class RegistrationsController < ApplicationController
  allow_unauthenticated_access

  def new
    @user = User.new
  end

  def create
    @user = User.new(user_params)

    if @user.save
      # Optionally sign in the user after registration
      start_new_session_for @user
      redirect_to root_path, notice: "Welcome!"
    else
      render :new, status: :unprocessable_entity
    end
  end

  private

  def user_params
    params.require(:user).permit(:email, :password, :password_confirmation)
  end
end

Add the routes:

# config/routes.rb
Rails.application.routes.draw do
  resources :registrations, only: [:new, :create]
  # ... other routes
end

5. Protect Your Controllers

# app/controllers/dashboard_controller.rb
class DashboardController < ApplicationController
  before_action :require_authentication

  def index
    @projects = Current.user.projects
  end
end

# app/controllers/home_controller.rb
class HomeController < ApplicationController
  allow_unauthenticated_access only: [:index]

  def index
    # Your public landing page
  end
end

Key Features You Get For Free

Secure password hashing with bcrypt
Session management with secure tokens
Automatic session resumption across browser restarts
Password reset via email
CSRF protection
Secure post-authentication redirects
XSS protection headers

A Note on Design Philosophy

Rails' authentication system exemplifies a crucial architectural principle: sophistication through simplicity. Instead of the kitchen-sink approach, you get:

Core authentication logic that's secure
Freedom to implement registration and user management your way
No framework lock-in for additional features
Clear separation between authentication and user functionality

This approach acknowledges a truth many frameworks miss: while authentication fundamentals are universal, user management rarely is.

Building Your Own

While Rails now provides authentication out of the box, understanding how to build it from scratch remains valuable. The GoRails tutorial walks through implementing similar functionality manually - a great exercise for understanding the security principles at play.

Remember: the best authentication system isn't the one with the most features, but the one that provides security without sacrificing developer productivity or application flexibility.

AWS App Runner: A quick start deploying Docker Container to AppRunner

Chandra Shettigar — Wed, 07 Aug 2024 17:45:44 +0000

In this article, I'll step-through the simple process of building a containerized app and deploying it to AWS App Runner, creating everything you need from scratch.

You can find all the code in this GitHub repository

Prefer a visual walkthrough? Check out this short video tutorial. And if you prefer reading, keep going.

Building Our Simple Container App

Let's start by creating a basic website. This simple site will consist of just two files:

index.html: The main HTML page for our website.
banner.jpg: A banner image to display on the page.

The index.html file is straightforward. It includes a title, basic styling, a heading, and an image tag to display our banner. Both files are placed in the same directory.

Creating the Dockerfile

Next, we'll create a Dockerfile. This is like a set of instructions for building our Docker image. We'll use a simple Dockerfile that starts with the NGINX image (a popular web server) and copies our website files into the correct location within the NGINX container.

Now, build the Docker image. This should be quick:

docker build -t nginx-website .

Note: I use DevContainer for my local development setup. You can skip this step if you prefer, but if you haven't used it before, I recommend checking it out! DevContainers offer a convenient way to create consistent and isolated development environments. You can learn more here: (1) Local DevOps Setup with DevContainer and (2) Multi-Container Dev Environment for Developers

Pushing to Amazon ECR

To deploy our image, we need a place to store it. We'll use Amazon Elastic Container Registry (ECR), which acts like a container image library. Let's create a repository to hold our image:

aws ecr create-repository --repository-name nginx-ws

The response from this command will include the repository URI where you can push your image. Let's call this .

Tag your Docker image with the ECR repo URI and a version (e.g., v1):

docker tag nginx-website <THE_REPO_URI>:v1

Authenticating with ECR and Pushing the Image

Before pushing the image, we need to authenticate Docker with our ECR repository. AWS uses a two-step process:

Get a temporary password and use that to docker login:

aws ecr get-login-password --region <AWS-REGION> | docker login --username AWS --password-stdin <ECR_REGISTRY_URL>

(Replace with your region and with the registry URL you got from creating the repository.)

Now lets push the image to ECR:

docker push <THE_REPO_URI>:v1

Setting Up IAM Permissions

To deploy the app, App Runner needs permission to access our ECR repository. Let's create an IAM (Identity and Access Management) role for this.

A trust policy for the IAM role first. This allows AppRunner to assume the role.

Create IAM role using the trust policy

aws iam create-role --role-name demo-apprunner-role \
--assume-role-policy-document file://$PWD/aws/trust-policy.json

Now create an IAM policy that grants the necessary permissions to the IAM role.

aws iam create-policy \
--policy-name demo-apprunner-ecr-policy \
--policy-document file://$PWD/aws/apprunner-ecr-policy.json

Attach the Policy to the Role:

aws iam attach-role-policy \
--role-name demo-apprunner-role \
--policy-arn <POLICY_ARN>

Creating the App Runner Service

Finally, let's create our App Runner service. I'll use a YAML configuration file, but you could use other tools like Terraform or CloudFormation too.

This YAML file specifies the service name, the image URL in ECR, and the IAM role ARN for permissions.

Now, run the command to deploy the service:

aws apprunner create-service --cli-input-yaml file://$PWD/apprunner-nginx-service.yml

Verify and Access Your App

It might take a few minutes for your service to be fully deployed. You can check its status in the AWS Management Console or using the AWS CLI:

aws apprunner list-services

Once deployed, you'll get a URL for your app. You can find it in the AWS console or the CLI output. Open that URL in your browser to see your website live on App Runner!

That's it! You've successfully deployed your Dockerized website to AWS App Runner.

Conclusion

AWS App Runner offers a simple and efficient way to deploy Docker containers to the cloud without the complexities of managing infrastructure. It's a great option for quickly getting your applications up and running, but if you're considering it for production, keep in mind a few things:

Scaling: App Runner does offer auto-scaling, but you'll want to make sure it aligns with your traffic patterns and load expectations.
Security: Review App Runner's security features and determine if they meet your specific requirements. You may want to integrate additional security measures like web application firewalls.
Monitoring and Logging: Make sure you have robust monitoring and logging in place to troubleshoot any issues that arise.

Have you already used App Runner in production? I'd love to hear about your experiences and any tips you might have. Feel free to leave a comment below or connect with me on LinkedIn

Easy GitHub Codespaces Setup: Your App, Postgres, and pgAdmin

Chandra Shettigar — Tue, 16 Jul 2024 05:55:38 +0000

I'm a big fan of working in containerized development environments. If I'm developing locally, I always dockerize my apps and use VS Code's DevContainers for a clean, isolated setup. But it gets even better with GitHub Codespaces! It takes your entire environment—your app code, database, and admin tools—and puts them in the cloud, accessible right in your web browser through a VS Code-like interface.

If you already use VS Code and DevContainers, you'll feel right at home with Codespaces. It's a seamless way to take your development to the cloud. If you haven't tried DevContainers yet, be sure to check out my short tutorial for a step-by-step guide to setting up a local containerized environment.

What We're Building:

We're creating a virtual workspace that includes:

Your app: This is the code you're developing. (We'll use a simple example, but you can easily adapt it to your project.)
Postgres database: This stores your app's data.
pgAdmin: This handy tool lets you see and manage what's in your database.

Why GitHub Codespaces?

Works anywhere: No need to set up your computer; just open a web browser.
Consistent setup: Your environment is the same every time.
Easy sharing: Collaborate with others effortlessly.

How It Works (A Quick Overview)

We'll use special files to tell GitHub Codespaces how to build our environment:

devcontainer.json: This controls the overall setup.
docker-compose.yml: This defines our app, database, and pgAdmin.
Dockerfile: This gives instructions for building our app's container.

Step-by-Step Guide

Get the Code:

Fork this repository in your account and go to that repo: https://github.com/devteds/postgres-pgadmin-on-github-codespace-vscode
Click "Code" dropdown and then "Create Codespace."

Watch the Magic: Codespaces will set everything up. This might take a minute.

Check the Containers:

A VS Code window will open in your browser.
Look for the Docker extension to see if everything is running.

Open pgAdmin:

In the Ports tab, find the link for pgAdmin.
It will look like https://-5050.preview.app.github.dev.

Log In to pgAdmin:

Use the username and password from the docker-compose.yml file.
If you get errors, check the file again; there are special settings for Codespaces.

Connect to Your Database:

In pgAdmin, create a new server connection
Use the details from docker-compose.yml

You're Done! You now have a complete development environment ready to use. Start coding your app, and the database and pgAdmin are right there with you!

Bonus Tip: To learn how to set up your app in the Codespace, check out this tutorial: https://www.devteds.com/devcontainers-for-developers-multi-container-local-dev-setup/

Let me know if you have any questions!

I hope this guide helps you discover the power and convenience of containerized development with DevContainers and GitHub Codespaces. Give them a try and see how they can streamline your workflow! If you have any questions, suggestions, or just want to share your experience, feel free to reach out. Happy coding!

Docker Security Checklist: Are You Production Ready?

Chandra Shettigar — Tue, 25 Jun 2024 19:53:22 +0000

You've built a great application using Docker, but are you really ready to push it to production? Before you hit that button, let's make sure your Docker image is secure and reliable.

No Dev Tools in Production

The Docker image you use for testing and development is probably packed with tools and dependencies you don't need in production. This makes it larger and potentially more vulnerable. Keep your production images lean and mean!

Use a Multi-Stage Build

Think of multi-stage builds like a factory assembly line. You build your application in one stage, then create a separate, minimal image in another stage. This final image only contains what's essential for running your app in production, reducing its attack surface.

If you'd like to learn more about multi-stage builds and see a step-by-step example, check out this tutorial: Multi-Stage Docker Build

Scan Your Image for Vulnerabilities

Before pushing your image to a registry or deploying it to production, always scan it for vulnerabilities. Think of this as a security checkpoint for your code.

Tools like Docker Scout can help you identify potential weaknesses in your image and provide recommendations for fixing them. This is a crucial step in ensuring the security of your application before it's exposed to the wider world.

Integrate Security Into Your CI/CD

Integrate image scanning into your Continuous Integration/Continuous Delivery (CI/CD) pipeline. This ensures every image you build for deployment gets a thorough security check before it goes anywhere near production.

Enable Registry Scanning

Many container registries, like AWS Elastic Container Registry (ECR), can automatically scan images when they're pushed. This adds another layer of defense, catching any vulnerabilities that might have slipped through earlier checks.

No Sensitive Data in the Image

Never, ever store sensitive data (passwords, API keys, certificates) directly in your Docker image. Treat your images like postcards: anyone can read them! Use environment variables, secrets management tools, or volume mounts to inject sensitive data at runtime.

Avoid Docker Drift: One Image, All Deployment Environments

Use the same Docker image across all your application environments (testing, staging, production). This reduces the chances of unexpected surprises when you promote your application.

Pro Tip: If you're using multiple Dockerfiles or building environment-specific Docker images, you're probably doing it wrong. This approach often leads to baking configuration details or secrets into your images, which is a major security risk. Keep it simple and use a single image for all environments!

Know Your Base Image

Be picky about your base image. It's the foundation of your Docker image, so choose one that is well-maintained and has a good security track record. Consider using security-hardened images for extra protection.

There are three main ways security vulnerabilities sneak into your container images:

Inherited Vulnerabilities: These come from the base image itself. Using a clean, well-maintained base image is crucial to avoid spending time fixing OS-level issues.
Tool Vulnerabilities: The tools you install for your application can also introduce vulnerabilities. Keep these to a minimum and make sure they're up-to-date.
Application Vulnerabilities: Your own application code can be a source of vulnerabilities. Thorough testing and code review are essential.

Create a Scan Review Process

Don't just scan your images, review the reports! Establish a process to assess vulnerabilities and decide how to handle them. You might fail the build pipeline if new vulnerabilities are found, or you might fix them later. The choice depends on your team's workflow and the level of risk you're willing to accept.

Security Scanning at Runtime

Scanning your images before deployment is important, but don't forget about runtime security. Monitoring your containers in production and having a plan to address any vulnerabilities that emerge is critical. The specific tools you use will depend on your container infrastructure.

Conclusion

Taking a little extra time to ensure your Docker image is secure can save you a lot of headaches down the road. By following these steps, you'll be well on your way to running a secure and reliable application in production.

Rails on Docker - Simplify Your Development with Docker and DevContainers

Chandra Shettigar — Sun, 02 Jun 2024 04:38:21 +0000

Sick of environment inconsistencies causing problems in your Ruby-on-Rails projects? Docker and VSCode Dev Containers let you create a perfectly reproducible and consistent development environment.

Even if you've never used Docker before you'll be surprised how easy it is to get started. No more worrying about messy dependencies or "it works on my machine" issues. Dev Containers lets you create a perfect sandbox for your Ruby-on-Rails projects.

Ready to see it in action? Check out this quick tutorial on Dockerizing a Rails app with Dev Containers in VSCode:

You'll learn how to:

Set up a new Rails project inside a Docker container.
Easily connect your app to a MySQL database (runs as docker container).
Optimize your setup for both development and production.
Code and test your app entirely within VSCode and Docker Desktop

Why use Docker and Dev Containers for Rails?

Consistency: Everyone on your team has the same environment, making collaboration a breeze.
Reproducibility: If something breaks, you can recreate your setup in seconds.
Portability: Take your project anywhere without having to re-install anything.
Isolation: Keep your main system clean and tidy.

I hope this tutorial helps you take your Rails development to the next level. It's a fantastic way to boost your productivity and make your coding life easier.

If you found this helpful, be sure to follow me on LinkedIn and subscribe to my YouTube channel for more tips and tutorials. Happy coding!

Multi-Container Local Development Setup using DevContainers in VSCode

Chandra Shettigar — Mon, 13 May 2024 11:30:00 +0000

As an application or web developer, it’s crucial to have an isolated yet seamless local development setup, especially when managing multiple applications or codebases across various microservice apps built on different programming languages, versions, or frameworks.

If you’ve used Docker for local development, you might be familiar with Docker Compose for handling multiple container setups. While this is helpful in many ways, it requires an extra step of entering a running container to execute ad hoc commands.

For instance, if you’re a Rails developer, you often need to run commands like rails generators, db migrations, rails runner, and especially the rails console. Similar challenges exist for most frameworks.

Imagine if you could open your editor in a container mode that loads the application environment and allow us to run application commands in the embedded terminal, without needing to run commands like docker run, docker exec, etc. This would make working within a containerized environment much easier.

One option that has worked well for my local development setup is the Dev Containers extension in VSCode. Not only does it allow you to load the application in VSCode within a container context, but you can also run dependency services (or other tiers of the application stack) as containers. The Dev Containers extension integrates smoothly with Docker Compose.

In this short tutorial, I’ll guide you through setting up a local development environment for an application that uses a database, both running as containers using Docker Compose and Dev Containers in VSCode. Here’s a quick breakdown of the steps you’ll learn in the tutorial:

Start by creating a Dev Container setup for your application
Create a web application using the Dev Container
Configure a multi-container setup with Dev Container for the application and database containers
Test and verify, mainly database container, using Docker Desktop
Link the application running as a container with the database running as another container
Conclude with a note on Multi-Stage Docker Build with DevContainer & Docker Compose

Setting up a reliable local environment can significantly enhance productivity for app developers. I hope this short video tutorial proves helpful!

VPC Basics for Kubernetes on Amazon EKS

Chandra Shettigar — Tue, 05 Mar 2024 11:30:00 +0000

As Kubernetes gains traction in the tech world, many companies leveraging AWS infrastructure are delving into Amazon EKS (Elastic Kubernetes Service) either to dip their toes or to dive in deep. Whether you are diving headfirst into EKS, AWS’s managed Kubernetes cluster, or crafting your own Kubernetes setup on AWS, understanding the VPC and the networking requirements is essential.

For DevOps engineers and application developers, networking setups might not be your main focus, but understanding the basics can be incredibly helpful. In this article, I’ll give you a simple overview of AWS VPC and using it for Kubernetes on EKS. This won’t cover all the technical details, but it’s a friendly guide for anyone starting out with EKS or Kubernetes on AWS

If you’re eager to get started with EKS and begin deploying microservices, I invite you to explore my k8s course. You’ll learn to create VPC, K8S cluster, and RDS database using Terraform and learn to deploy microservices with routing & load-balancing user traffic using AWS LoadBalancer with Kubernetes.

VPC: Understanding the Basics

VPC, or Virtual Private Cloud, is a fundamental component of AWS that enables users to create a private section of cloud space within the larger public cloud environment. This private section is isolated from other users in the cloud and provides controls to manage access to and from the internet.

With VPC, users are allocated a specific range of IP addresses, allowing them to host a predetermined number of resources or compute instances (such as EC2 instances, Load Balancers, etc.) within the confines of their VPC.

Moreover, VPC facilitates the creation of subnets, which are used to group resources and control access. Subnets enable users to designate which groups of resources can be publicly accessible via public IP addresses, which should be strictly internal with internet connectivity but no incoming connections (private subnets), and which are solely for internal communication (intra subnets). Users have the flexibility to create multiple subnets to suit their needs.

Additionally, VPC allows users to define auto-failover setups at both the VPC and subnet levels by distributing resources across two or more Availability Zones (AZs). In AWS, an AZ represents a distinct physical location within a region, and each AWS region typically consists of two or more AZs. For instance, if you choose “North Virginia” as the AWS region for your VPC, you would configure your setup to span at least two AZs within that region.

Kubernetes and Amazon EKS

Kubernetes, commonly known as K8S, is an open-source container orchestration platform that automates containerized applications' deployment, scaling, and management. It provides a rich set of features for managing containerized workloads, including automated rollouts, self-healing, and scaling based on resource usage.

In Kubernetes infrastructure, two critical components are pivotal: the control plane and the worker nodes. The control plane serves as the brain of the Kubernetes cluster, orchestrating and coordinating various tasks. Conversely, the worker nodes constitute the deployment environment for containerized applications. Managing the control plane is often a complex undertaking in Kubernetes deployments, requiring meticulous attention to detail. This is where Amazon EKS steps in to alleviate the burden, particularly for users operating within the AWS ecosystem.

Amazon EKS, also known as Elastic Kubernetes Service, is AWS’s managed solution for Kubernetes. It simplifies the deployment, management, and scaling of Kubernetes clusters on AWS. With EKS, users can focus on developing and innovating their applications without worrying about managing the complexities of Kubernetes clusters, mainly the Control Plane part. Additionally, EKS seamlessly integrates with various AWS services like Load Balancers, IAM, and CloudWatch, making it easier to manage security, monitor performance, and distribute traffic efficiently.

VPC for Kubernetes on Amazon EKS

When configuring a VPC for a Kubernetes cluster on Amazon EKS, it’s beneficial to establish three types of subnets, each serving distinct purposes: Private Subnets, Public Subnets, and Intra Subnets.

Private Subnets

Private subnets primarily host the worker nodes or the compute instances running the actual application containers. Even applications requiring external access for end-users or customers typically operate within private subnets. In most scenarios, applications need to communicate beyond the VPC boundaries, whether for downloading resources or sending HTTP requests. Therefore, making private subnets the primary environment for worker nodes is often preferred. While exceptions may exist, this setup generally ensures smooth operation.

Public Subnets

Public subnets accommodate resources that necessitate internet access, enabling users from the internet to interact with them. For instance, a website accessible via a web browser typically resides in a public subnet. In the Kubernetes context, containers rarely serve as direct public-facing web servers. Instead, public-facing applications are typically served through Reverse Proxies and Load Balancers. These Load Balancers can be deployed in public subnets.

Utilizing AWS Load Balancer service in Kubernetes via Kubernetes Ingress Controller seamlessly integrates with Amazon EKS. Placing Load Balancers in public subnets enables end-users to access the externally facing Load Balancer’s IP or hostname. The Load Balancer then proxies requests to the target container applications running within the worker node space in private subnets.

Intra Subnets

The control plane, the heart of the Kubernetes cluster, is ideally housed within intra-subnets. From a security standpoint and best practices perspective, restricting internet access to intra-subnets is advisable. This setup ensures that the control plane remains isolated and secure, minimizing potential vulnerabilities.

Conclusion

To wrap up, if AWS is your go-to cloud provider and you’re considering Kubernetes, EKS is a solid choice to kickstart your journey. While there are pros and cons to using EKS versus managing your Kubernetes cluster, EKS typically offers a hassle-free experience. In this brief article, I’ve provided a high-level overview of VPC requirements for Kubernetes. For those eager to dive deeper, I recommend delving into VPC intricacies and exploring EKS further.

If you’re eager to get started with EKS and begin deploying microservices, I invite you to explore my course. In it, I cover essential VPC concepts and guide you through spinning up an EKS cluster using Terraform. We delve into deploying multiple microservices and explore advanced topics like using Ingress Controller with AWS ALB and managing Secret Configs. Dive in and embark on your Kubernetes journey: https://www.devteds.com/kubernetes-course-aws-eks-terraform