Getting Started with Model Context Protocol (MCP) for Web Devs25 min read

Every web developer has experienced the frustration of asking an AI coding assistant to debug an issue, only to realize the model is operating completely blind. Large Language Models understand code syntax brilliantly, yet they have zero direct awareness of your local MySQL staging tables, your live Apache configuration, your private REST endpoints, or your Git branch status. Until recently, bridging that gap meant manually copying terminal outputs, database dumps, and API payloads into your prompt window over and over again.

The Model Context Protocol (MCP) changes this paradigm entirely. Open-sourced by Anthropic and rapidly adopted across modern developer tooling, MCP serves as an open, standardized bridge between AI clients and external systems. Think of it as a universal “USB-C port” for AI models: write an MCP server once for your database, API, or project repository, and any MCP-compatible AI assistant can immediately discover resources, inspect state, and execute commands safely. In this tutorial, we will explore the core architecture of MCP and build a complete, production-ready TypeScript MCP server tailored specifically for everyday web development tasks.

Tutorial Overview: Learning Goals and Prerequisites

Before diving into implementation, let us review what you will accomplish in this guide. We will demystify the protocol, walk through its message formats, construct a working server from scratch, and connect it directly to an AI client interface.

• Understand the Tripartite Architecture: Master how MCP hosts, clients, and servers communicate through bidirectional JSON-RPC transports.
• Implement the Core Primitives: Learn how to expose read-only data with Resources, execute dynamic server actions with Tools, and supply reusable workflows with Prompts.
• Build a Functional Web Dev MCP Server: Write a modular Node.js/TypeScript server that allows an AI model to ping HTTP endpoints, inspect response headers, and validate JSON payloads.
• Connect to AI Clients: Configure your server inside tools like Claude Desktop and modern AI-powered IDEs with proper environment boundaries.
• Debug and Test with MCP Inspector: Use visual diagnostic tools to inspect JSON-RPC messages and catch runtime transport errors quickly.

To follow along comfortably with this guide, you should have the following tools and foundations ready on your development machine:

• Node.js Environment: Node.js version 18.0 or higher installed, along with npm or pnpm.
• JavaScript/TypeScript Basics: A working understanding of asynchronous JavaScript, Promises, and modern ES module syntax.
• Command Line Familiarity: Comfort with running shell commands in bash, zsh, or PowerShell.
• An MCP Client: Claude Desktop or an MCP-enabled developer tool like Cursor, Antigravity, or Cline installed locally.

What Is Model Context Protocol (MCP) and Why Web Developers Need It

Modern web engineering is inherently distributed. A typical daily workflow does not involve code alone; it involves orchestrating a diverse ecosystem of tools. You write PHP or JavaScript, query local SQLite or MySQL databases, trigger Webpack or Vite build scripts, test REST endpoints via Postman or curl, and inspect Docker container logs. Traditional AI chat windows isolate the model from this reality, forcing you into the role of a manual copy-paste proxy.

Without an open protocol, connecting an AI model to these disparate tools causes what engineers call the “M times N integration dilemma.” If there are 10 different AI developer applications and 50 different developer services (GitHub, GitLab, PostgreSQL, Redis, WordPress REST APIs, AWS S3), building proprietary connectors requires 500 individual integration plugins. Each proprietary plugin breaks whenever an API changes, creating fragile maintenance bottlenecks.

Model Context Protocol resolves this complexity by establishing an open, bidirectional standard built on JSON-RPC 2.0. By decoupling the AI client from the data source, MCP establishes an ecosystem where each data provider maintains a single MCP server. Once an MCP server is published, every compatible AI agent can instantly discover its capabilities, read its documentation, and invoke its operations seamlessly.

For web developers, the practical benefits are immediate. Instead of writing custom scripts to format database tables or describe your API routing patterns to an AI model, you can run a local MCP server. When you ask your AI assistant, “Why did our checkout API return a 500 error on the staging server?”, the agent queries your staging log MCP server directly, pinpoints the stack trace, and suggests the exact code fix in seconds.

