Claude Code от Anthropic — это агентная среда разработки, работающая прямо в терминале. В отличие от чат-интерфейсов, она имеет доступ к файловой системе, может выполнять команды и взаимодействовать с Git. Но главное преимущество — возможность расширять функциональность через кастомные инструменты.
Из коробки Claude Code умеет читать и редактировать файлы, запускать shell-команды, искать по проекту и работать с Git. Однако реальная ценность для разработчика появляется тогда, когда агент получает доступ к специализированным инструментам: поиску по внутренней документации, вызову внешних API, работе с базами данных или запуску кастомных скриптов.
В этом руководстве разберём, как подключать собственные инструменты двумя способами: через MCP-серверы и через кастомные shell-инструменты. Рассмотрим реальные примеры конфигурации, ограничения безопасности и типичные ошибки.
Что такое MCP и зачем он нужен в Claude Code
Model Context Protocol (MCP) — это открытый протокол, который Anthropic предложила для стандартизации взаимодействия между LLM-агентами и внешними инструментами. В контексте Claude Code MCP-сервер работает как отдельный процесс, с которым агент общается через JSON-RPC по stdin/stdout.
Архитектура MCP решает несколько проблем. Во-первых, она изолирует код инструмента от основного процесса агента — ошибка в MCP-сервере не ломает Claude Code. Во-вторых, она позволяет переиспользовать одни и те же инструменты между разными агентами: MCP-сервер, написанный для Claude Code, будет работать и с Claude Desktop, и с любым другим MCP-совместимым клиентом.
MCP-сервер может предоставлять три типа ресурсов: инструменты (tools) — функции, которые агент вызывает по своей инициативе; ресурсы (resources) — данные, которые агент может читать; промпты (prompts) — шаблоны для конкретных сценариев. Для Claude Code наиболее актуальны инструменты.
Установка MCP-сервера: пошаговый пример
Рассмотрим подключение MCP-сервера на практике. Anthropic поддерживает репозиторий с готовыми серверами на GitHub — там есть интеграции с Filesystem, GitHub, GitLab, Slack, PostgreSQL и другими системами.
Установим сервер для работы с файловой системой с дополнительными возможностями. Репозиторий `modelcontextprotocol/servers` содержит пакет `@modelcontextprotocol/server-filesystem`, но для демонстрации лучше взять сервер, который добавляет поиск по содержимому файлов — например, `@anthropic/server-filesystem-search`.
Установка через npm:
bash
npm install -g @anthropic/server-filesystem-search
После установки нужно добавить сервер в конфигурацию Claude Code. Файл конфигурации находится в `~/.claude/claude_dotfiles/claude.json` (на macOS) или в соответствующей директории для вашей ОС.
Добавляем секцию `mcpServers`:
json
{
«mcpServers»: {
«filesystem-search»: {
«command»: «npx»,
«args»: [«-y», «@anthropic/server-filesystem-search», «—allowed-directories», «/path/to/your/project»]
}
}
}
После перезапуска Claude Code агент получит новый инструмент для поиска по содержимому файлов с поддержкой регулярных выражений. Проверить, что сервер подключился, можно командой `/tools` внутри Claude Code — она покажет список всех доступных инструментов.
Обратите внимание на параметр `—allowed-directories` — это механизм безопасности MCP-сервера, который ограничивает доступ к файловой системе. Без него сервер сможет читать любые файлы, к которым у процесса есть доступ.
Кастомные shell-инструменты: когда MCP избыточен
Не все инструменты требуют MCP. Claude Code поддерживает кастомные shell-инструменты — это скрипты, которые агент может вызывать как команды. Они проще в настройке, но дают меньше контроля над тем, как агент их использует.
Кастомные shell-инструменты описываются в том же конфигурационном файле, в секции `customCommands`:
json
{
«customCommands»: [
{
«name»: «search-docs»,
«command»: «grep -r -l \»$QUERY\» /path/to/docs/»,
«description»: «Поиск по файлам документации»
},
{
«name»: «lint-project»,
«command»: «npx eslint . —format json»,
«description»: «Запуск ESLint для всего проекта»
}
]
}
Разница между MCP-инструментами и кастомными командами принципиальная. MCP-сервер — это самостоятельный процесс с собственной логикой, который может обрабатывать аргументы, возвращать структурированные данные и управлять состоянием. Кастомная команда — это просто shell-строка, которую Claude Code выполняет. Агент не видит структуры возвращаемых данных — только stdout и stderr.
Для простых операций — поиск по файлам, запуск линтера, проверка синтаксиса — кастомных команд достаточно. Для сложных сценариев с валидацией ввода, обработкой ошибок и структурированным выводом нужен MCP.
Создание собственного MCP-сервера на Python
Когда готовых серверов недостаточно, можно написать свой. MCP поддерживает Python, TypeScript и Java. Рассмотрим пример на Python — он проще для быстрой разработки.
Устанавливаем SDK:
bash
pip install mcp
Создаём сервер с инструментом для поиска по базе знаний в формате Markdown:
python
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent
import sqlite3
import json
server = Server(«knowledge-base»)
@server.list_tools()
async def list_tools():
return [
Tool(
name=»search_knowledge_base»,
description=»Поиск по базе знаний в формате Markdown»,
inputSchema={
«type»: «object»,
«properties»: {
«query»: {«type»: «string», «description»: «Поисковый запрос»}
},
«required»: [«query»]
}
)
]
@server.call_tool()
async def call_tool(name: str, arguments: dict):
if name == «search_knowledge_base»:
conn = sqlite3.connect(«/path/to/knowledge.db»)
cursor = conn.cursor()
cursor.execute(
«SELECT title, content, url FROM docs WHERE content LIKE ? LIMIT 5»,
(f»%{arguments[‘query’]}%»,)
)
results = cursor.fetchall()
conn.close()
formatted = []
for title, content, url in results:
formatted.append(f»## {title}\n{content[:500]}…\nИсточник: {url}\n»)
return [TextContent(type=»text», text=»\n—\n».join(formatted))]
raise ValueError(f»Unknown tool: {name}»)
if name == «main»:
import asyncio
asyncio.run(stdio_server(server))
Сервер использует SQLite для хранения базы знаний и возвращает агенту структурированные результаты с заголовками, содержимым и ссылками на источники. Claude Code сам решит, когда вызывать этот инструмент — на основе описания и схемы входных данных.
Подключается такой сервер стандартно:
json
{
«mcpServers»: {
«knowledge-base»: {
«command»: «python»,
«args»: [«/path/to/knowledge_server.py»]
}
}
}
Ограничения безопасности и контроль агентного контура
Кастомные инструменты расширяют возможности Claude Code, но создают и новые риски. Агент может вызвать инструмент с неожиданными аргументами, особенно если описание инструмента недостаточно точное.
Основные правила безопасности при работе с кастомными инструментами:
MCP-сервер должен проверять входные данные. Если инструмент принимает путь к файлу — сервер должен убедиться, что путь не выходит за пределы разрешённой директории. Если инструмент выполняет SQL-запросы — сервер должен экранировать параметры.
Не давайте агенту инструменты с побочными эффектами без явного подтверждения. Если инструмент удаляет данные или отправляет запросы во внешние системы, добавьте флаг подтверждения в схему входных данных — например, поле `confirm: true`, которое агент должен явно установить.
Используйте минимальные привилегии. MCP-сервер не должен иметь доступа к системным директориям, если это не требуется для его работы. Для сервера базы знаний достаточно read-only доступа к файлу базы данных.
Claude Code также имеет собственные механизмы безопасности: он запрашивает подтверждение перед выполнением опасных команд и показывает, какие инструменты вызываются. При первом запуске MCP-сервера агент сообщает о подключении нового инструмента и может запросить подтверждение.
Типичные проблемы и их решение
При настройке кастомных инструментов возникают несколько типичных проблем.
MCP-сервер не подключается. Проверьте, что команда запуска корректна — выполните её в терминале отдельно. Ошибки MCP-сервера пишутся в stderr, но Claude Code может не показывать их в интерфейсе. Запустите Claude Code с флагом `—verbose` для диагностики.
Агент не использует инструмент. Чаще всего проблема в описании инструмента. Claude Code принимает решение о вызове инструмента на основе его названия и описания. Если описание неинформативно или не соответствует реальной задаче — агент его проигнорирует. Перепишите description так, чтобы было понятно, когда и зачем вызывать инструмент.
Инструмент возвращает ошибку. MCP-сервер должен корректно обрабатывать исключения и возвращать понятные сообщения об ошибках. Если сервер упал с исключением, Claude Code может потерять контекст и начать заново. Добавьте try/except в обработчики инструментов.
Совместимость версий. MCP-протокол развивается, и версии SDK могут отличаться. Используйте последнюю стабильную версию `mcp` Python-пакета. Для TypeScript-серверов проверяйте совместимость с версией MCP, которую использует ваша версия Claude Code.
Практические сценарии: что реально стоит подключать
Исходя из опыта работы с Claude Code, наиболее полезные кастомные инструменты для реальных проектов:
Поиск по внутренней документации и API-спецификациям. Если в проекте есть OpenAPI-спецификация или Confluence-документация — подключите их как MCP-ресурс или инструмент поиска. Это резко сокращает количество галлюцинаций при генерации кода, работающего с внутренними API.
Интеграция с системой тикетов. MCP-сервер, который умеет получать описание задачи из Jira или Linear, позволяет агенту работать в контексте реальной задачи без ручного копирования требований.
Запуск тестов с анализом результатов. Вместо того чтобы просить агента запустить тесты и прочитать вывод, дайте ему инструмент, который запускает тесты, парсит результаты и возвращает структурированный отчёт с указанием упавших тестов и причин.
Валидация кода перед коммитом. Инструмент, который проверяет код на соответствие стандартам проекта, запускает линтер и проверяет типы, помогает агенту не создавать коммиты, которые потом отклонят на CI.
Что дальше: проверьте свою конфигурацию
После настройки кастомных инструментов стоит проверить, что всё работает корректно. Откройте Claude Code и выполните команду `/tools` — вы должны увидеть список всех подключённых инструментов с их описаниями.
Затем дайте агенту задачу, которая должна использовать новый инструмент. Например, если вы подключили поиск по документации, попросите: «Найди в документации описание функции авторизации и напиши тест для неё». Если инструмент не вызывается — проверьте описание и перезапустите Claude Code.
Помните, что кастомные инструменты — это не серебряная пуля. Они расширяют возможности агента, но не заменяют качественного промптинга и проверки результатов. Всегда проверяйте, что агент действительно использует инструмент, а не генерирует ответ на основе своих внутренних знаний.