Claude Code MCP Server po polsku, kompletny tutorial 2026

Spis treści

• Czym jest Model Context Protocol
• Architektura, stdio vs SSE vs HTTP
• Jak Claude rozmawia z MCP serverem
• Pierwszy MCP server w Pythonie
• MCP server w TypeScript / Node
• 5 praktycznych przykładów
• Podłączenie do Claude Code
• Security model i sekrety
• Testowanie MCP servera
• Antywzorce
• Ekosystem gotowych MCP servers
• FAQ

Aktualizacja: maj 2026. MCP (Model Context Protocol) to najważniejszy standard w ekosystemie agentów AI od czasu OpenAI Functions. Wprowadzony przez Anthropic w listopadzie 2024, w 2026 jest już wspierany przez OpenAI, Cursor, Zed, Continue i kilkanaście innych klientów. W tym tutorialu pokazuję czym jest MCP, jak działa pod maską (stdio vs SSE, JSON-RPC handshake, tool discovery), oraz jak napisać własny MCP server w Pythonie i TypeScript od zera w 30 minut. Z gotowymi przykładami i antywzorcami z produkcyjnej praktyki.

Czym jest Model Context Protocol

MCP to otwarty protokół, który definiuje jak modele LLM rozmawiają z zewnętrznymi źródłami danych i narzędziami. Anthropic ogłosił go w listopadzie 2024 jako odpowiedź na chaos w ekosystemie, każdy klient miał swój własny sposób na integracje (Cursor extensions, ChatGPT plugins, Copilot tools), żaden nie był przenośny.

Pomyśl o MCP jak o LSP (Language Server Protocol) dla LLM. LSP zunifikowało komunikację edytor-narzędzia językowe, dzięki temu jeden serwer (np. pyright dla Pythona) działa w VS Code, Neovim, Sublime, Zed. MCP robi to samo dla agentów AI, jeden MCP server (np. GitHub bridge) działa w Claude Code, Cursor, Continue, Zed.

Co dokładnie wystawia MCP server? Trzy rzeczy:

• Tools, funkcje, które Claude może wywołać (np. search_issues, create_pull_request, query_database). Każdy tool ma nazwę, opis i schema parametrów.
• Resources, dane, które Claude może czytać on-demand (np. file://path/to/file, db://users/123). Resources są referencyjne, Claude pobiera tylko te, których potrzebuje.
• Prompts, templates promptów, które klient (Claude Code) może wstrzyknąć do sesji (np. /review-pr z preconfigured promptem do code review).

Dlaczego to game-changer? Bez MCP każda integracja Claude'a z Twoim systemem to ręczne kopiowanie kontekstu (skopiuj output git log do chatu, wklej JSON z bazy, screenshot z Linear). Z MCP Claude czyta to bezpośrednio, ma świeże dane, ma narzędzia do akcji. Workflow typu "dodaj feature X, sprawdź czy ticket Linear ma wszystkie szczegóły, wystaw PR z linkiem do ticketu" idzie automatycznie.

Jeśli dopiero zaczynasz z Claude Code, zacznij od pillaru Claude Code tutorial po polsku, a potem wracaj tu po deep dive w MCP.

Architektura MCP, stdio vs SSE vs HTTP

MCP definiuje 3 transporty (sposoby komunikacji klient-server). Wybór transportu zależy od tego, gdzie biegnie server i jak długo żyje.

Porównanie transportów MCP

Transport	Use case	Lokalizacja servera	Latencja	Złożoność
stdio	Lokalne narzędzia, dev tooling, default	Lokalnie (child process klienta)	Bardzo niska, 1-10 ms	Najprostszy
sse	Współdzielony server, długie streamy	Lokalnie lub zdalnie	Średnia, 20-100 ms	Wymaga HTTP servera
http	Request-response, stateless API	Zdalnie	Średnia, 30-200 ms	Wymaga HTTP servera + auth

Stdio to default. Server jest spawnowany jako child process Claude Code, komunikacja idzie przez stdin/stdout w formacie JSON-RPC 2.0 (każda wiadomość to jedna linia JSON). Zero konfiguracji sieci, zero auth (bo lokalne). Dla 90% przypadków to wystarczy.

SSE (Server-Sent Events) używasz, gdy server musi być zdalny (firmowy serwer dostępny dla kilku developerów) albo gdy chcesz, żeby server żył dłużej niż jedna sesja Claude Code (np. cache w pamięci między sesjami). SSE używa HTTP + długo żyjące połączenie typu event-stream.

HTTP to nowszy transport (dodany w 2025), stateless request-response. Każde wywołanie tool to oddzielny POST. Dobry, gdy stoisz za load balancerem albo deployujesz MCP jako serverless function.

Jak Claude rozmawia z MCP serverem

Pod maską MCP używa JSON-RPC 2.0. Każda wiadomość ma id, method i params (lub result / error dla odpowiedzi). Pełny przebieg sesji:

1. Spawn, Claude Code startuje server jako child process (dla stdio) lub łączy się przez HTTP/SSE.
2. Initialize, Claude wysyła initialize z wersją protokołu i swoimi capabilities. Server odpowiada swoimi capabilities (czy wspiera tools, resources, prompts).
3. List tools, Claude pyta tools/list. Server odpowiada listą narzędzi z nazwami, opisami i JSON Schema parametrów.
4. Tool call, kiedy Claude potrzebuje użyć narzędzia, wysyła tools/call z nazwą i argumentami. Server wykonuje akcję i zwraca result (tekst, JSON, image, file content).
5. Shutdown, na zakończenie sesji Claude wysyła shutdown, server kończy się czysto.

Przykład realnego tools/call response, który zobaczysz w logach:

{
  "jsonrpc": "2.0",
  "id": 42,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 3 issues in repo 'kursai':\n- #12 fix mobile nav\n- #15 add MCP article\n- #18 update pricing"
      }
    ],
    "isError": false
  }
}

