DEV Community: Kevin

Git worktree + Claude Code: My Secret to 10x Developer Productivity

Kevin — Fri, 12 Sep 2025 02:05:17 +0000

Recently I discovered what might be the most productivity-boosting workflow change I've made in years. In this article, I'm going to share my experience with combining git worktree and Claude Code to achieve something I never thought possible: working on multiple coding tasks simultaneously without losing my mind to context switching.

The Problem: Context Switching Hell

You know the drill. You're deep in the zone working on feature A, making great progress, when suddenly an urgent bug report comes in. You have to:

Stash your changes or make a hasty commit
Switch branches
Get your head back into the bug's context
Fix it
Switch back to your original work
Try to remember where you left off

By the time you're back to feature A, you've lost precious mental context and momentum. I was doing this dance multiple times a day, and it was killing my productivity.

My Solution: Git Worktree + Claude Code

tl;dr: I create a separate git worktree for each ticket and start a dedicated Claude Code session in each one using multiple iTerm2 panes.

Here's my workflow breakdown:

Create a worktree for each ticket/task
Open multiple iTerm2 panes
Start Claude Code session in each pane
Work on multiple tasks simultaneously

Why Git Worktree?

For those unfamiliar, git worktree allows you to have multiple working directories for the same repository, each checked out to different branches. Think of it as having multiple copies of your project, but they all share the same git history.

Here's how I set it up:

# Create a new worktree for feature branch
git worktree add ../myproject-feature-auth feature/user-authentication

# Create another worktree for bug fix
git worktree add ../myproject-bugfix-login bugfix/login-validation

# List all worktrees
git worktree list

Each worktree is a complete working directory where I can make changes, run tests, and commit without affecting other worktrees.

The Claude Code Magic

Here's where it gets interesting. I open iTerm2 and create multiple panes (Cmd+D and Cmd+Shift+D are your friends). In each pane, I navigate to a different worktree and start a Claude Code session:

# Pane 1: Feature work
cd ~/projects/myproject-feature-auth
claude

# Pane 2: Bug fix work  
cd ~/projects/myproject-bugfix-login
claude

# Pane 3: Code review prep
cd ~/projects/myproject-refactor-api
claude

Each Claude Code session maintains its own context about that specific task. The AI agent understands the branch I'm on, the files I'm working with, and the conversation history related to that particular ticket.

The Benefits Are Game-Changing

High Throughput: I can make progress on 3-4 different tasks in parallel. While Claude is implementing a solution in one pane, I can review its work in another pane or start discussing a different problem.

Minimal Context Switching: Each Claude session requires minimal input from me because it remembers our entire conversation history. I don't have to re-explain the problem every time I switch tasks.

Perfect Context Isolation: Each worktree + Claude session is completely isolated. The AI agent working on the authentication feature has no confusion about the bug fix I'm working on in another pane.

Resume Anywhere: I can leave a task mid-conversation and come back hours (or days) later. The Claude session remembers exactly where we left off, what we were trying to accomplish, and what approaches we had already tried.

Setting Up Your Own Workflow

Here's my recommended setup process:

1. Create your worktree structure:

# From your main project directory
git worktree add ../project-name-ticket-123 feature/ticket-123
git worktree add ../project-name-hotfix-456 hotfix/critical-bug-456

2. Configure iTerm2 panes:

Open iTerm2
Split horizontally: Cmd+Shift+D
Split vertically: Cmd+D
Arrange panes to your preference

3. Start Claude sessions:

# In each pane, navigate to the respective worktree
cd ../project-name-ticket-123
claude

4. Establish context in each session:
Tell each Claude session about the specific task, show relevant code files, and explain what you're trying to accomplish.

What I Learned

From this workflow experiment, I learned that context preservation is more valuable than I initially thought. The ability to maintain multiple concurrent conversations with Claude, each focused on a specific problem domain, eliminates the cognitive overhead of constantly re-establishing context.

The combination works because:

Git worktree solves the technical isolation problem
Claude Code solves the context maintenance problem
Multiple panes solve the switching problem

Trade-offs to Consider

This workflow isn't perfect for everyone:

Resource usage: Running multiple Claude sessions uses more system resources and API calls.

Cognitive load: You still need to mentally track multiple tasks, though the context switching pain is greatly reduced.

