Model Context Protocol (MCP) Guide

npm install @modelcontextprotocol/sdk

pip install mcp

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

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

server.tool("greet", { name: z.string() }, async ({ name }) => ({
  content: [{ type: "text", text: `Hello, ${name}!` }],
}));

const transport = new StdioServerTransport();
await server.connect(transport);

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello-world")

@mcp.tool()
def greet(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}!"

if __name__ == "__main__":
    mcp.run()

server.tool(
  "read_file",
  "Read the contents of a file from disk",
  {
    path: z.string().describe("Absolute path to the file"),
  },
  async ({ path }) => {
    const content = await fs.readFile(path, "utf-8");
    return {
      content: [{ type: "text", text: content }],
    };
  }
);

// Static resource
server.resource("config://app", "Application config", async () => ({
  contents: [{ uri: "config://app", text: JSON.stringify(config) }],
}));

// Dynamic resource via URI template
server.resource(
  "file://{path}",
  "Read any file",
  async (uri) => {
    const path = uri.pathname;
    const text = await fs.readFile(path, "utf-8");
    return { contents: [{ uri: uri.href, text }] };
  }
);

server.prompt(
  "summarize",
  "Summarize a given text",
  { text: z.string() },
  ({ text }) => ({
    messages: [
      {
        role: "user",
        content: { type: "text", text: `Please summarize:\n\n${text}` },
      },
    ],
  })
);

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "node",
  args: ["my-server.js"],
});

const client = new Client({ name: "my-client", version: "1.0.0" });
await client.connect(transport);

// List available tools
const { tools } = await client.listTools();

// Call a tool
const result = await client.callTool({
  name: "greet",
  arguments: { name: "World" },
});

console.log(result.content[0].text); // "Hello, World!"

const transport = new StdioServerTransport();

import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";

app.get("/sse", (req, res) => {
  const transport = new SSEServerTransport("/message", res);
  server.connect(transport);
});

return {
  content: [
    { type: "text", text: "Here is the result:" },
    { type: "image", data: base64String, mimeType: "image/png" },
    { type: "resource", resource: { uri: "file:///output.csv", text: csvData } },
  ],
};

try {
  const result = await riskyOperation();
  return { content: [{ type: "text", text: result }] };
} catch (err) {
  return {
    isError: true,
    content: [{ type: "text", text: `Error: ${err.message}` }],
  };
}

// Good: read from environment
const apiKey = process.env.MY_API_KEY;
if (!apiKey) throw new Error("MY_API_KEY is not set");

npx @modelcontextprotocol/inspector node my-server.js

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({ name: "my-server", version: "1.0.0" });
// All stderr output is safe — it won't corrupt the stdio transport
console.error("[debug] Server started");

import logging
logging.basicConfig(level=logging.DEBUG)

import { describe, it, expect } from "vitest";
import { greetUser } from "./tools/greet.js";

describe("greetUser", () => {
  it("returns a greeting", async () => {
    const result = await greetUser({ name: "Alice" });
    expect(result.content[0].text).toBe("Hello, Alice!");
  });
});

from mcp.server.fastmcp import FastMCP
from pathlib import Path

mcp = FastMCP("filesystem")
ROOT = Path("/home/user/documents")

@mcp.resource("file://{filename}")
def read_file(filename: str) -> str:
    """Read a file from the documents folder."""
    return (ROOT / filename).read_text()

@mcp.tool()
def write_file(filename: str, content: str) -> str:
    """Write content to a file in the documents folder."""
    (ROOT / filename).write_text(content)
    return f"Written {len(content)} bytes to {filename}"

server.tool(
  "search_products",
  "Search the product catalog",
  { query: z.string(), limit: z.number().default(10) },
  async ({ query, limit }) => {
    const res = await fetch(
      `https://api.example.com/products?q=${encodeURIComponent(query)}&limit=${limit}`,
      { headers: { Authorization: `Bearer ${process.env.API_KEY}` } }
    );
    const data = await res.json();
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
    };
  }
);

import sqlite3
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("sqlite-server")
DB_PATH = "data.db"

@mcp.tool()
def run_query(sql: str) -> str:
    """Run a read-only SQL query against the database."""
    if not sql.strip().upper().startswith("SELECT"):
        raise ValueError("Only SELECT queries are allowed")
    conn = sqlite3.connect(DB_PATH)
    cursor = conn.execute(sql)
    rows = cursor.fetchall()
    cols = [d[0] for d in cursor.description]
    conn.close()
    return "\n".join([",".join(cols)] + [",".join(map(str, r)) for r in rows])