Claude wkleja zawartość content do swojego kontekstu i kontynuuje rozumowanie. Z perspektywy modelu tool MCP wygląda identycznie jak tool wbudowany (Bash, Edit, Read), różni się tylko prefiksem nazwy: mcp__<server_name>__<tool_name>.

Twój pierwszy MCP server w Pythonie

Zacznijmy od najprostszego working example, MCP server, który dodaje dwie liczby i pyta o aktualny czas. Tak, trywialne, ale pokazuje pełny shape API.

Krok 1, instalacja SDK:

python -m venv .venv
source .venv/bin/activate
pip install mcp

Krok 2, plik server.py:

#!/usr/bin/env python
"""Mini MCP server, demo z dwoma tools."""
from datetime import datetime
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("kursai-demo")


@mcp.tool()
def add_numbers(a: float, b: float) -> float:
    """Dodaje dwie liczby i zwraca sumę."""
    return a + b


@mcp.tool()
def current_time(timezone: str = "Europe/Warsaw") -> str:
    """Zwraca aktualny czas w podanej strefie (ISO 8601)."""
    # uproszczona logika dla przykładu
    return datetime.now().isoformat() + f" ({timezone})"


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

To wszystko. Cztery rzeczy do zauważenia:

• FastMCP("kursai-demo"), nazwa servera (pojawi się w prefiksie tools w Claude).
• @mcp.tool(), dekorator zamienia funkcję Python w MCP tool. Type hints automatycznie generują JSON Schema parametrów.
• docstring, opis funkcji idzie do description w MCP. To Claude widzi i na tej podstawie decyduje, czy użyć narzędzia. Pisz konkretnie.
• transport="stdio", dla lokalnego użycia.

Krok 3, dodaj do .claude/settings.json:

{
  "mcpServers": {
    "kursai-demo": {
      "command": "python",
      "args": ["./server.py"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Otwórz Claude Code w projekcie i wpisz "policz 17 + 25 używając toola". Claude wywoła mcp__kursai-demo__add_numbers(a=17, b=25), server zwróci 42, Claude wkleje to do odpowiedzi. Działa.

MCP server w TypeScript / Node

Jeśli wolisz Node, oficjalny SDK jest jeszcze prostszy. Instalacja:

npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript tsx @types/node
npx tsc --init

Plik server.ts:

#!/usr/bin/env node
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: "kursai-demo-ts",
  version: "1.0.0",
});

server.tool(
  "add_numbers",
  "Dodaje dwie liczby i zwraca sumę.",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  })
);