Complexity: More moving pieces mean more things that can go wrong (though I haven't encountered issues yet).

Q&A: Addressing the Details

After sharing this workflow with friendds, I got some great questions that deserve clarification:

Q: How do you actually resume Claude sessions after hours or days?

A: Simple - I just don't close the Claude Code session. I keep the terminal panes open, so the session maintains its context forever (or until my machine restarts). No need for export/import.

Q: What about branch synchronization and merge conflicts?

A: I'm assuming a PR workflow here. Each worktree branch eventually opens a PR against main. The isolation means I don't worry about synchronization until PR time.

Q: How do you manage Claude's context window limitations?

A: This is honestly a bottleneck. When the context gets too large, I sometimes need to start fresh or be strategic about what files I show Claude. It's not perfect.

Q: Which tasks actually benefit from this workflow?

A: Features or bugs that are well broken down ahead of time with clear requirements. If you're doing exploratory work or the requirements are fuzzy, this approach might be overkill.

Q: What about running tests across multiple worktrees?

A: Tests run independently in each worktree. As long as you're not using hardcoded ports or shared resources, parallel test execution works fine.

Q: How do you track which pane is which task?

A: iTerm2 tip - press Cmd+I to set a custom session name for each pane. I name them after the ticket number or feature name.

Q: How do you clean up old worktrees?

A: I don't have a cleanup process yet. That's definitely something I need to figure out as my worktree list grows. git worktree prune helps with deleted branches, but manual cleanup is still needed.

What's Next

I'm excited to optimize this workflow further. Some ideas I'm exploring:

Creating shell aliases for quick worktree + Claude session setup
Using tmux for even better session management
Developing a simple script to automate the entire setup process
Building a worktree cleanup routine

This workflow has genuinely transformed how I approach development work. Instead of dreading interruptions and context switches, I now see them as opportunities to make parallel progress on multiple fronts.

Give it a try and let me know how it works for you!

Thanks for your read!

The Complete MCP Guide for Developers(2025 Edition)

Kevin — Sun, 22 Jun 2025 21:23:07 +0000

The Model Context Protocol (MCP) is rapidly becoming the "USB-C" of AI integration—a universal standard that's transforming how we build intelligent applications. If you're a developer who's been watching the AI space evolve, MCP represents a pivotal shift from fragmented, custom integrations to standardized, interoperable AI tooling.

This comprehensive guide will take you from MCP fundamentals to practical implementation, giving you everything you need to understand and leverage this emerging protocol in 2025.

What's New in MCP 2025: The Protocol Matures

Just as USB-C transformed device connectivity, MCP 2025 represents the protocol's evolution from promising standard to enterprise-ready infrastructure. The ecosystem has matured dramatically, with major platforms adopting MCP as their integration backbone and security considerations taking center stage.

The 2025 MCP Landscape

The MCP ecosystem has reached a critical inflection point in 2025. Production deployments have scaled significantly, with enterprise adoption driving new requirements for security, authentication, and remote deployment capabilities. This growth has revealed both opportunities and challenges that the 2025 specification addresses head-on.

Key 2025 Developments:

Enterprise Platform Adoption: Major AI platforms now support MCP natively
Security Maturation: New authentication frameworks and security standards
Deployment Evolution: Remote MCP servers becoming the enterprise standard
Ecosystem Growth: Thousands of production MCP server deployments

Platform Integration Updates

Major AI platforms have embraced MCP as their standard integration layer:

Claude Ecosystem: Enhanced integration across Desktop, Code, and API platforms
Enterprise AI Platforms: Growing adoption in ChatGPT Enterprise and similar services
Development Tools: Native MCP support in major development environments
Enterprise Partnerships: Integration with platforms like Atlassian and Docker

Note: Specific platform adoption details vary by vendor and should be verified with current documentation.

2025 Specification Updates

OAuth 2.1 Authentication Framework

The most significant 2025 update is the adoption of OAuth 2.1 as the standard authentication mechanism, replacing previous token-based approaches:

// OAuth 2.1 Authentication Flow for MCP Servers
class MCPAuthError extends Error {
  constructor(message, code = 'AUTH_ERROR') {
    super(message);
    this.name = 'MCPAuthError';
    this.code = code;
  }
}

class MCPOAuthServer {
  constructor(config) {
    this.validateConfig(config);
    this.clientId = config.clientId;
    this.clientSecret = config.clientSecret;
    this.authServer = config.authorizationServer;
  }

  validateConfig(config) {
    const required = ['clientId', 'clientSecret', 'authorizationServer'];
    for (const field of required) {
      if (!config[field] || typeof config[field] !== 'string') {
        throw new MCPAuthError(`Missing or invalid ${field}`);
      }
    }
  }

  isValidURL(url) {
    try {
      const parsed = new URL(url);
      return ['http:', 'https:'].includes(parsed.protocol);
    } catch {
      return false;
    }
  }

  // Exchange authorization code for access token
  async authenticateClient(authCode, redirectUri) {
    // Comprehensive input validation
    if (!authCode || typeof authCode !== 'string' || authCode.length < 10) {
      throw new MCPAuthError('Invalid authorization code format', 'INVALID_CODE');
    }

    if (!redirectUri || !this.isValidURL(redirectUri)) {
      throw new MCPAuthError('Invalid redirect URI', 'INVALID_REDIRECT');
    }

    const tokenRequest = {
      grant_type: 'authorization_code',
      code: authCode,
      redirect_uri: redirectUri,
      client_id: this.clientId,
      client_secret: this.clientSecret
    };

    // Proper URLSearchParams usage
    const params = new URLSearchParams();
    Object.entries(tokenRequest).forEach(([key, value]) => {
      params.append(key, String(value));
    });

    try {
      const response = await fetch(`${this.authServer}/oauth/token`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          'Accept': 'application/json',
          'User-Agent': 'MCP-Server/2.0.0'
        },
        body: params.toString(),
        timeout: 10000 // 10 second timeout
      });

      if (!response.ok) {
        const errorData = await response.json().catch(() => ({}));
        throw new MCPAuthError(
          `Token exchange failed: ${errorData.error || response.statusText}`,
          'TOKEN_EXCHANGE_FAILED'
        );
      }

      const tokenData = await response.json();

      // Validate token response
      if (!tokenData.access_token) {
        throw new MCPAuthError('Invalid token response', 'INVALID_TOKEN_RESPONSE');
      }

      return tokenData;
    } catch (error) {
      if (error instanceof MCPAuthError) {
        throw error;
      }
      throw new MCPAuthError(`Authentication failed: ${error.message}`, 'AUTH_FAILED');
    }
  }
}

