Model Context Protocol (MCP) Explained: Architecture, Code and Security

Before MCP, every AI application that wanted to read your GitHub issues, query your database or search your docs needed its own custom integration for each system. With M applications and N tools, that is M×N pieces of glue code, each with its own auth, schema and bugs. The Model Context Protocol turns that into M+N: tools implement the protocol once as servers, applications implement it once as clients, and everything interoperates. This guide explains how it works at the level you need to build, debug and secure a real server.

MCP is evolving quickly; the specification is versioned by date and new revisions add capabilities every few months. The concepts here are stable, but check modelcontextprotocol.io for the current specification and SDK versions before you ship.

Why MCP Exists: The M×N Integration Problem

Large language models are only as useful as the context and actions you give them. Function calling, covered in our AI agents guide, solved the model side: a model can emit a structured request like get_weather(city="Pune"). It did not solve the integration side: where do the tool definitions come from, who runs the code, how does a different application reuse the same tool, and how does the user control what is connected?

MCP borrows the idea of the Language Server Protocol. LSP let any editor talk to any language's tooling through one protocol. MCP lets any AI host talk to any tool or data source. The practical consequences:

• A company writes one MCP server for its internal ticketing system, and engineers can use it from their AI coding agent, their chat assistant and their IDE.
• Users can plug in tools without the app developer shipping new code.
• Capabilities are discovered at runtime: the host asks each server what it offers.

The ecosystem now includes SDKs for many languages, support in major AI assistants, IDEs and coding agents, and a large number of open-source servers for common systems such as Git hosting, databases, browsers, file systems and SaaS APIs. Governance of the protocol has also moved toward a vendor-neutral foundation, which has encouraged broad adoption.

MCP Architecture: Hosts, Clients and Servers

Three roles, which are easy to confuse:

• Host: the AI application the user interacts with, such as a desktop assistant, an IDE or a terminal coding agent. It owns the model, the conversation and the user's consent decisions.
• Client: a connector inside the host. The host creates one client per server connection, and each client maintains a stateful session with exactly one server.
• Server: a program that exposes capabilities (tools, resources, prompts) for one domain: your database, your file system, your Jira.

An important consequence of this design: the server never talks to the model directly. The host decides which tool definitions to show the model, executes the model's tool calls through the right client, and decides what to put back into context. That is where consent and policy live.

The session lifecycle

1. Initialize. The client sends initialize with the protocol version it speaks, its capabilities and its name. The server replies with its chosen version, its capabilities (for example, "I offer tools and resources, and I will notify you when the tool list changes") and its name.
2. Initialized. The client sends an notifications/initialized notification. Normal operation begins.
3. Discovery. The client calls tools/list, resources/list and prompts/list.
4. Operation. The host calls tools/call, resources/read or prompts/get as the conversation requires. Servers can send notifications such as notifications/tools/list_changed.
5. Shutdown. For stdio, the client closes the server's input and the process exits; for HTTP, the session is terminated or expires.

Tools vs Resources vs Prompts

The single most useful thing to understand about MCP is who controls each primitive. That determines which one you should use.

Rules of thumb: if it does something or needs model judgement about when to fetch it, make it a tool. If it is reference material a user might attach ("include our DB schema"), make it a resource. If it is a workflow the user kicks off deliberately, make it a prompt.

Client-side features

Servers can also ask the client for things, if the client advertises support:

• Sampling: the server asks the host's model to generate a completion, so a server can use an LLM without its own API key, under the host's control.
• Roots: the client tells the server which directories or URIs it is allowed to operate within.
• Elicitation: the server asks the user for additional structured input mid-operation, for example to confirm a choice.

What MCP Looks Like on the Wire

Every message is JSON-RPC 2.0: requests with an id, responses with the matching id, and notifications without one. Here is a tool call from client to server and the response.

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "find_orders",
    "arguments": { "customer_email": "asha@example.com", "limit": 2 }
  }
}

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      { "type": "text", "text": "[{\"id\": 1042, \"status\": \"DELIVERED\", \"amount_paise\": 129900}]" }
    ],
    "structuredContent": {
      "result": [ { "id": 1042, "status": "DELIVERED", "amount_paise": 129900 } ]
    },
    "isError": false
  }
}

Two details matter. First, tool results carry a content array (text, images, audio, links to resources or embedded resources) and, in recent revisions, optional structuredContent that conforms to a declared output schema. Second, a tool that fails in a business sense ("customer not found") should return a normal result with isError: true and a helpful message, so the model can recover. JSON-RPC errors are for protocol problems such as an unknown tool or invalid arguments.

Build Your First MCP Server in Python

We will build a small but realistic server: read-only access to an orders database for a support assistant. It exposes one tool, one resource and one prompt. Install the official SDK with pip install "mcp[cli]" (or uv add "mcp[cli]").

import sqlite3

