Understanding MCP (Model Context Protocol)

MCP, or Model Context Protocol, is a system designed to let AI assistants interact with your local machine or server in a safe, structured, and programmable way. Think of it as an API for AI models — but instead of humans calling the API, the AI does.

Core Concepts of MCP

Every MCP server has three main components:

Tools

Tools are actions that the AI can perform. They are like functions exposed to the AI.

Example:

nmap-basic-scan → The AI can scan a network host using Nmap.

mcpServer.registerTool(
  "nmap-basic-scan",
  {
    description: "Run a basic and safe Nmap scan (-sV) on a target.",
    inputSchema: {target: z.string()},
  },
  async ({target}) => {
    /* executes Nmap */
  }
);

Resources

Resources are static or dynamic data that the AI can read. They are like files, guides, or documentation available to the AI.

Example:

nmap-guide → The AI can read a Nmap usage guide.

mcpServer.registerResource(
  "nmap-guide",
  "resource://nmap-guide",
  {mimeType: "text/plain"},
  async () => {
    return {
      contents: [
        {
          uri: "resource://nmap-guide",
          text: "Nmap usage guide...",
          mimeType: "text/plain",
        },
      ],
    };
  }
);

Prompts

Prompts are templates that the AI can use to generate responses. They are like pre-written instructions or message patterns.

Example:

nmap-help → The AI can give usage help for Nmap.

mcpServer.registerPrompt(
  "nmap-help",
  {
    title: "Nmap Help",
    description: "Provides usage help for the Nmap scan tool.",
    argsSchema: {},
  },
  async (): Promise<GetPromptResult> => {
    return {
      messages: [
        {
          role: "assistant",
          content: {type: "text", text: "Nmap MCP Usage: {target}"},
        },
      ],
    };
  }
);

How MCP Works

• You start an MCP server on your machine.

• The AI connects to your MCP server over a transport layer (STDIO, SSE, WebSocket, etc.).

• The AI can then:

  • Call tools to execute commands.
  • Read resources for contextual information.
  • Use prompts to generate structured responses.

MCP ensures that AI actions are typed, validated, and safe.

Example: Nmap MCP Server in TypeScript

Here’s a simple MCP server that exposes:

• Tool: nmap-basic-scan → Run Nmap scans.
• Resource: nmap-guide → Provides a Nmap usage guide.
• Prompt: nmap-help → Gives instructions for using the Nmap tool.

import {McpServer} from "@modelcontextprotocol/sdk/server/mcp.js";
import {StdioServerTransport} from "@modelcontextprotocol/sdk/server/stdio.js";
import {GetPromptResult} from "@modelcontextprotocol/sdk/types.js";
import * as z from "zod/v4";
import {exec} from "child_process";
import util from "util";

const execAsync = util.promisify(exec);

const mcpServer = new McpServer({name: "nmap-mcp", version: "1.0.0"});

// Resource: Nmap guide
mcpServer.registerResource(
  "nmap-guide",
  "resource://nmap-guide",
  {mimeType: "text/plain"},
  async () => ({
    contents: [
      {
        uri: "resource://nmap-guide",
        text: "Nmap usage guide content...",
        mimeType: "text/plain",
      },
    ],
  })
);

// Prompt: Nmap help
mcpServer.registerPrompt(
  "nmap-help",
  {
    title: "Nmap Help",
    description: "Usage instructions for Nmap",
    argsSchema: {},
  },
  async (): Promise<GetPromptResult> => ({
    messages: [
      {
        role: "assistant",
        content: {type: "text", text: "Use nmap-basic-scan with {target}"},
      },
    ],
  })
);

// Tool: Nmap basic scan
mcpServer.registerTool(
  "nmap-basic-scan",
  {
    description: "Run a basic and safe Nmap scan (-sV) on a target.",
    inputSchema: {target: z.string()},
  },
  async ({target}) => {
    try {
      const {stdout} = await execAsync(`nmap ${target}`);
      return {content: [{type: "text", text: stdout}]};
    } catch (err: any) {
      return {content: [{type: "text", text: err.message}]};
    }
  }
);

// Start MCP server
async function main() {
  const transport = new StdioServerTransport();
  await mcpServer.connect(transport);
  console.log("MCP server running...");
}

main();

Summary

• MCP = Tools + Resources + Prompts.
• It's a plugin-like system for AI, letting it act safely on your environment.
• AI clients can call tools, read resources, and use prompts over a transport.
• MCP is the core infrastructure for extending AI capabilities safely.