Enhanced Transport Layer

The new Streamable HTTP transport provides better performance and reliability than the previous HTTP+SSE implementation:

// Streamable HTTP Transport Implementation
import { StreamableHTTPTransport } from '@modelcontextprotocol/sdk/transport/streamable-http.js';

class ModernMCPServer {
  constructor() {
    this.server = new Server(
      { name: 'modern-server', version: '2.0.0' },
      { 
        capabilities: { 
          tools: {},
          streaming: true,
          authentication: { oauth2: true }
        } 
      }
    );
  }

  setupTransport() {
    return new StreamableHTTPTransport({
      port: process.env.PORT || 3000,
      path: '/mcp',
      cors: {
        origin: process.env.ALLOWED_ORIGINS?.split(','),
        credentials: true
      },
      authentication: {
        strategy: 'oauth2',
        requiredScopes: ['mcp:tools', 'mcp:resources']
      }
    });
  }
}

What is MCP and Why Should You Care?

The Model Context Protocol is an open standard designed to standardize how AI applications—especially those using large language models (LLMs)—interact with external tools, data sources, and APIs. Think of it as a state management layer specifically designed for AI agents, enabling persistent, structured context exchange between AI models and their operational environments.

The Problem MCP Solves

Before MCP, every AI integration was a snowflake:

Custom connectors for every tool, database, or API
No standardization across different AI platforms
Fragmented context management leading to inconsistent agent behavior
Security vulnerabilities from ad-hoc integrations
Scalability nightmares when managing multiple AI tools

MCP addresses these challenges by providing a unified protocol for AI-to-tool communication, similar to how HTTP standardized web communication or how TCP/IP standardized network protocols.

Key Benefits for Developers

Standardization: Write once, integrate everywhere
Scalability: Modular design supports complex AI deployments
Persistent Context: Enables stateful, multi-turn AI interactions
Interoperability: Open standard with growing ecosystem support
Security: Built-in authentication and access controls

Security in MCP 2025: Critical Considerations

The rapid growth of the MCP ecosystem has revealed significant security challenges that developers must address. Understanding and implementing proper security measures is crucial for production MCP deployments.

The Security Challenge

As MCP adoption has grown, security researchers have identified common vulnerability patterns in deployed servers. While specific statistics vary by deployment context, common issues include:

Command Injection Vulnerabilities: Improper input validation in tool implementations
Insufficient Input Validation: Lack of sanitization for user-provided parameters
Privilege Escalation: Misconfigured tool permissions allowing unauthorized access
Authentication Implementation Flaws: Incorrect OAuth 2.1 implementations
Resource Exhaustion: Lack of proper rate limiting and resource management

Note: Security vulnerability rates should be verified through current security research and audit reports.

Command Injection Prevention

Command injection is a critical concern for MCP servers that execute system commands:

// ❌ VULNERABLE: Direct command execution
async function vulnerableExecute(command) {
  const { exec } = require('child_process');
  return new Promise((resolve, reject) => {
    exec(command, (error, stdout) => {
      if (error) reject(error);
      else resolve(stdout);
    });
  });
}

// ✅ SECURE: Parameterized command execution
class SecurityError extends Error {
  constructor(message) {
    super(message);
    this.name = 'SecurityError';
  }
}

class SecureCommandExecutor {
  constructor() {
    // Strict allowlist approach
    this.allowedCommands = new Map([
      ['git_status', {
        command: ['git', 'status', '--porcelain'],
        allowedArgs: ['--help', '--verbose']
      }],
      ['list_files', {
        command: ['ls', '-la'],
        allowedArgs: []
      }],
      ['disk_usage', {
        command: ['df', '-h'],
        allowedArgs: []
      }]
    ]);
  }

  async executeCommand(commandName, args = []) {
    const commandConfig = this.allowedCommands.get(commandName);
    if (!commandConfig) {
      throw new SecurityError(`Command '${commandName}' not allowed`);
    }

    // Strict argument validation
    const validatedArgs = this.validateArgs(args, commandConfig.allowedArgs);
    const fullCommand = [...commandConfig.command, ...validatedArgs];

    return await this.executeSecurely(fullCommand);
  }

  validateArgs(args, allowedArgs) {
    const validatedArgs = [];

    for (const arg of args) {
      if (typeof arg !== 'string') {
        throw new SecurityError('All arguments must be strings');
      }

      // Comprehensive sanitization
      if (this.containsDangerousCharacters(arg)) {
        throw new SecurityError('Argument contains dangerous characters');
      }

      // Allowlist validation
      if (!allowedArgs.includes(arg)) {
        throw new SecurityError(`Argument '${arg}' not allowed`);
      }

      validatedArgs.push(arg);
    }

    return validatedArgs;
  }

