Свой MCP-сервер:пишем с нуля

Готовые MCP-серверы закрывают типовое: документация, браузер, поиск. Но рано или поздно упираешься в задачу, которой нет в каталоге: «дай Claude читать нашу внутреннюю базу», «пусть дёргает наш приватный API», «научи его понимать наш формат данных». Тут и пишут свой MCP-сервер — это проще, чем кажется. По сути ты пишешь несколько обычных функций и оборачиваешь их в стандартный протокол, чтобы Claude мог их вызывать.

Часть 1 · Понятие

Что такое свой MCP-сервер

Расшифруем аббревиатуру. MCP (Model Context Protocol) — это стандарт, по которому модель получает доступ к внешним инструментам и данным. Сервер — программа, которая по этому стандарту предоставляет инструменты. Claude Code выступает клиентом: он подключается к серверу, видит список его инструментов и вызывает их, когда задача подходит.

Что такое MCP и как ставить готовые серверы — отдельный гайд про MCP-серверы и готовые связки. Здесь же мы идём дальше: не подключаем чужой сервер, а пишем свой, когда готового под задачу не существует.

Часть 2 · Анатомия

Из чего состоит сервер

Инструмент — это центральное понятие. Думай о нём как об одной функции, которую ты разрешаешь вызывать Claude. У инструмента четыре части:

Инструмент — это одна функция, которую ты разрешаешь Claude вызывать. Сервер — набор таких функций под одним протоколом.

Описание инструмента работает так же, как описание скила: чем точнее формулировка «когда меня использовать», тем чаще Claude зовёт инструмент там, где надо. Это та же логика, что в гайде про скилы Claude Code— модель матчит задачу с описанием.

Часть 3 · Код

Скелет сервера на TypeScript

Серверы пишут на любом языке, для которого есть SDK; чаще всего на TypeScript или Python. Возьмём TypeScript и официальный пакет @modelcontextprotocol/sdk. Сначала ставим зависимости:

# Заводим проект и ставим официальный MCP SDK
npm init -y
npm install @modelcontextprotocol/sdk

Теперь скелет. Логика простая: создаём сервер, объявляем один инструмент с понятным описанием и схемой входа, пишем обработчик, запускаем на stdio. Код ниже — иллюстрация устройства (точные сигнатуры сверяй с актуальной докой SDK):

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

// 1. Заводим сервер с именем и версией
const server = new McpServer({ name: "my-orders", version: "1.0.0" });

// 2. Регистрируем инструмент: имя, описание, схема входа, обработчик
server.tool(
  "get_order",                       // имя — короткое и понятное
  "Достать заказ по номеру из нашей внутренней базы", // описание = триггер
  { orderId: z.string() },           // схема входа: один строковый параметр
  async ({ orderId }) => {
    // 3. Обработчик: тут твоя реальная логика (запрос в БД, вызов API)
    const order = await fetchOrderFromDb(orderId);
    return { content: [{ type: "text", text: JSON.stringify(order) }] };
  },
);

// 4. Запускаем на транспорте stdio — Claude общается через ввод-вывод
await server.connect(new StdioServerTransport());

Разберём по шагам. Сервер заводится один раз с именем и версией. Инструмент — это четыре части из прошлого раздела, собранные в один вызов: имя, описание, схема входа (тут через библиотеку zod), обработчик. Транспорт stdio в конце — способ, которым Claude будет общаться с сервером. Всё, что реально делает работу, живёт в обработчике: запрос в базу, вызов API, чтение файла.

Часть 4 · Подключение

Подключаем сервер к Claude Code

Способ 1. Команда claude mcp add

Для локального сервера на stdio: указываешь имя и через -- — команду запуска процесса. Всё, что после --, это как запустить твой сервер:

# Синтаксис: claude mcp add <имя> -- <команда запуска>
claude mcp add my-orders -- node /path/to/server.js

# С переменной окружения (например, ключ к базе)
claude mcp add my-orders --env DB_URL=postgres://... -- node /path/to/server.js

Способ 2. Файл .mcp.json

Если сервер нужен всей команде — пропиши его в .mcp.json в корне проекта. Файл едет в гит, и при git pull сервер появляется у всех:

{
  "mcpServers": {
    "my-orders": {
      "type": "stdio",
      "command": "node",
      "args": ["./mcp/server.js"]
    }
  }
}

После подключения Claude Code видит инструменты сервера и зовёт их по описанию — как любые встроенные. Проверить, что сервер подключился, можно командой /mcp в чате.

Часть 5 · Транспорт

Транспорт и область видимости

stdio против HTTP

Транспорт stdio — это локальный сервер: Claude запускает его как процесс на твоей машине и говорит с ним через стандартный ввод-вывод. Идеален для инструментов, работающих локально: доступ к файлам, локальной базе, скриптам. Транспорт HTTP — это удалённый сервер по URL, к которому подключаются по сети. Берут, когда сервис крутится на хосте и доступен команде.

Scope: кто видит сервер

При добавлении через claude mcp add у сервера есть область видимости (scope), как и у скилов с командами:

1. local — приватный для текущего проекта, только у тебя. Дефолт.
2. project — в .mcp.json проекта, едет в гит, виден всей команде.
3. user — твой личный сервер во всех проектах на этой машине.

Вопросы

Частые вопросы

Читать дальше

Соседние гайды