conn = sqlite3.connect("orders.db")
conn.executescript("""
CREATE TABLE IF NOT EXISTS orders (
  id INTEGER PRIMARY KEY,
  customer_email TEXT NOT NULL,
  status TEXT NOT NULL,
  amount_paise INTEGER NOT NULL,
  created_at TEXT NOT NULL
);
DELETE FROM orders;
INSERT INTO orders VALUES
 (1041, 'asha@example.com', 'REFUNDED',  49900, '2026-09-28'),
 (1042, 'asha@example.com', 'DELIVERED', 129900, '2026-10-02'),
 (1043, 'ravi@example.com', 'SHIPPED',   89900, '2026-10-05');
""")
conn.commit()
conn.close()

import sqlite3
import sys
from mcp.server.fastmcp import FastMCP

DB_PATH = "orders.db"
mcp = FastMCP("orders")

def query(sql: str, params: tuple = ()) -> list[dict]:
    # mode=ro opens the database read-only: the server cannot modify data
    conn = sqlite3.connect(f"file:{DB_PATH}?mode=ro", uri=True)
    conn.row_factory = sqlite3.Row
    try:
        return [dict(r) for r in conn.execute(sql, params).fetchall()]
    finally:
        conn.close()

@mcp.tool()
def find_orders(customer_email: str, limit: int = 10) -> list[dict]:
    """Return a customer's most recent orders (newest first).

    Use this when a support agent asks about a specific customer's orders.
    Amounts are in paise (1 rupee = 100 paise).
    """
    limit = max(1, min(limit, 50))          # never trust model-supplied limits
    print(f"find_orders {customer_email}", file=sys.stderr)  # logs go to stderr
    return query(
        "SELECT id, status, amount_paise, created_at FROM orders "
        "WHERE customer_email = ? ORDER BY created_at DESC LIMIT ?",
        (customer_email, limit),
    )

@mcp.resource("schema://orders")
def orders_schema() -> str:
    """The orders table schema, for context."""
    rows = query("SELECT sql FROM sqlite_master WHERE name = 'orders'")
    return rows[0]["sql"] if rows else "orders table not found"

@mcp.prompt()
def refund_review(order_id: str) -> str:
    """Template for reviewing a refund request."""
    return (f"Review refund eligibility for order {order_id}. "
            "Look up the order, check its status and date, and recommend "
            "approve or reject with a one-paragraph justification.")

if __name__ == "__main__":
    mcp.run()   # stdio transport by default

What the SDK does for you: the type hints become the tool's JSON input schema, the docstring becomes the description the model reads, and the return type is serialised into the result (recent SDK versions also emit structuredContent for typed returns). Note three deliberate choices:

• Read-only connection (mode=ro) and parameterised SQL. The model never constructs SQL, so there is nothing to inject.
• Clamped arguments. Model-supplied values are untrusted input, exactly like HTTP request parameters.
• Logs on stderr. With stdio transport, stdout carries the protocol. A stray print() to stdout corrupts the JSON-RPC stream and is the most common reason a new server "connects then dies".

The Same Server in TypeScript

With the official TypeScript SDK (npm install @modelcontextprotocol/sdk zod), the structure is the same. This uses the v1.x SDK API; check the SDK README if you are on a newer major version, as package layout may change.

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

type Order = { id: number; status: string; amount_paise: number; created_at: string };

// Stand-in for a real read-only DB query
const ORDERS: Record<string, Order[]> = {
  "asha@example.com": [
    { id: 1042, status: "DELIVERED", amount_paise: 129900, created_at: "2026-10-02" },
    { id: 1041, status: "REFUNDED", amount_paise: 49900, created_at: "2026-09-28" },
  ],
};

const server = new McpServer({ name: "orders", version: "1.0.0" });