  containsDangerousCharacters(str) {
    // Comprehensive dangerous character detection
    const dangerousPatterns = [
      /[;&|`$()><\\*?[\]{}]/,  // Shell metacharacters
      /[\n\r\t\f\v\0]/,          // Control characters
      /["']/,                   // Quote characters
      /\.\.|\/..\//,            // Path traversal
      /^-/,                     // Option injection
    ];

    return dangerousPatterns.some(pattern => pattern.test(str));
  }

  async executeSecurely(command) {
    const { spawn } = require('child_process');

    return new Promise((resolve, reject) => {
      // Secure process execution
      const process = spawn(command[0], command.slice(1), {
        stdio: ['ignore', 'pipe', 'pipe'],
        timeout: 30000,
        detached: false,
        uid: 1001,     // Non-root user
        gid: 1001,     // Non-root group
        env: {},       // Empty environment
        cwd: '/tmp',   // Safe working directory
        shell: false   // CRITICAL: Never use shell
      });

      let stdout = '';
      let stderr = '';

      process.stdout.on('data', (data) => {
        stdout += data;
        // Prevent memory exhaustion
        if (stdout.length > 1024 * 1024) { // 1MB limit
          process.kill('SIGTERM');
          reject(new SecurityError('Output too large'));
        }
      });

      process.stderr.on('data', (data) => {
        stderr += data;
      });

      process.on('close', (code, signal) => {
        if (signal) {
          reject(new SecurityError(`Process terminated by signal: ${signal}`));
        } else if (code === 0) {
          resolve({ stdout, stderr, success: true });
        } else {
          reject(new SecurityError(`Command failed with code ${code}: ${stderr}`));
        }
      });

      process.on('error', (error) => {
        reject(new SecurityError(`Process error: ${error.message}`));
      });

      // Ensure process cleanup
      setTimeout(() => {
        if (!process.killed) {
          process.kill('SIGTERM');
          reject(new SecurityError('Process timeout'));
        }
      }, 30000);
    });
  }
}

Input Validation Framework

Implement comprehensive input validation for all tool parameters:

class ValidationError extends Error {
  constructor(message) {
    super(message);
    this.name = 'ValidationError';
  }
}

class MCPInputValidator {
  constructor() {
    this.validators = new Map();
    this.setupCommonValidators();
  }

  setupCommonValidators() {
    this.validators.set('string', this.validateString);
    this.validators.set('integer', this.validateInteger);
    this.validators.set('email', this.validateEmail);
    this.validators.set('url', this.validateURL);
  }

  validateString(value, constraints = {}) {
    if (typeof value !== 'string') {
      throw new ValidationError('Value must be a string');
    }

    if (constraints.maxLength && value.length > constraints.maxLength) {
      throw new ValidationError(`String exceeds maximum length`);
    }

    // Check for potential injection attempts
    const dangerousPatterns = [
      /[<>]/g,           // HTML/XML injection
      /['"`;]/g,         // SQL injection
      /\$\{|\$\(/g,      // Template injection
      /eval\(|exec\(/g,  // Code injection
      /javascript:/gi    // XSS attempts
    ];

    for (const pattern of dangerousPatterns) {
      if (pattern.test(value)) {
        throw new SecurityError('Input contains potentially dangerous content');
      }
    }

    return value;
  }

  async validateToolCall(toolName, args, schema) {
    const tool = schema.tools.find(t => t.name === toolName);
    if (!tool) {
      throw new ValidationError(`Unknown tool: ${toolName}`);
    }

    const validatedArgs = {};

    for (const [paramName, paramConfig] of Object.entries(tool.parameters)) {
      const value = args[paramName];

      if (paramConfig.required && value === undefined) {
        throw new ValidationError(`Missing required parameter: ${paramName}`);
      }

      if (value !== undefined) {
        const validator = this.validators.get(paramConfig.type);
        if (validator) {
          validatedArgs[paramName] = validator(value, paramConfig.constraints);
        }
      }
    }

    return validatedArgs;
  }
}

MCP Architecture: Understanding the Components

MCP introduces a layered, modular architecture with several key components:

Core Components

MCP Clients

Interfaces (chatbots, apps, APIs) that initiate protocol requests
Submit contextual metadata and handle responses
Examples: Claude Desktop, custom AI applications

MCP Servers

Middleware that exposes tools, resources, and capabilities
Manages context, enforces access controls, and executes tool logic
Examples: Database connectors, API wrappers, file system servers

MCP Hosts

AI applications that require access to external resources
Orchestrate communication between clients and servers
Handle session management and context assembly

Transport Layer

Handles communication between components
Supports HTTP, Server-Sent Events (SSE), and other protocols
Manages connection lifecycle and error handling

Protocol Flow

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Client    │◄──►│    Host     │◄──►│   Server    │
│             │    │             │    │             │
│ (Interface) │    │ (AI Agent)  │    │ (Tools/Data)│
└─────────────┘    └─────────────┘    └─────────────┘

Discovery: Client requests available tools from server
Context Assembly: Host gathers relevant context and tools
Agent Processing: AI agent reasons over available context and tools
Tool Invocation: Host executes tool calls based on agent output
Response: Results flow back through the chain

Local vs Remote MCP Servers: Deployment Strategies

The MCP ecosystem now supports both local and remote server deployments. Understanding when to use each approach is crucial for building effective MCP implementations.

Local MCP Servers

Local servers run on the same machine as the MCP client, using direct process communication.

When to Use Local Servers:

High security requirements (data never leaves local environment)
Low latency needs (direct process communication)
Development and testing scenarios
Offline operation requirements
Resource-intensive operations needing local compute

Local Server Implementation

// Local MCP Server with Stdio Transport
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

class LocalFileSystemServer {
  constructor() {
    this.server = new Server(
      { name: 'local-filesystem', version: '2.0.0' },
      { 
        capabilities: { 
          tools: {},
          resources: {},
          local_execution: true
        } 
      }
    );

    this.setupLocalTools();
  }

  setupLocalTools() {
    this.server.setRequestHandler('tools.list', async () => ({
      tools: [
        {
          name: 'read_local_file',
          description: 'Read file from local filesystem',
          parameters: {
            path: { 
              type: 'string', 
              required: true,
              constraints: {
                pattern: '^/[^\\0]*$', // Unix path validation
                maxLength: 4096
              }
            }
          }
        }
      ]
    }));
  }

  async run() {
    const transport = new StdioServerTransport();
    await this.server.connect(transport);
    console.error('Local MCP server running...');
  }
}

Remote MCP Servers

Remote servers run as independent services, accessible over network protocols.

When to Use Remote Servers:

Multiple client support
Centralized management and updates
Resource pooling across users
Enterprise integration requirements
Multi-tenant deployments

Remote Server Implementation

// Remote MCP Server with HTTP Transport
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StreamableHTTPTransport } from '@modelcontextprotocol/sdk/transport/streamable-http.js';

class RemoteDatabaseServer {
  constructor() {
    this.server = new Server(
      { name: 'remote-database', version: '2.0.0' },
      { 
        capabilities: { 
          tools: {},
          streaming: true,
          multi_tenant: true,
          remote_execution: true
        } 
      }
    );

    this.setupRemoteTools();
    this.setupAuthentication();
  }

  setupRemoteTools() {
    this.server.setRequestHandler('tools.call', async (request) => {
      const userContext = await this.authenticateUser(request);
      const { name, arguments: args } = request.params;

      // Validate user permissions
      await this.validateUserAccess(userContext.userId, name, args);

      // Execute with monitoring
      return await this.executeToolWithMonitoring(name, args, userContext);
    });
  }

  async run() {
    const transport = new StreamableHTTPTransport({
      port: process.env.PORT || 3000,
      path: '/mcp',
      authentication: {
        strategy: 'oauth2',
        config: {
          authorizationServer: process.env.AUTH_SERVER_URL,
          clientId: process.env.CLIENT_ID,
          requiredScopes: ['mcp:database']
        }
      }
    });

    await this.server.connect(transport);
    console.log(`Remote MCP server running on port ${process.env.PORT || 3000}`);
  }
}

How MCP Actually Works: A Technical Deep Dive

Understanding Agent Driver vs. Agent Logic

One of the most important concepts in MCP is the separation between the Agent Driver (host application logic) and Agent Logic (the LLM/AI model itself).

Agent Logic (LLM/Agent):

Receives structured context including available tools and their schemas
Reasons about which tools to use based on the current task
Outputs structured responses indicating tool calls or final answers
Does NOT need to understand MCP protocol details

Agent Driver (Host/Application):

Assembles context from MCP servers according to protocol
Parses agent outputs to determine next actions
Handles tool invocation through MCP protocol
Manages sessions, authentication, and error handling

Tool Discovery and Invocation

Here's how a typical MCP interaction works:

1. Tool Discovery

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools.list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "name": "get_user",
      "description": "Fetches user information by user_id",
      "parameters": {
        "user_id": { "type": "string", "required": true }
      }
    },
    {
      "name": "send_email",
      "description": "Sends email to specified recipient",
      "parameters": {
        "to": { "type": "string", "required": true },
        "subject": { "type": "string", "required": true },
        "body": { "type": "string", "required": true }
      }
    }
  ]
}