server.tool(
  "current_time",
  "Zwraca aktualny czas ISO 8601.",
  { timezone: z.string().default("Europe/Warsaw") },
  async ({ timezone }) => ({
    content: [{ type: "text", text: `${new Date().toISOString()} (${timezone})` }],
  })
);

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

Uruchom przez tsx server.ts. Konfiguracja w .claude/settings.json:

{
  "mcpServers": {
    "kursai-demo-ts": {
      "command": "npx",
      "args": ["tsx", "./server.ts"]
    }
  }
}

Co warto wiedzieć przy TypeScript wersji:

• Zod jest defacto standardem dla schema parametrów. SDK zamienia Zod schema na JSON Schema automatycznie.
• Logi przez console.error, nigdy console.log. console.log idzie do stdout, który jest zajęty przez JSON-RPC, każdy log psuje protokół.
• Build vs tsx, w dev używaj tsx (zero build step). W produkcji tsc i odpalaj skompilowany JS, szybciej startuje.

5 praktycznych przykładów MCP serverów

Trywialny add_numbers to demo. Realne MCP servery łączą Claude z systemami, których inaczej musiałbyś używać ręcznie. Pięć przykładów z mojej praktyki:

1. GitHub bridge (issues, PR, commits)

Wystawia tools: search_issues, create_issue, list_pull_requests, get_commit_diff. Pod spodem używa @octokit/rest z auth tokenem w env. Use case: "znajdź ostatnie 5 zamkniętych issues w kursai i pokaż które mają najwięcej komentarzy". Claude wywoła tool, dostanie JSON, wyciągnie informacje.

2. Linear bridge (tasks, projects, cycles)

Tools: list_my_tasks, create_task, update_status, get_cycle_progress. Use case: "dodaj task w Linear: 'naprawić mobile nav po feedback z PR #12', przypisz mi, priorytet wysoki, milestone Q2". Claude buduje request z kontekstu rozmowy.

3. Custom database reader (Postgres, MySQL)

Tools: list_tables, describe_table, query_readonly. Z constraint, że query_readonly akceptuje tylko SELECT (parsuje przez sqlparse i odrzuca DML). Use case: Claude debuguje bug z danych produkcyjnych bez kopiowania query do panelu admina.

4. Internal API gateway

Bridge do firmowego REST API. Tools generowane z OpenAPI spec, openapi_to_mcp.py czyta YAML i wystawia każdy endpoint jako tool z poprawnym schema. Auth idzie z env var INTERNAL_API_KEY. Use case: Claude robi pełny workflow z firmowym CRM/billingiem bez kontekst-switchowania do innego UI.

5. File system indexer z embeddings

Tools: semantic_search (vector search po treści plików), find_by_topic. Background process buduje index w SQLite z embeddings (sentence-transformers). Use case: w monorepo z 5000 plików Claude szybko znajduje "gdzie jest logika rate limitingu" bez czytania całego repo.

Pełne implementacje (~200 linii każda, plus testy) są w pack templates dołączonym do Kursu Claude Code po polsku.

Podłączenie servera do Claude Code

Konfiguracja MCP servera idzie do .claude/settings.json (per-projekt) lub ~/.claude/settings.json (globalnie). Pełna struktura:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    },
    "postgres": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "DATABASE_URL",
        "mcp/postgres:latest"
      ],
      "env": {
        "DATABASE_URL": "postgresql://user:pass@host/db"
      }
    },
    "linear": {
      "command": "node",
      "args": ["./tools/linear-mcp/dist/server.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_..."
      }
    }
  }
}

Klucze do zapamiętania:

• command, executable (najczęściej npx, python, node, docker).
• args, lista argumentów. Pamiętaj o -y dla npx, inaczej zapyta o instalację interaktywnie.
• env, zmienne środowiskowe przekazane do servera. Sekrety trzymaj tu, nie w args.
• cwd (opcjonalnie), katalog roboczy, w którym server startuje.