server.registerTool(
  "find_orders",
  {
    title: "Find orders",
    description: "Return a customer's most recent orders, newest first. Amounts are in paise.",
    inputSchema: {
      customer_email: z.string().email(),
      limit: z.number().int().min(1).max(50).default(10),
    },
  },
  async ({ customer_email, limit }) => {
    const rows = (ORDERS[customer_email] ?? []).slice(0, limit);
    if (rows.length === 0) {
      return { content: [{ type: "text", text: `No orders for ${customer_email}` }], isError: true };
    }
    return { content: [{ type: "text", text: JSON.stringify(rows) }] };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);
console.error("orders MCP server running on stdio");   // stderr, not stdout

Connect and Test Your Server

Test with the MCP Inspector first

The official MCP Inspector is a small web UI that connects to your server, lists its tools, resources and prompts, and lets you call them by hand. Run npx @modelcontextprotocol/inspector python server.py, or with the Python SDK's CLI, mcp dev server.py. Always test here before connecting a model, because it separates "my server is broken" from "the model did not call my tool".

Connect it to a host

Most hosts use a JSON config naming a command to launch. A typical desktop-assistant style configuration:

{
  "mcpServers": {
    "orders": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Terminal coding agents usually provide a command for this; for example, Claude Code supports claude mcp add orders -- python /absolute/path/to/server.py. Editors such as VS Code and Cursor read similar JSON files in the project or user settings. Use absolute paths: hosts often launch servers from a different working directory, which is the second most common cause of "server failed to start". If the database path is relative, as in our example, launch the server from its own directory or make the path absolute.

Debugging checklist

• Server exits immediately: run the command yourself in a terminal and read the traceback.
• Connects but tools missing: check the host's MCP logs; confirm your server declared the tools capability (the SDKs do this automatically).
• Model never calls the tool: improve the description. Say when to use it, not just what it does.
• Garbled protocol errors: something is writing to stdout.

Remote MCP Servers: Streamable HTTP and OAuth

Local stdio servers run on the user's machine with the user's privileges. For shared, multi-user integrations (a company's internal knowledge base, a SaaS product's API), you deploy a remote server using the Streamable HTTP transport. The client POSTs JSON-RPC messages to a single endpoint; the server replies with JSON or opens a server-sent events stream for long-running responses and notifications; a session ID header ties requests together. In the Python SDK this is mcp.run(transport="streamable-http").

Authorization for remote servers is based on OAuth 2.1. The MCP server acts as an OAuth resource server: it publishes metadata pointing to an authorization server, the client obtains an access token for that specific server (audience-bound), and the server validates the token on every request. If OAuth is new to you, our OAuth 2.0 and JWT guide covers the flows. Two rules from the specification's security guidance are worth memorising:

• No token passthrough. A server must not accept a token issued for some other service and forward it to a downstream API. Each hop validates tokens meant for it.
• Validate the Origin header and bind local servers to localhost. Otherwise a malicious web page can use DNS rebinding to reach a server running on a developer's laptop.

MCP Security: The Threats That Actually Matter

MCP does not create new classes of vulnerability so much as concentrate existing ones. Everything a server returns, and every tool description, becomes text in the model's context. That makes the security model essentially the prompt injection problem plus classic supply-chain and authorization issues. Read prompt injection and LLM security alongside this section.

A security checklist for server authors

1. Least privilege. Read-only by default. Separate read and write tools so hosts can approve them differently.
2. Validate every argument as if it came from an attacker: types, ranges, path traversal, allowed values.
3. Never build queries or shell commands by string concatenation from tool arguments.
4. Scope data to the authenticated user in remote servers. The model must not be able to ask for another user's data by changing an argument.
5. Mark destructive tools clearly (the protocol has tool annotations such as read-only and destructive hints, which hosts may use for consent prompts) and require confirmation.
6. Log tool calls with user, arguments and outcome for audit.
7. Return minimal data. Do not dump full records when the task needs three fields; less data in context means less to leak.

Designing Tools Models Use Well

A technically correct server can still be useless if the model picks the wrong tool or passes bad arguments. Tool design is API design for a reader that is smart but literal.

• Few, task-shaped tools beat many thin wrappers. find_orders(customer_email) is better than exposing list_tables, describe_table and run_query separately, which forces multi-step reasoning and opens injection risk.
• Write descriptions for when to use the tool, include units ("amounts in paise"), formats ("dates are ISO 8601") and limits.
• Use enums and constraints in schemas rather than describing allowed values in prose.
• Return compact, readable results: summarise, paginate, and include identifiers the model can use in follow-up calls.
• Make errors actionable: "No customer with that email; try find_customer_by_phone" lets the model recover.
• Watch context cost. Every connected tool's definition consumes context tokens on every request. Dozens of servers with hundreds of tools degrade tool selection; connect what the task needs.

How MCP Comes Up in Interviews

AI engineering and agentic roles, which are growing quickly in India (see the agentic AI engineer career path), increasingly ask about tool integration. Typical questions and what a strong answer includes:

• "How is MCP different from function calling?" Function calling is the model-level mechanism; MCP standardises discovery, invocation and transport between apps and tool providers. Hosts translate MCP tools into function definitions for the model.
• "When would you not use MCP?" A single app with a few internal tools: plain function calling is simpler. MCP pays off with multiple hosts, user-pluggable tools or separate ownership.
• "Design an internal MCP server for a company's HR and ticketing systems." Remote Streamable HTTP server, OAuth with per-user tokens, data scoped to the caller, read and write tools separated, audit logging, rate limits, and a review process for which servers employees may install.
• "What could go wrong if an agent can read email and also call an HTTP fetch tool?" Indirect prompt injection leading to exfiltration; mitigate by removing one leg of the trifecta, requiring approval, or restricting egress.

The best way to prepare is to build one. Wrap something you use daily (your notes, a Postgres database, a public API such as an Indian railway or weather service you have legitimate access to), test it in the Inspector, connect it to a host, then try to break it with an injected instruction in the data it returns. You will learn more about agent security from that afternoon than from any article, including this one.

Frequently Asked Questions

Pranjal Jain

Ex-Microsoft SDE · IIT Kanpur · Founder of Prepflix. Helps engineers crack startup and product company interviews across India.