2. Tool Invocation

Request:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools.call",
  "tool": "get_user",
  "args": { "user_id": "123" }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "user_id": "123",
    "name": "John Doe",
    "email": "john@example.com",
    "status": "active"
  }
}

Context Management and Sessions

MCP excels at managing persistent context across multi-turn interactions. Here's what you typically need to store:

Session Data Structure:

{
  userId: "user_123",
  sessionId: "session_456", 
  context: {
    conversationHistory: [...],
    toolStates: {...},
    userPreferences: {...},
    activeWorkflow: {...}
  },
  metadata: {
    createdAt: "2025-06-22T10:00:00Z",
    lastActivity: "2025-06-22T10:30:00Z"
  }
}

Building Your First MCP Server

Let's build a practical example: a simple file system MCP server with enhanced security.

Step 1: Basic Server Structure

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import fs from 'fs/promises';
import path from 'path';

class FileSystemMCPServer {
  constructor() {
    this.server = new Server(
      { name: 'filesystem-server', version: '2.0.0' },
      { capabilities: { tools: {} } }
    );

    this.setupTools();
    this.inputValidator = new MCPInputValidator();
  }

  setupTools() {
    // Register available tools
    this.server.setRequestHandler('tools.list', async () => ({
      tools: [
        {
          name: 'read_file',
          description: 'Read contents of a file',
          parameters: {
            path: { 
              type: 'string', 
              required: true,
              constraints: {
                maxLength: 4096,
                pattern: '^[a-zA-Z0-9._/-]+$'
              }
            }
          }
        },
        {
          name: 'write_file', 
          description: 'Write content to a file',
          parameters: {
            path: { 
              type: 'string', 
              required: true,
              constraints: {
                maxLength: 4096,
                pattern: '^[a-zA-Z0-9._/-]+$'
              }
            },
            content: { 
              type: 'string', 
              required: true,
              constraints: {
                maxLength: 1048576 // 1MB limit
              }
            }
          }
        },
        {
          name: 'list_directory',
          description: 'List files in a directory',
          parameters: {
            path: { 
              type: 'string', 
              required: true,
              constraints: {
                maxLength: 4096,
                pattern: '^[a-zA-Z0-9._/-]+$'
              }
            }
          }
        }
      ]
    }));

    // Handle tool invocations with security validation
    this.server.setRequestHandler('tools.call', async (request) => {
      const { name, arguments: args } = request.params;

      // Validate input
      const validatedArgs = await this.inputValidator.validateToolCall(
        name, 
        args, 
        await this.server.request('tools.list')
      );

      switch (name) {
        case 'read_file':
          return await this.readFile(validatedArgs.path);
        case 'write_file':
          return await this.writeFile(validatedArgs.path, validatedArgs.content);
        case 'list_directory':
          return await this.listDirectory(validatedArgs.path);
        default:
          throw new Error(`Unknown tool: ${name}`);
      }
    });
  }