The Core Architecture of Model Context Protocol (MCP)

To write effective MCP servers, you must understand how data flows across the system. The protocol relies on three primary actors: the Host, the Client, and the Server. Each actor holds a distinct responsibility in the security and execution pipeline.

• The MCP Host: The top-level software program that the human developer interacts with. Examples include Claude Desktop, an IDE extension, or a terminal agent. The Host controls the UI, owns the user permissions, and coordinates the LLM chat session.
• The MCP Client: A lightweight internal component inside the Host. For every connected server, an individual Client instance maintains a dedicated one-to-one communication session, negotiating capabilities and dispatching user requests.
• The MCP Server: A standalone process running either locally on your machine or remotely on a server. It exposes specific capabilities (such as file system access or database querying) through standardized protocol messages.

Understanding Protocol Transports: stdio vs. SSE

MCP supports two primary transport mechanisms for exchanging JSON-RPC messages between clients and servers:

• Standard Input/Output (stdio): The server runs as a local child process launched by the host. Communication happens entirely through standard input (`process.stdin`) and standard output (`process.stdout`). This is the most common transport for local developer tooling because it requires no open network ports, provides instant startup, and operates with native operating system process isolation.
• Server-Sent Events (SSE) over HTTP: The server runs as an independent web service. Clients open an HTTP POST connection for commands and receive streaming updates via SSE. This transport is ideal for shared enterprise servers, remote cloud deployments, and multi-tenant architectures.

The Three Core MCP Primitives

Every feature you expose from an MCP server maps to one of three foundational building blocks:

• Resources: Passive, read-only data sources. Similar to an HTTP GET request, resources provide contextual information without triggering side effects. Examples include reading the content of a local `.env.example` file, inspecting current Git branch metadata, or fetching database schema definitions.
• Tools: Executable functions designed for the model to take action. Similar to an HTTP POST request, tools take structured arguments, perform computations or I/O operations, and return results. Examples include executing a database query, sending an HTTP request, or creating a new file.
• Prompts: Pre-packaged prompt templates and interactive workflows provided directly by the server. Prompts help users kick off complex, multi-step tasks by prepopulating the AI’s context with domain-specific instructions and relevant resources.

Step-by-Step: Building Your First Web Dev MCP Server

Now that the theoretical groundwork is clear, let us build a practical MCP server tailored for web developers. We will create a server named webdev-toolkit-mcp that provides two essential development capabilities: checking HTTP endpoint health (headers, status code, latency) and validating raw JSON data payloads against schemas.

1. Initializing the Project and Dependencies

Start by creating a clean directory for your project and initializing a Node.js project. We will configure TypeScript to ensure clean builds and strong type safety.

mkdir webdev-toolkit-mcp
cd webdev-toolkit-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install --save-dev typescript @types/node

The command above installs the official `@modelcontextprotocol/sdk` library along with `zod`, which we will use for robust runtime argument validation. Next, initialize your TypeScript configuration file:

npx tsc --init

Open the generated tsconfig.json file and configure it with modern Node.js module resolution settings suitable for ESM modules:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

This configuration instructs TypeScript to output compiled JavaScript files into a dist/ folder while keeping our source files neatly organized under src/.

Next, update your package.json file to declare ES module support and provide build and execution scripts:

{
  "name": "webdev-toolkit-mcp",
  "version": "1.0.0",
  "description": "A practical MCP server providing web development diagnostic tools",
  "type": "module",
  "bin": {
    "webdev-toolkit-mcp": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "start": "node ./dist/index.js",
    "dev": "tsc --watch"
  }
}

Setting "type": "module" ensures our Node.js runtime handles standard import and export syntax natively without external bundlers.

2. Creating the Server Entry Point

Create a new file named src/index.ts. Here, we instantiate the base MCP Server object and define metadata including its name and semantic version.

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  ListResourcesRequestSchema,
  ReadResourceRequestSchema,
  ListToolsRequestSchema,
  CallToolRequestSchema,
  ErrorCode,
  McpError
} from "@modelcontextprotocol/sdk/types.js";
import { z } from "zod";

