MCP (Model Context Protocol): Kompletny Przewodnik dla Programistów

Model Context Protocol (MCP) to otwarty standard stworzony przez Anthropic, który definiuje sposób komunikacji modeli AI z zewnętrznymi narzędziami, źródłami danych i usługami. Pomyśl o nim jako o "USB-C dla AI" - uniwersalnym złączu, które pozwala dowolnemu agentowi AI komunikować się z dowolnym narzędziem przez ustandaryzowany interfejs.

Od momentu uruchomienia MCP przekroczył 97 milionów miesięcznych pobrań SDK i został przyjęty przez wszystkich głównych dostawców AI: Anthropic, OpenAI, Google, Microsoft i Amazon. W tym przewodniku poznamy wszystko, co musisz wiedzieć, aby budować z MCP.

Dlaczego MCP Istnieje

Przed MCP każda aplikacja AI musiała budować niestandardowe integracje dla każdego narzędzia, którego chciała używać. Chcesz, żeby twoja AI czytała pliki? Pisz niestandardowy kod. Odpytywanie bazy danych? Więcej niestandardowego kodu. Publikowanie na Slacku? Kolejna integracja.

To tworzyło problem N×M: N aplikacji AI, z których każda potrzebowała M niestandardowych integracji, co prowadziło do zduplikowanego wysiłku i fragmentacji ekosystemów.

MCP rozwiązuje to za pomocą jednego protokołu, którego dowolny klient AI może użyć do komunikacji z dowolnym serwerem MCP:

Podstawowe Koncepcje

MCP ma trzy fundamentalne prymitywy:

1. Narzędzia (Tools)

Narzędzia to funkcje, które AI może wywoływać. Reprezentują akcje takie jak "utwórz plik", "odpytaj bazę danych" czy "wyślij wiadomość". Każde narzędzie ma nazwę, opis i JSON Schema dla swoich parametrów.

{
  name: "create_issue",
  description: "Create a new GitHub issue",
  inputSchema: {
    type: "object",
    properties: {
      title: { type: "string", description: "Issue title" },
      body: { type: "string", description: "Issue body" },
      repo: { type: "string", description: "Repository name" }
    },
    required: ["title", "repo"]
  }
}

2. Zasoby (Resources)

Zasoby to dane, które AI może czytać. Reprezentują pliki, rekordy bazy danych, odpowiedzi API lub dowolne inne źródło danych. Zasoby są identyfikowane przez URI.

{
  uri: "file:///Users/dev/project/README.md",
  name: "Project README",
  mimeType: "text/markdown"
}

3. Prompty (Prompts)

Prompty to szablony wielokrotnego użytku, które pomagają strukturyzować interakcje. Mogą zawierać dynamiczne parametry i są przydatne do standaryzacji typowych przepływów pracy.

{
  name: "code_review",
  description: "Review code changes for quality and security",
  arguments: [
    { name: "diff", description: "The code diff to review", required: true }
  ]
}

Architektura

MCP stosuje architekturę klient-serwer:

• Host: Aplikacja AI (Claude Desktop, Cursor, twoja niestandardowa aplikacja)
• Klient: Utrzymuje połączenie 1:1 z serwerem MCP
• Serwer: Udostępnia narzędzia, zasoby i prompty klientowi
• Transport: Komunikacja odbywa się przez JSON-RPC 2.0 via stdio (lokalnie) lub Server-Sent Events (zdalnie)

Budowanie Serwera MCP

Zbudujmy praktyczny serwer MCP, który współdziała z listą zadań przechowywaną w pliku JSON.

Konfiguracja Początkowa

mkdir mcp-todo-server && cd mcp-todo-server
npm init -y
npm install @modelcontextprotocol/sdk zod

Implementacja Serwera

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

const TODO_FILE = "./todos.json";

function readTodos(): { id: number; text: string; done: boolean }[] {
  if (!fs.existsSync(TODO_FILE)) return [];
  return JSON.parse(fs.readFileSync(TODO_FILE, "utf-8"));
}

function writeTodos(todos: { id: number; text: string; done: boolean }[]) {
  fs.writeFileSync(TODO_FILE, JSON.stringify(todos, null, 2));
}

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

// Tool: Add a todo
server.tool(
  "add_todo",
  "Add a new todo item",
  { text: z.string().describe("The todo text") },
  async ({ text }) => {
    const todos = readTodos();
    const newTodo = { id: Date.now(), text, done: false };
    todos.push(newTodo);
    writeTodos(todos);
    return { content: [{ type: "text", text: `Added: "${text}"` }] };
  }
);