  async readFile(filePath) {
    try {
      // Additional security: resolve path and check it's within allowed directory
      const resolvedPath = path.resolve(filePath);
      const allowedDir = path.resolve('./allowed_files');

      if (!resolvedPath.startsWith(allowedDir)) {
        throw new SecurityError('Access denied: path outside allowed directory');
      }

      const content = await fs.readFile(resolvedPath, 'utf-8');
      return { content, success: true };
    } catch (error) {
      return { error: error.message, success: false };
    }
  }

  async writeFile(filePath, content) {
    try {
      const resolvedPath = path.resolve(filePath);
      const allowedDir = path.resolve('./allowed_files');

      if (!resolvedPath.startsWith(allowedDir)) {
        throw new SecurityError('Access denied: path outside allowed directory');
      }

      await fs.writeFile(resolvedPath, content, 'utf-8');
      return { message: 'File written successfully', success: true };
    } catch (error) {
      return { error: error.message, success: false };
    }
  }

  async listDirectory(dirPath) {
    try {
      const resolvedPath = path.resolve(dirPath);
      const allowedDir = path.resolve('./allowed_files');

      if (!resolvedPath.startsWith(allowedDir)) {
        throw new SecurityError('Access denied: path outside allowed directory');
      }

      const files = await fs.readdir(resolvedPath);
      return { files, success: true };
    } catch (error) {
      return { error: error.message, success: false };
    }
  }

  async run() {
    const transport = new StdioServerTransport();
    await this.server.connect(transport);
    console.error('File System MCP Server running...');
  }
}

// Start the server
const server = new FileSystemMCPServer();
server.run().catch(console.error);

Step 2: Adding Session Management

For production servers, you'll want persistent session storage:

import { Redis } from 'ioredis';

class SessionManager {
  constructor() {
    this.redis = new Redis(process.env.REDIS_URL);
  }

  async getSession(sessionId) {
    const data = await this.redis.get(`session:${sessionId}`);
    return data ? JSON.parse(data) : null;
  }

  async updateSession(sessionId, context) {
    await this.redis.setex(
      `session:${sessionId}`, 
      3600, // 1 hour TTL
      JSON.stringify(context)
    );
  }

  async createSession(userId) {
    const sessionId = `session_${Date.now()}_${Math.random().toString(36)}`;
    const context = {
      userId,
      createdAt: new Date().toISOString(),
      conversationHistory: [],
      toolStates: {}
    };

    await this.updateSession(sessionId, context);
    return sessionId;
  }
}

Enterprise Deployment Patterns

Enterprise MCP deployments require sophisticated patterns optimized for scale, security, and reliability. Here are proven approaches from production deployments.

Containerized Deployment with Docker

# Production MCP Server Dockerfile
FROM node:18-alpine AS base

# Security: Run as non-root user
RUN addgroup -g 1001 -S mcpuser && \
    adduser -S mcpuser -u 1001

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm ci --only=production && npm cache clean --force

# Copy application code
COPY --chown=mcpuser:mcpuser . .

# Health check endpoint
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node healthcheck.js

USER mcpuser
EXPOSE 3000

CMD ["node", "server.js"]

Kubernetes Deployment