const server = new Server(
  {
    name: "webdev-toolkit-mcp",
    version: "1.0.0"
  },
  {
    capabilities: {
      resources: {},
      tools: {}
    }
  }
);

In this initialization block, we inform the client that our server supports both resources and tools capabilities. When a client initiates a connection, it negotiates these capabilities during the initial handshake.

3. Exposing a Read-Only Resource

Let us create a resource that exposes local environment tips and server configuration data. When the AI model needs reference guidelines, it can read this resource directly without executing arbitrary scripts.

const SERVER_CONFIG_URI = "config://webdev/environment-guidelines";

server.setRequestHandler(ListResourcesRequestSchema, async () => {
  return {
    resources: [
      {
        uri: SERVER_CONFIG_URI,
        name: "Web Development Guidelines",
        mimeType: "text/plain",
        description: "Standards and port configurations for local web dev environments"
      }
    ]
  };
});

server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
  if (request.params.uri === SERVER_CONFIG_URI) {
    const guidelines = [
      "Standard Local Ports:",
      "- PHP/Apache: http://localhost:8080",
      "- Node.js API: http://localhost:3000",
      "- MySQL: localhost:3306",
      "Rule: Always check HTTP response headers for Content-Type and CORS headers before debugging payloads."
    ].join("\n");

    return {
      contents: [
        {
          uri: SERVER_CONFIG_URI,
          mimeType: "text/plain",
          text: guidelines
        }
      ]
    };
  }

  throw new McpError(ErrorCode.InvalidRequest, `Unknown resource URI: ${request.params.uri}`);
});

The code above registers two handlers: ListResourcesRequestSchema advertises our available resources to the AI client, and ReadResourceRequestSchema resolves the resource URI into concrete text content when requested.

4. Implementing Executable Diagnostic Tools

Now let us implement two dynamic tools. The first tool, inspect_http_endpoint, performs an HTTP request to any local or remote URL, calculates latency, and extracts response headers. The second tool, validate_json_payload, tests whether a JSON string conforms to expected keys.

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "inspect_http_endpoint",
        description: "Inspects an HTTP URL and returns response status, latency, and key headers.",
        inputSchema: {
          type: "object",
          properties: {
            url: {
              type: "string",
              description: "The full URL to check (e.g., http://localhost:8080/api/health or https://example.com)"
            },
            method: {
              type: "string",
              enum: ["GET", "HEAD", "POST"],
              description: "HTTP method to use for the check. Defaults to GET."
            }
          },
          required: ["url"]
        }
      },
      {
        name: "validate_json_payload",
        description: "Validates if a given string is valid JSON and checks for mandatory top-level keys.",
        inputSchema: {
          type: "object",
          properties: {
            jsonString: {
              type: "string",
              description: "The raw JSON string to validate"
            },
            requiredKeys: {
              type: "array",
              items: { type: "string" },
              description: "List of required top-level property names"
            }
          },
          required: ["jsonString"]
        }
      }
    ]
  };
});

The inputSchema uses standard JSON Schema syntax. This tells the LLM exactly what parameters are required and how to structure them before calling the tool. Now, add the execution handler for these tools:

const InspectUrlSchema = z.object({
  url: z.string().url(),
  method: z.enum(["GET", "HEAD", "POST"]).optional().default("GET")
});

