🔌 MCP-серверы

Model Context Protocol: что это, архитектура, сервер на Python и TypeScript, подключение к клиентам.

Шпаргалки · ИИ · #mcp #ai #agents #tools

Что это

MCP (Model Context Protocol) открытый протокол, по которому ИИ-приложение (клиент) подключается к внешним инструментам и данным через серверы. Один стандарт вместо отдельной интеграции под каждую систему.

Архитектура

Роль Описание
Host (хост) приложение с моделью: Claude Desktop, Claude Code, IDE, свой агент
Client часть хоста, держит соединение с одним сервером
Server программа, предоставляющая возможности

Сообщения JSON-RPC 2.0. Транспорты: stdio (локальный процесс) и Streamable HTTP (удалённый сервер; прежнее SSE устарело).

Что даёт сервер

Примитив Кто управляет Смысл
Tools модель функции для вызова (поиск, запись, запрос к API)
Resources приложение данные для чтения: файлы, записи, схемы
Prompts пользователь шаблоны запросов и сценарии
Sampling, Roots, Elicitation клиент запрос генерации у клиента, границы файлов, уточнение у пользователя

Сервер на Python (FastMCP)

pip install "mcp[cli]"

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Погода")

@mcp.tool()
def get_forecast(city: str) -> str:
    """Прогноз погоды для города."""
    return f"{city}: +12°C, облачно"

@mcp.resource("notes://{name}")
def note(name: str) -> str:
    return f"Содержимое заметки {name}"

if __name__ == "__main__":
    mcp.run()          # stdio по умолчанию

Отладка: mcp dev server.py (MCP Inspector).

Сервер на TypeScript

npm i @modelcontextprotocol/sdk zod

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: "weather", version: "1.0.0" });

server.tool("get_forecast", { city: z.string() }, async ({ city }) => ({
  content: [{ type: "text", text: `${city}: +12°C` }],
}));

await server.connect(new StdioServerTransport());

Подключение (Claude Desktop, claude_desktop_config.json)

{
  "mcpServers": {
    "weather": { "command": "python", "args": ["/path/server.py"] },
    "files": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/docs"] },
    "remote": { "url": "https://mcp.example.com/mcp" }
  }
}

Claude Code: claude mcp add weather -- python /path/server.py, claude mcp list.

Известные серверы

Файловая система, Git и GitHub, PostgreSQL и SQLite, Slack, Google Drive, Puppeteer и Playwright (браузер), Fetch (веб-страницы), Memory, Sentry, Notion, Jira, Docker и Kubernetes.

Безопасность

  • Принцип наименьших прав: давайте серверу только нужные папки, токены с минимальным набором прав.
  • Подтверждение пользователя для действий с последствиями (запись, удаление, отправка).
  • Недоверенные данные (страницы, письма) могут содержать инструкции для модели (prompt injection): не передавайте им чувствительные инструменты без проверки.
  • Устанавливайте серверы только из доверенных источников и просматривайте код.
  • Логируйте вызовы инструментов.

Практика

Описание инструмента влияет на его выбор моделью: делайте имена и описания точными, параметры типизированными, ответы краткими и структурированными.