# Production Kubernetes Deployment
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-server
  namespace: mcp-production
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  selector:
    matchLabels:
      app: mcp-server
  template:
    metadata:
      labels:
        app: mcp-server
      annotations:
        container.apparmor.security.beta.kubernetes.io/mcp-server: runtime/default
    spec:
      serviceAccountName: mcp-server
      securityContext:
        runAsNonRoot: true
        runAsUser: 1001
        runAsGroup: 1001
        fsGroup: 1001
        seccompProfile:
          type: RuntimeDefault
      containers:
      - name: mcp-server
        image: company/mcp-server:v2.0.0
        ports:
        - containerPort: 3000
          protocol: TCP
        resources:
          requests:
            memory: 256Mi
            cpu: 100m
          limits:
            memory: 512Mi
            cpu: 250m
        securityContext:
          allowPrivilegeEscalation: false
          readOnlyRootFilesystem: true
          runAsNonRoot: true
          runAsUser: 1001
          capabilities:
            drop: ["ALL"]
        volumeMounts:
        - name: tmp-volume
          mountPath: /tmp
        - name: cache-volume
          mountPath: /app/.cache
        livenessProbe:
          httpGet:
            path: /health
            port: 3000
          initialDelaySeconds: 30
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /ready
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 10
        env:
        - name: NODE_ENV
          value: production
        - name: MCP_LOG_LEVEL
          value: info
      volumes:
      - name: tmp-volume
        emptyDir: {}
      - name: cache-volume
        emptyDir: {}
      automountServiceAccountToken: false
      dnsPolicy: ClusterFirst
      restartPolicy: Always

MCP vs. Other Protocols: Where It Fits

Understanding how MCP compares to familiar protocols helps clarify its purpose:

Protocol	Layer/Domain	Purpose	Limitations for AI
TCP/IP	Network transport	Reliable data transmission	Not context- or AI-aware
REST	Web APIs	Simple, stateless resource access	No built-in context memory
GraphQL	Web APIs	Flexible, client-driven queries	Lacks persistent AI context
gRPC	Web APIs/RPC	High-performance, typed APIs	Not designed for AI context
MCP	AI context exchange	Persistent, structured, multi-agent context	More complex, newer ecosystem

MCP operates at the application context layer, not as a transport protocol. It defines how to structure, persist, and exchange context between AI agents and external systems, while potentially using HTTP, gRPC, or other protocols for actual data transport.

Storage Strategies for MCP Servers

In-Memory Storage (Development/Simple Cases)

class InMemorySessionStore {
  constructor() {
    this.sessions = new Map();
  }

  get(sessionId) {
    return this.sessions.get(sessionId);
  }

  set(sessionId, context) {
    this.sessions.set(sessionId, context);
  }
}

Redis (Production/Distributed)

class RedisSessionStore {
  constructor(redisUrl) {
    this.redis = new Redis(redisUrl);
  }

  async get(sessionId) {
    const data = await this.redis.get(`mcp:session:${sessionId}`);
    return data ? JSON.parse(data) : null;
  }

  async set(sessionId, context, ttl = 3600) {
    await this.redis.setex(
      `mcp:session:${sessionId}`,
      ttl,
      JSON.stringify(context)
    );
  }
}

SQL with JSON (Structured + Flexible)