const ValidateJsonSchema = z.object({
  jsonString: z.string(),
  requiredKeys: z.array(z.string()).optional().default([])
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "inspect_http_endpoint") {
    const parsed = InspectUrlSchema.safeParse(args);
    if (!parsed.success) {
      throw new McpError(ErrorCode.InvalidParams, `Invalid arguments: ${parsed.error.message}`);
    }

    const { url, method } = parsed.data;
    const startTime = performance.now();

    try {
      const response = await fetch(url, {
        method,
        signal: AbortSignal.timeout(5000)
      });
      const durationMs = Math.round(performance.now() - startTime);

      const headerMap: Record = {};
      response.headers.forEach((val, key) => {
        headerMap[key] = val;
      });

      const outputData = {
        url,
        status: response.status,
        statusText: response.statusText,
        latencyMs: durationMs,
        headers: {
          "content-type": headerMap["content-type"] || "unknown",
          "content-length": headerMap["content-length"] || "unknown",
          "server": headerMap["server"] || "unknown",
          "access-control-allow-origin": headerMap["access-control-allow-origin"] || "none"
        }
      };

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(outputData, null, 2)
          }
        ]
      };
    } catch (err: any) {
      return {
        isError: true,
        content: [
          {
            type: "text",
            text: `Connection failed: ${err.message}`
          }
        ]
      };
    }
  }

  if (name === "validate_json_payload") {
    const parsed = ValidateJsonSchema.safeParse(args);
    if (!parsed.success) {
      throw new McpError(ErrorCode.InvalidParams, `Invalid arguments: ${parsed.error.message}`);
    }

    const { jsonString, requiredKeys } = parsed.data;

    try {
      const parsedObject = JSON.parse(jsonString);
      const isPlainObject = typeof parsedObject === "object" && parsedObject !== null && !Array.isArray(parsedObject);

      const missingKeys: string[] = [];
      if (isPlainObject && requiredKeys.length > 0) {
        for (const key of requiredKeys) {
          if (!(key in parsedObject)) {
            missingKeys.push(key);
          }
        }
      }

      const result = {
        isValidJson: true,
        isObject: isPlainObject,
        missingKeys,
        passedValidation: missingKeys.length === 0
      };

      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(result, null, 2)
          }
        ]
      };
    } catch (err: any) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify({
              isValidJson: false,
              parseError: err.message,
              passedValidation: false
            }, null, 2)
          }
        ]
      };
    }
  }

  throw new McpError(ErrorCode.MethodNotFound, `Tool not found: ${name}`);
});

Notice how errors are handled. Rather than crashing the server process on a failed network request, we catch the exception and return a structured response containing isError: true. This enables the AI model to reason about the failure (for example, recognizing that a local server is offline) and provide actionable suggestions to the developer.

5. Connecting the Stdio Transport

Finally, we launch the server by attaching it to the standard input/output transport at the bottom of src/index.ts:

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("WebDev Toolkit MCP Server running on stdio transport");
}

main().catch((error) => {
  console.error("Fatal server error:", error);
  process.exit(1);
});

There is a critical rule to remember when building stdio-based MCP servers: never use console.log() for debugging. Because stdio transport uses standard output strictly for transmitting JSON-RPC protocol packets, writing raw text to stdout with console.log() will corrupt the JSON-RPC message stream and cause client disconnection. Always use console.error() for logging, which routes safely to stderr.

Compile your TypeScript code into JavaScript using the build command:

npm run build

Your compiled server is now ready in dist/index.js.

Configuring AI Clients to Connect to Your MCP Server

Once your server is compiled, you must register it with your AI client. Let us look at how to configure Claude Desktop, one of the most widely used MCP hosts.

Open the Claude Desktop configuration file in your preferred text editor. Its default location depends on your operating system:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add your newly created server inside the mcpServers object:

{
  "mcpServers": {
    "webdev-toolkit": {
      "command": "node",
      "args": [
        "D:/server/www/pm/webdev-toolkit-mcp/dist/index.js"
      ]
    }
  }
}

Make sure to replace the path in the args array with the absolute path to your compiled dist/index.js file. On Windows, use forward slashes (/) or escaped backslashes (\\) to avoid JSON string escaping issues.

Restart Claude Desktop. When the application opens, look for the hammer icon in the chat interface. You should see webdev-toolkit listed with your two custom tools: inspect_http_endpoint and validate_json_payload.

Now, test your server by asking the AI a natural question in the chat prompt:

“Can you check if my local development API at http://localhost:8080/api/users is reachable, and inspect its response headers?”

Claude will recognize that the question requires an external tool, call your local MCP server with the specified URL, receive the JSON-RPC response, and synthesize a clear diagnosis right in your conversation window.