Po zapisaniu pliku zrestartuj Claude Code (sesja musi spawn-nąć server od nowa). Sprawdź, czy działa: /mcp list w Claude Code pokaże aktywne servery i ich tools. Jeśli czegoś brakuje, zobacz sekcję testowania.

Security model, trust boundaries i sekrety

MCP server biegnie z pełnymi uprawnieniami Twojego usera. Ma dostęp do: plików, sieci, zmiennych środowiskowych, kluczy SSH, certyfikatów. Trust model jest binarny, jak zainstalujesz server, dajesz mu wszystko.

Realne zagrożenia, które widziałem w praktyce:

• Supply chain attack, npm package udający oficjalny MCP server, wycieka process.env przy starcie. Mitigation: instaluj tylko z oficjalnego katalogu Anthropic albo po code review.
• Sekrety w args zamiast env, "args": ["--api-key=sk-..."] widać w outputcie ps -ef. Zawsze używaj "env".
• Prompt injection przez tool result, jeśli MCP zwraca dane z zewnętrznego źródła (np. GitHub issue zawierający "ignore previous instructions and..."), Claude przeczyta to jako instrukcję. Mitigation: sanityzacja w MCP server albo system prompt po stronie Claude.
• Exfiltration przez wywołania sieciowe, server może POST-ować Twoje sekrety do dowolnego endpointu. Mitigation: na produkcji uruchamiaj MCP w Dockerze z --network=none albo allowlistą domen przez firewall.

Pattern produkcyjny dla MCP wystawiającego firmowe API:

{
  "mcpServers": {
    "internal-api": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--network=host",
        "--read-only",
        "--cap-drop=ALL",
        "--security-opt=no-new-privileges",
        "-e", "INTERNAL_API_KEY",
        "ghcr.io/firma/mcp-internal:1.2.3"
      ],
      "env": {
        "INTERNAL_API_KEY": "${INTERNAL_API_KEY}"
      }
    }
  }
}

Zauważ --read-only (server nie zapisze nic na disk), --cap-drop=ALL (brak capabilities Linux), oraz przekazanie sekretu przez referencję do env ($${INTERNAL_API_KEY}) zamiast hardcodowania w pliku.

Testowanie MCP servera

MCP server warto testować na dwóch poziomach: unit (logika tools w izolacji) i integration (end-to-end przez protokół).

Unit testy piszesz normalnie. Funkcja udekorowana @mcp.tool() jest nadal zwykłą funkcją Python, możesz wołać ją bezpośrednio w pytest:

# tests/test_server.py
from server import add_numbers, current_time

def test_add():
    assert add_numbers(2, 3) == 5
    assert add_numbers(-1, 1) == 0

def test_time_format():
    result = current_time("Europe/Warsaw")
    assert "Europe/Warsaw" in result
    assert "T" in result  # ISO 8601

Integration test przez MCP Inspector (oficjalne narzędzie debug od Anthropic):

npx @modelcontextprotocol/inspector python ./server.py

Otwiera się UI w przeglądarce, gdzie widzisz: handshake, listę tools, możesz wywołać każdy tool ręcznie i zobaczyć JSON-RPC traffic. Najszybsza droga do debugowania, czemu Claude nie używa Twojego toola.

Dla CI zrobisz integration test programatycznie, używając klienta MCP z SDK:

# tests/test_integration.py
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def test_list_tools():
    params = StdioServerParameters(command="python", args=["server.py"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            names = [t.name for t in tools.tools]
            assert "add_numbers" in names
            assert "current_time" in names

def test_main():
    asyncio.run(test_list_tools())

Antywzorce, czego unikać przy pisaniu MCP

1. Niejasne nazwy i opisy tools, do_thing z opisem "robi rzecz" gwarantuje, że Claude nie użyje. Konwencja: verb_object (np. search_issues, create_task), opis w 1 zdaniu mówiący kiedy użyć i co zwraca.
2. Print/console.log do stdout, łamie JSON-RPC protokół. Każdy log idzie przez stderr albo logger. To 50% problemów debugowych z MCP.
3. Zbyt duże response, tool zwracający 50 KB JSON zapycha context window Claude'a. Zwracaj zsumaryzowane dane, pełne wyniki wystawiaj jako resources, które Claude pobierze on-demand.
4. Hardcoded credentials, klucze w kodzie servera. Zawsze przez env vars, nawet w dev.
5. Brak timeout na external calls, MCP tool wołający zewnętrzne API bez timeout potrafi zawiesić całą sesję Claude. Default 30 s na każdy external call.
6. Blocking I/O w Pythonie, używasz requests zamiast httpx.AsyncClient, blockujesz event loop. FastMCP wspiera async, używaj go.
7. One mega-tool zamiast wielu małych, do_github_stuff(action, ...args) jest gorsze niż 5 oddzielnych tools (list_issues, create_issue, itd.). Claude lepiej routuje przy konkretnych tools.
8. Brak idempotencji, tool, który tworzy zasób bez check-update-or-create, generuje duplikaty przy retry. Dla wszystkich create operations rozważ idempotency key.

Ekosystem gotowych MCP servers, co używać w 2026

Zanim napiszesz własny MCP, sprawdź czy ktoś już zrobił. Trzy źródła:

1) Anthropic official catalog (github.com/modelcontextprotocol/servers):

• filesystem, czyta/pisze pliki z sandboxowanego katalogu
• github, issues, PR, commits, files
• gitlab, analogiczne dla GitLab
• postgres, read-only queries z introspect schema
• sqlite, full read-write SQLite
• slack, channels, messages, search
• google-drive, list i fetch plików
• brave-search, web search przez Brave API
• puppeteer, web scraping i automation
• sentry, error tracking

2) Community katalog (github.com/punkpeye/awesome-mcp-servers), zbiera 200+ serverów do prawie wszystkiego: Notion, Linear, Figma, ClickUp, Stripe, AWS, Kubernetes, Datadog, Grafana, Spotify, Steam, weather, finance APIs.

3) Anthropic Connector marketplace (od Q4 2025), oficjalny marketplace dla zweryfikowanych enterprise MCP servers z auth flow i payments. Najczystszy sposób na monetyzację własnego MCP.

Strategia, którą rekomenduję klientom: 80% potrzeb pokrywasz oficjalnymi serverami (filesystem, GitHub, Postgres, Slack). 20% to własne MCP do firmowych systemów. Nie pisz GitHub bridge od nowa, oficjalny jest production-quality.

Co dalej, ścieżka nauki MCP

MCP to jedna z trzech warstw advanced Claude Code (obok hooks i Agent SDK). Sensowna kolejność:

1. Najpierw opanuj basics, Claude Code tutorial po polsku
2. Potem automation, Claude Code hooks po polsku
3. Potem ten pillar (MCP), zacznij od oficjalnego GitHub MCP, potem napisz własny
4. Na końcu programmable agents, Claude Agent SDK po polsku
5. Dla wyboru narzędzia, Claude Code vs Cursor (Cursor też wspiera MCP, ale gorzej niż Claude Code)

Najczęściej zadawane pytania

Powiązane artykuły

Claude Code•9 min

Claude Code cena 2026, ile kosztuje i czy jest darmowy

Claude Code cena w PLN i USD, plany Pro i Max, API pay-as-you-go, darmowe kredyty i alternatywy. Najtańsza legalna ścieżka. Stan maj 2026.

Czytaj

Claude Code•9 min

Claude Max plan po polsku, ceny i limity 2026

Plan Claude Max po polsku: ceny Max 5x i 20x, ile zapytań daje, Claude Pro vs Max, Max vs API. Limity sesji i tygodniowe. Stan maj 2026, dla kogo warto.

Czytaj

Claude Code•15 min

Claude Code Skills po polsku, tutorial Agent Skills 2026

Pierwszy polski tutorial Agent Skills w Claude Code. SKILL.md, frontmatter, progressive disclosure, jak tworzyć skille krok po kroku, vs subagents i MCP.

Czytaj