CREATE TABLE mcp_sessions (
  session_id VARCHAR(255) PRIMARY KEY,
  user_id VARCHAR(255),
  context JSON,
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

Advanced Security Best Practices

1. Authentication and Authorization

// Enhanced middleware for MCP server
class AuthenticationError extends Error {
  constructor(message) {
    super(message);
    this.name = 'AuthenticationError';
  }
}

class AuthorizationError extends Error {
  constructor(message) {
    super(message);
    this.name = 'AuthorizationError';
  }
}

async function authenticateRequest(request) {
  const token = request.headers.authorization?.replace('Bearer ', '');
  if (!token) throw new AuthenticationError('Authentication required');

  const user = await verifyToken(token);
  if (!user) throw new AuthenticationError('Invalid token');

  return user;
}

// Tool-level permissions
async function checkToolPermissions(user, toolName) {
  const permissions = await getUserPermissions(user.id);
  if (!permissions.tools.includes(toolName)) {
    throw new AuthorizationError(`Access denied for tool: ${toolName}`);
  }
}

2. Enhanced Input Validation

function validateToolCall(toolName, args, schema) {
  const tool = schema.tools.find(t => t.name === toolName);
  if (!tool) throw new Error(`Unknown tool: ${toolName}`);

  // Validate required parameters
  for (const [param, config] of Object.entries(tool.parameters)) {
    if (config.required && !(param in args)) {
      throw new Error(`Missing required parameter: ${param}`);
    }
  }

  // Type validation, sanitization, etc.
  return true;
}

3. Rate Limiting

class RateLimiter {
  constructor(windowMs = 60000, maxRequests = 100) {
    this.windowMs = windowMs;
    this.maxRequests = maxRequests;
    this.requests = new Map();
  }

  async checkLimit(userId) {
    const now = Date.now();
    const userRequests = this.requests.get(userId) || [];

    // Remove old requests outside window
    const validRequests = userRequests.filter(
      time => now - time < this.windowMs
    );

    if (validRequests.length >= this.maxRequests) {
      throw new Error('Rate limit exceeded');
    }

    validRequests.push(now);
    this.requests.set(userId, validRequests);
  }
}

Performance Optimization and Scaling

Caching Strategies

class MCPCache {
  constructor(ttl = 300000) { // 5 minutes
    this.cache = new Map();
    this.ttl = ttl;
  }

  async get(key, fetcher) {
    const cached = this.cache.get(key);
    if (cached && Date.now() - cached.timestamp < this.ttl) {
      return cached.data;
    }

    const data = await fetcher();
    this.cache.set(key, { data, timestamp: Date.now() });
    return data;
  }
}

Load Balancing Multiple Servers

class MCPServerPool {
  constructor(servers) {
    this.servers = servers;
    this.currentIndex = 0;
  }

  getNextServer() {
    const server = this.servers[this.currentIndex];
    this.currentIndex = (this.currentIndex + 1) % this.servers.length;
    return server;
  }

  async executeToolCall(toolName, args) {
    const server = this.getNextServer();
    try {
      return await server.callTool(toolName, args);
    } catch (error) {
      // Fallback to next server if available
      if (this.servers.length > 1) {
        const fallbackServer = this.getNextServer();
        return await fallbackServer.callTool(toolName, args);
      }
      throw error;
    }
  }
}

Testing MCP Implementations

Unit Testing Tools

import { jest } from '@jest/globals';
import { MCPTestClient } from '@modelcontextprotocol/sdk/test';

describe('FileSystem MCP Server', () => {
  let testClient;
  let server;

  beforeEach(async () => {
    server = new FileSystemMCPServer();
    testClient = new MCPTestClient(server);
    await testClient.connect();
  });

  test('should list available tools', async () => {
    const response = await testClient.request('tools.list');
    expect(response.tools).toHaveLength(3);
    expect(response.tools[0].name).toBe('read_file');
  });

  test('should read file successfully', async () => {
    const result = await testClient.callTool('read_file', {
      path: '/tmp/test.txt'
    });
    expect(result.success).toBe(true);
  });
});

Integration Testing

describe('MCP Integration Tests', () => {
  test('should handle complete workflow', async () => {
    const client = new MCPClient('http://localhost:3000/mcp');

    // 1. Discover tools
    const tools = await client.listTools();
    expect(tools).toContain('create_user');

    // 2. Execute workflow
    const user = await client.callTool('create_user', {
      name: 'Test User',
      email: 'test@example.com'
    });

    const profile = await client.callTool('get_user', {
      user_id: user.id
    });

    expect(profile.name).toBe('Test User');
  });
});

Common Pitfalls and How to Avoid Them

1. Over-Engineering Context Storage

Problem: Storing every piece of information in session context
Solution: Only persist what's necessary for continuity

// ❌ Too much context
const badContext = {
  fullConversationHistory: [...], // Massive array
  allToolResults: {...},          // Everything ever called
  userBrowsingHistory: [...],     // Unnecessary data
};

// ✅ Focused context
const goodContext = {
  recentMessages: messages.slice(-10),     // Last 10 messages
  activeWorkflow: currentWorkflow,         // Current task state
  userPreferences: essentialPrefs,         // Only relevant prefs
};

2. Ignoring Error Handling

// ❌ Poor error handling
async function callTool(name, args) {
  return await server.invoke(name, args);
}

// ✅ Robust error handling
async function callTool(name, args) {
  try {
    return await server.invoke(name, args);
  } catch (error) {
    if (error.code === 'RATE_LIMITED') {
      await delay(1000);
      return await server.invoke(name, args);
    }

    throw new MCPError(`Tool '${name}' failed: ${error.message}`, {
      tool: name,
      args,
      originalError: error
    });
  }
}

3. Security Vulnerabilities

// ❌ Exposing sensitive operations
tools: [
  {
    name: 'execute_command',
    description: 'Execute any shell command',
    // This is dangerous!
  }
]

// ✅ Secure, limited operations
tools: [
  {
    name: 'get_system_status',
    description: 'Get basic system health metrics',
    // Safe, read-only operation
  }
]

The Future of MCP

Emerging Trends

Standardization Across Platforms: Major AI providers are adopting MCP
Marketplace Ecosystems: MCP server marketplaces are emerging
Visual Development Tools: Low-code MCP server builders
Industry Specialization: Vertical-specific MCP implementations

What This Means for Developers

Career Opportunities: MCP expertise is becoming valuable
Architecture Decisions: New projects should consider MCP-first design
Skill Development: Understanding both AI and integration patterns is crucial
Ecosystem Participation: Contributing to open-source MCP tools builds reputation

Getting Started: Your Next Steps

1. Experiment with Existing Tools

Try Claude Desktop with MCP servers
Explore the official MCP server repository
Join the MCP community discussions

2. Build Your First Server

Start with a simple file system or database connector
Focus on one tool/capability initially
Test with the MCP inspector tool

3. Contribute to the Ecosystem

Open-source your MCP servers
Document your implementations
Share learnings with the community

4. Stay Updated

Follow MCP specification updates
Monitor ecosystem developments
Engage with other MCP developers

Conclusion

The Model Context Protocol represents a fundamental shift in how we build AI-integrated applications. By providing a standardized way to manage context, tools, and persistent state, MCP enables developers to create more sophisticated, reliable, and scalable AI systems.

As a developer, understanding MCP positions you at the forefront of the AI infrastructure revolution. Whether you're building the next generation of AI-powered SaaS applications, contributing to the growing ecosystem of MCP tools, or transitioning your career toward AI infrastructure engineering, MCP provides the foundation for the future of intelligent software.

The protocol has evolved significantly in 2025, with enhanced security features, OAuth 2.1 authentication, and enterprise-ready deployment patterns. While challenges remain around security implementation and ecosystem standardization, the growing adoption by major platforms signals MCP's importance in the AI infrastructure landscape.

Start building, start experimenting, and join the community of developers who are defining how AI and traditional software systems will work together in the years to come.

Want to dive deeper? Check out the official MCP documentation and explore the growing collection of open-source MCP servers to see real-world implementations in action.