Debugging and Testing MCP Servers Like a Pro

Diagnosing bugs in an MCP server while it is running inside an AI host can be cumbersome. If your server crashes or returns an invalid schema, the client may simply display a generic connection error. To streamline development, Anthropic provides an open-source visual debugging tool called MCP Inspector.

You can launch the MCP Inspector without installing it globally by using npx:

npx @modelcontextprotocol/inspector node dist/index.js

This command starts a local web server (usually at http://localhost:5173) and automatically launches your browser. The Inspector GUI allows you to:

• Inspect Discovered Capabilities: View all registered resources, tools, and prompts along with their exact JSON Schema definitions.
• Execute Tools Interactively: Enter form parameters directly in the browser and click “Run Tool” to test edge cases without typing prompts in an LLM.
• Monitor Raw JSON-RPC Frames: Watch every request and response frame in real time, making it trivial to catch schema validation mismatches and syntax bugs.
• View Stderr Output: Inspect real-time console.error() logs without disturbing the stdio communication channel.

Common MCP Pitfalls and Quick Fixes

• Accidental stdout Pollution: Calling console.log() inside any tool handler instantly corrupts the JSON-RPC transport. Always use console.error() for debugging output.
• Relative File Path Failures: When launching an MCP server via a host configuration, the working directory (cwd) may not be your project root. Always use absolute paths or resolve them with import.meta.url and path.resolve().
• Missing Node.js in System Path: If your client fails to spawn the server process, ensure the full path to your Node.js binary is specified in the configuration, especially when using version managers like nvm.
• Timeout on Blocking Tasks: If a tool takes longer than the host’s configured timeout (typically 30–60 seconds), the client will abort the call. For long operations, provide progress notifications or return early with status tokens.

Real-World Web Development Use Cases for MCP

While our example server provides fundamental HTTP diagnostics, the true power of Model Context Protocol emerges when you integrate it into specific web development stacks.

1. WordPress and CMS Headless Management

Building custom plugins or migrating content across WordPress sites often involves tedious database inspection. By creating an MCP server that communicates with the WordPress REST API or WP-CLI, you can empower an AI assistant to:

• Audit Draft Posts: List unpublished articles, verify SEO metadata completeness, and identify missing featured image tags automatically.
• Inspect Plugin Conflicts: Query active plugins, detect version mismatches, and check for known compatibility notices.
• Manage Custom Taxonomies: Reassign categories and tags across hundreds of posts using simple conversational requests.

2. Local Database and ORM Assistance

Instead of copying SQL schemas into your chat window, you can run an MCP server connected to your local development database (MySQL, PostgreSQL, or SQLite). With read-only permissions configured, your AI assistant can inspect table definitions, evaluate foreign key relationships, and write accurate Laravel Eloquent or CodeIgniter 4 query builders that match your exact schema.

3. Automated Web Performance and Lighthouse Auditing

You can build an MCP server that executes Google Lighthouse or fetches Web Vitals metrics for your local staging URLs. When you ask your assistant, “How can I improve the Largest Contentful Paint (LCP) on our product card page?”, the assistant triggers a Lighthouse run via MCP, reads the diagnostic opportunities, and generates targeted CSS and JavaScript optimizations.

Security Best Practices for Agentic Web Tooling

Granting an AI model the ability to execute tools on your local machine or staging environment requires thoughtful security boundaries. Because LLMs can be vulnerable to prompt injection attacks from untrusted external content, you must design your MCP servers defensively.

• Apply the Principle of Least Privilege: By default, make resources read-only. For tools that perform state-changing operations (such as deleting database rows or deploying code), configure your MCP host to require explicit human confirmation before execution.
• Strict Input Validation with Zod: Never trust input arguments supplied by the model. Always sanitize and validate every parameter using strict schema validators like Zod to prevent command injection and path traversal exploits.
• Protect Secret Keys and Credentials: Never hardcode API keys, database credentials, or auth tokens inside client configuration files. Store secrets in environment variables or a local `.env` file that is excluded from version control.
• Sandbox Dangerous File System Operations: If your MCP server reads or writes local files, constrain file access to a specific project directory using path.resolve() and verify that resolved paths never escape the intended boundary.

Practical Hands-On Exercises: Test Your Skills

The best way to solidify your understanding of Model Context Protocol is to build additional tools into your server. Here are two practical exercises you can complete right now:

Exercise 1: Create a CSS Color Palette Extractor Tool

Extend your webdev-toolkit-mcp server with a new tool named extract_css_palette. This tool should accept a string of CSS code and return an array of all unique hex, RGB, and HSL color values found in the stylesheet.

• Input Schema: An object with a single required property cssContent of type string.
• Implementation Tip: Use regular expressions to match patterns like #[0-9a-fA-F]{3,6} and rgba?\([^)]+\), deduplicate them using a JavaScript Set, and return the unique list.
• Test Prompt: Paste a small CSS snippet into your AI client and ask: “What colors are used in this stylesheet?”

Exercise 2: Implement a Git Branch Status Resource

Add a dynamic MCP Resource that executes git status --porcelain in your current project folder and exposes the list of modified, untracked, and deleted files as a readable resource.

• URI Pattern: Use a descriptive URI format such as git://workspace/status.
• Implementation Tip: Use Node.js child_process.execFile to call Git safely, catch potential errors if Git is not installed, and return the plain text output under contents.
• Test Prompt: Ask your AI client: “What files have I changed in my working branch?”

Frequently Asked Questions

What is the difference between MCP and standard REST APIs?

REST APIs are designed for direct application-to-application communication with predefined endpoints and custom authentication schemes. In contrast, Model Context Protocol provides a standardized discovery and negotiation layer tailored specifically for LLMs. It enables models to dynamically explore available tools, inspect input schemas, and receive structured tool results without requiring custom client code for every individual service.

Can I build an MCP server in PHP or Python instead of TypeScript?

Yes, absolutely. While the official TypeScript SDK is popular among web developers, Anthropic also maintains an official Python SDK (`mcp`). Furthermore, because MCP is based on standard JSON-RPC 2.0 over standard I/O or SSE, community SDKs are available for PHP, Go, Rust, and C#. You can write an MCP server in modern PHP using Composer to expose your CodeIgniter or Laravel application services directly.

How does MCP handle authentication and sensitive API keys?

For local stdio servers, authentication is inherited from the local operating system process permissions and environment variables passed in the client configuration file. For remote servers operating over Server-Sent Events (SSE), standard HTTP authorization headers (such as Bearer tokens or OAuth 2.0) are utilized to authenticate and isolate client sessions.

Is Model Context Protocol restricted to Anthropic Claude?

No, MCP is completely open-source and model-agnostic. While Anthropic created and popularized the specification, any AI application or model provider can implement an MCP client. Leading developer tools including Cursor, Continue.dev, Zed, Antigravity, and open-source agent frameworks have already adopted MCP to connect their models to developer ecosystems.

What happens if an MCP tool throws an unhandled error during execution?

If an unhandled exception terminates the server process, the stdio pipe closes and the host reports a disconnection error. To prevent this, tool handlers should always wrap asynchronous logic in try-catch blocks and return an MCP response with isError: true. This preserves the communication channel and allows the AI model to inform the user of the error gracefully.

Conclusion and Next Steps

The transition from isolated text chatbots to fully integrated, agentic AI assistants represents the biggest leap in developer productivity since the invention of the modern IDE. By mastering Model Context Protocol (MCP), you are no longer limited to copy-pasting code into a chat window. You can give your AI assistant safe, standardized, real-time access to your databases, local test suites, build tools, and staging servers.

Your journey with MCP has just begun. To take your skills to the next level, try implementing the exercises outlined above, or explore the growing ecosystem of open-source MCP servers for PostgreSQL, GitHub, and Docker. By writing custom MCP tooling tailored to your team’s stack, you transform artificial intelligence from a passive conversational partner into an indispensable engineering teammate.