// Tool: List todos
server.tool(
  "list_todos",
  "List all todo items",
  {},
  async () => {
    const todos = readTodos();
    const list = todos
      .map((t) => `${t.done ? "✅" : "⬜"} [${t.id}] ${t.text}`)
      .join("\n");
    return { content: [{ type: "text", text: list || "No todos yet." }] };
  }
);

// Tool: Complete a todo
server.tool(
  "complete_todo",
  "Mark a todo as completed",
  { id: z.number().describe("The todo ID to complete") },
  async ({ id }) => {
    const todos = readTodos();
    const todo = todos.find((t) => t.id === id);
    if (!todo) return { content: [{ type: "text", text: "Todo not found." }] };
    todo.done = true;
    writeTodos(todos);
    return { content: [{ type: "text", text: `Completed: "${todo.text}"` }] };
  }
);

// Resource: Current todos as a readable resource
server.resource(
  "todos://list",
  "Current todo list",
  async () => ({
    contents: [{
      uri: "todos://list",
      mimeType: "application/json",
      text: JSON.stringify(readTodos(), null, 2),
    }],
  })
);

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

Konfiguracja

Aby używać tego serwera z Claude Desktop, dodaj go do swojej konfiguracji:

{
  "mcpServers": {
    "todo": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-todo-server/src/index.ts"]
    }
  }
}

Budowanie Klienta MCP

Możesz również zbudować niestandardowego klienta, który łączy się z dowolnym serwerem MCP:

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

const transport = new StdioClientTransport({
  command: "npx",
  args: ["tsx", "./src/index.ts"],
});

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

// List available tools
const { tools } = await client.listTools();
console.log("Available tools:", tools.map((t) => t.name));

// Call a tool
const result = await client.callTool({
  name: "add_todo",
  arguments: { text: "Write MCP blog post" },
});
console.log(result);

Popularne Serwery MCP

Ekosystem MCP rozrósł się szybko. Oto niektóre z najpopularniejszych serwerów:

MCP vs A2A (Agent-to-Agent)

Podczas gdy MCP obsługuje komunikację agent-narzędzie, protokół A2A (Agent-to-Agent) Google obsługuje komunikację agent-agent. Są komplementarne:

• MCP: Jak agent AI używa narzędzi (integracja pionowa)
• A2A: Jak agenci AI współpracują ze sobą (integracja pozioma)

Najlepsze Praktyki

1. Utrzymuj serwery skoncentrowane: Jeden serwer na domenę (serwer GitHub, serwer Slack itp.). Nie buduj monolitycznych serwerów.
2. Waliduj dane wejściowe za pomocą Zod: Zawsze waliduj dane wejściowe narzędzi za pomocą odpowiednich schematów.
3. Obsługuj błędy elegancko: Zwracaj znaczące komunikaty o błędach, nie stack trace.
4. Używaj zasobów dla danych tylko do odczytu: Jeśli AI potrzebuje tylko czytać dane, udostępniaj je jako zasób, a nie narzędzie.
5. Dodawaj odpowiednie opisy: Dobre opisy narzędzi i parametrów pomagają AI zrozumieć, kiedy i jak używać każdego narzędzia.
6. Testuj za pomocą MCP Inspector: Użyj npx @modelcontextprotocol/inspector do interaktywnego testowania serwera.

Rozpoczęcie Pracy

# Create a new MCP server from template
npx @modelcontextprotocol/create-server my-server

# Test with the MCP Inspector
npx @modelcontextprotocol/inspector npx tsx ./src/index.ts

Podsumowanie

MCP stał się de facto standardem wykorzystania narzędzi AI w 2026 roku. Niezależnie od tego, czy budujesz niestandardowych agentów AI, rozszerzasz Claude Code, czy tworzysz integracje dla istniejących platform, zrozumienie MCP jest niezbędne. Protokół jest wystarczająco prosty, aby nauczyć się go w jedno popołudnie, ale wystarczająco potężny, aby budować produkcyjne przepływy pracy AI.

Następne kroki:

• Poznaj Specyfikację MCP
• Przeglądaj istniejące serwery MCP w poszukiwaniu inspiracji
• Zbuduj swój pierwszy serwer z TypeScript lub Python SDK
• Przetestuj go z Claude Desktop lub MCP Inspector