MCP (Model Context Protocol)

В этой папке собрана подробная документация и примеры настройки и использования MCP-серверов с Claude Code.

Обзор

MCP (Model Context Protocol) - это стандартизированный способ доступа Claude к внешним инструментам, API и источникам данных в реальном времени. В отличие от Memory, MCP обеспечивает доступ к изменяющимся данным «на лету».

Ключевые особенности:

• Доступ к внешним сервисам в реальном времени
• Синхронизация данных «на лету»
• Расширяемая архитектура
• Безопасная аутентификация
• Взаимодействие через инструменты

Архитектура MCP

Экосистема MCP

Способы установки MCP

Claude Code поддерживает несколько транспортных протоколов для подключения к MCP-серверам:

HTTP-транспорт (рекомендуется)

# Basic HTTP connection
claude mcp add --transport http notion https://mcp.notion.com/mcp

# HTTP with authentication header
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Stdio-транспорт (локальный)

Для локально запускаемых MCP-серверов:

# Local Node.js server
claude mcp add --transport stdio myserver -- npx @myorg/mcp-server

# With environment variables
claude mcp add --transport stdio myserver --env KEY=value -- npx server

CLAUDE_PROJECT_DIR для stdio-серверов (v2.1.139+)

Каждый MCP stdio-сервер запускается с уже установленной в окружении переменной CLAUDE_PROJECT_DIR=<абсолютный путь к корню репозитория> - по той же схеме, что используется для hook'ов. Файлы .mcp.json уровня plugin и project могут ссылаться на ${CLAUDE_PROJECT_DIR} в значениях command, args и env; подстановка выполняется до вызова execve():

{
  "mcpServers": {
    "repo-tools": {
      "type": "stdio",
      "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/mcp/repo-tools.js"],
      "env": {
        "REPO_ROOT": "${CLAUDE_PROJECT_DIR}"
      }
    }
  }
}

Используйте этот вариант, когда вашему stdio-серверу требуется читать файлы относительно корня проекта независимо от того, откуда был запущен Claude Code.

stdio MCP-серверы также получают CLAUDE_CODE_SESSION_ID (совпадает со значением, передаваемым в hooks и Bash), в том числе при возобновлении сессии через --resume (v2.1.163+).

Транспорт SSE (устаревший)

Транспорт Server-Sent Events признан устаревшим в пользу http, но по-прежнему поддерживается:

claude mcp add --transport sse legacy-server https://example.com/sse

Транспорт WebSocket (ws)

WebSocket-серверы удерживают постоянное двунаправленное соединение, что удобно для удалённых MCP-серверов, самостоятельно отправляющих события в Claude. Если же ваш сервер только отвечает на запросы, используйте HTTP: он поддерживает OAuth и флаг claude mcp add --transport, тогда как WebSocket не поддерживает ни того, ни другого.

Так как --transport не принимает значение ws, настройте транспорт в .mcp.json или через claude mcp add-json:

{
  "type": "ws",
  "url": "wss://mcp.example.com/socket",
  "headers": {
    "Authorization": "Bearer YOUR_TOKEN"
  }
}

Запись type: "ws" принимает те же поля url, headers, headersHelper, timeout и alwaysLoad, что и http. Аутентификация возможна только через заголовки - OAuth-потока для WebSocket-серверов не предусмотрено.

Примечание: WebSocket-серверы не отображаются в выводе claude mcp list. Для их проверки используйте claude mcp get <name> или панель /mcp.

Как и HTTP с SSE, WebSocket-соединения используют 5-минутное окно простоя; при этом у stdio и WebSocket нет таймера на отдельный запрос. Запись url без указания type приводит к ошибке, в которой в качестве допустимых значений перечисляются "http", "sse" и "ws".

Рабочие директории сессии (roots/list)

MCP-серверы могут получать список рабочих директорий сессии: директория запуска и все записи --add-dir/additionalDirectories возвращаются по MCP-запросу roots/list, а при каждом изменении набора отправляется уведомление notifications/roots/list_changed (v2.1.203). Таймаут простоя теперь применяется и к stdio-серверам (30 минут), причём заданный для сервера timeout служит нижней границей простоя (v2.1.203).

Примечание для Windows

В нативной Windows (не в WSL) для команд npx используйте cmd /c:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Аутентификация OAuth 2.0

Claude Code поддерживает OAuth 2.0 для MCP-серверов, которые этого требуют. При подключении к серверу с поддержкой OAuth Claude Code берёт на себя весь процесс аутентификации:

# Connect to an OAuth-enabled MCP server (interactive flow)
claude mcp add --transport http my-service https://my-service.example.com/mcp

# Pre-configure OAuth credentials for non-interactive setup
claude mcp add --transport http my-service https://my-service.example.com/mcp \
  --client-id "your-client-id" \
  --client-secret "your-client-secret" \
  --callback-port 8080

Переопределение способа обнаружения метаданных OAuth

Если ваш MCP-сервер возвращает ошибки на стандартном endpoint метаданных OAuth (/.well-known/oauth-authorization-server), но при этом предоставляет рабочий OIDC endpoint, вы можете указать Claude Code, откуда получать метаданные OAuth. Задайте authServerMetadataUrl в объекте oauth конфигурации сервера:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

URL должен начинаться с https://. Эта опция требует Claude Code v2.1.64 или новее.

Уведомление об аутентификации при запуске и обновление динамических заголовков (v2.1.193)

• Уведомление об аутентификации при запуске (v2.1.193+): при старте Claude Code выводит уведомление со списком MCP-серверов, которым всё ещё требуется аутентификация, чтобы сервер, нуждающийся в логине, не оставался молча неработающим.
• Автообновление headersHelper (v2.1.193+): если вы задаёте собственную аутентификацию через headersHelper, этот helper автоматически вызывается повторно, когда сервер возвращает HTTP 401 или 403. Учётные данные обновляются на лету без ручного переподключения. См. Use dynamic headers for custom authentication.

Предупреждение (v2.1.238): headersHelper в проектном .mcp.json, а также inline MCP-серверы в проектных agent-файлах или файлах, подключённых через --add-dir, теперь требуют, чтобы для соответствующей папки был подтверждён trust dialog - в том числе при запуске через claude -p. Кроме того, такие helper'ы выполняются без унаследованных переменных окружения с учётными данными; helper'ы уровня user, managed и claude.ai вместо этого запускаются из директории конфигурации Claude. Проектная конфигурация, которая полагалась на унаследованные учётные данные или на запуск в недоверенном режиме, перестанет работать, пока вы не подтвердите trust dialog и не передадите учётные данные другим способом.

MCP-коннекторы Claude.ai

MCP-серверы, настроенные в вашей учётной записи Claude.ai, автоматически доступны в Claude Code. Это значит, что любые MCP-подключения, настроенные через веб-интерфейс Claude.ai, будут доступны без дополнительной настройки.

MCP-коннекторы Claude.ai также работают в режиме --print (v2.1.83+), что позволяет использовать их неинтерактивно и в скриптах.

Замечание о запуске (v2.1.117+): когда одновременно настроены и локальные, и claude.ai MCP-серверы, по умолчанию используется параллельное подключение (ранее оно было последовательным), что уменьшает задержку запуска при использовании нескольких серверов.

Чтобы отключить MCP-серверы Claude.ai в Claude Code, установите переменную окружения ENABLE_CLAUDEAI_MCP_SERVERS в false:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Примечание: Эта функция доступна только пользователям, вошедшим в систему с учётной записью Claude.ai.

Процесс настройки MCP

Команда /mcp

Введите /mcp в сессии, чтобы посмотреть список подключённых серверов, запустить OAuth-авторизацию и проверить состояние соединения.

• Начиная с версии v2.1.121, MCP повторяет попытку первичного подключения до 3 раз при временных ошибках.
• Начиная с версии v2.1.128, /mcp показывает число инструментов для каждого подключённого сервера и визуально выделяет серверы, у которых заявлено 0 инструментов, - так неправильно настроенные серверы сразу бросаются в глаза.

Поиск MCP-инструментов

Если описания MCP-инструментов занимают более 10% контекстного окна, Claude Code автоматически включает поиск по инструментам, чтобы подбирать нужные из них, не перегружая контекст модели.

Примечание: Поиск инструментов работает только с Sonnet 4 и новее либо Opus 4 и новее. Модели Haiku поиск инструментов не поддерживают.

Отключение поиска инструментов для отдельного сервера (v2.1.121+)

Если инструменты конкретного MCP-сервера нужны на каждом шаге, добавьте в его конфигурацию "alwaysLoad": true - это отключит отложенную загрузку через поиск инструментов и оставит его инструменты всегда доступными:

{
  "mcpServers": {
    "always-on-tool": {
      "command": "node",
      "args": ["./tools/always.js"],
      "alwaysLoad": true
    }
  }
}

Используйте с осторожностью - каждый постоянно загружаемый инструмент занимает контекст, который иначе мог бы использоваться поиском по инструментам для подбора более подходящего.

Динамическое обновление инструментов

Claude Code поддерживает MCP-уведомления list_changed. Когда MCP-сервер динамически добавляет, удаляет или изменяет доступные инструменты, Claude Code получает уведомление и автоматически обновляет список инструментов - без переподключения или перезапуска.

MCP Apps

MCP Apps - первое официальное расширение MCP, позволяющее вызовам MCP-инструментов возвращать интерактивные UI-компоненты, которые отрисовываются прямо в интерфейсе чата. Вместо простых текстовых ответов MCP-серверы могут выдавать полноценные дашборды, формы, визуализации данных и многошаговые сценарии - всё это отображается прямо в чате, не прерывая диалог.

MCP Elicitation

MCP-серверы могут запрашивать у пользователя структурированный ввод через интерактивные диалоги (v2.1.49+). Это позволяет MCP-серверу запросить дополнительную информацию в процессе работы - например, попросить подтверждение, предложить выбрать один из вариантов или заполнить обязательные поля, - делая взаимодействие с MCP-сервером более интерактивным.

Ограничение на описания и инструкции инструментов

Начиная с v2.1.84, Claude Code применяет лимит в 2 КБ на описания инструментов и инструкции в расчёте на один MCP-сервер. Это не даёт отдельным серверам занимать чрезмерно много контекста излишне многословными определениями инструментов, снижая раздувание контекста и сохраняя эффективность взаимодействия.

MCP Prompts как slash-команды

MCP-серверы могут предоставлять промпты, которые отображаются в Claude Code как slash-команды. Промпты доступны согласно следующему соглашению об именовании:

/mcp__<server>__<prompt>

Например, если сервер с именем github предоставляет prompt с названием review, его можно вызвать как /mcp__github__review.

Дедупликация серверов

Когда один и тот же MCP-сервер определён на нескольких уровнях (локальном, проектном, пользовательском), приоритет имеет локальная конфигурация. Это позволяет без конфликтов переопределять MCP-настройки уровня проекта или пользователя локальными.

Недавние исправления жизненного цикла (v2.1.136)

В v2.1.136 исправлены два давних бага жизненного цикла MCP - если вы используете конфигурации с несколькими серверами, ради этого стоит обновиться:

• MCP-серверы сохраняются после /clear: серверы, настроенные через .mcp.json, плагины или коннекторы claude.ai, больше не исчезают после /clear в VS Code, JetBrains и Agent SDK. Более ранние версии молча выгружали их, и требовался перезапуск.
• Исправлена гонка при одновременном обновлении OAuth refresh-token: в конфигурациях с несколькими OAuth-серверами refresh-токены больше не теряются, когда несколько серверов одновременно пытаются их обновить. Это устраняет ситуацию «каждое утро приходится заново авторизовываться», от которой страдали установки с несколькими MCP-серверами под OAuth.

MCP-ресурсы через @-упоминания

Вы можете ссылаться на MCP-ресурсы прямо в промптах, используя синтаксис @-упоминаний:

@server-name:protocol://resource/path

Например, чтобы сослаться на конкретный ресурс базы данных:

@database:postgres://mydb/users

Это позволяет Claude получать содержимое MCP-ресурсов и встраивать его непосредственно в контекст разговора.

Области действия MCP

Конфигурации MCP можно хранить в разных областях действия с различными уровнями общего доступа:

# Project scope - writes to .mcp.json so the team shares it
claude mcp add --scope project --transport http github https://api.github.com/mcp

# User scope - available in every project
claude mcp add --scope user --transport stdio memory -- npx @modelcontextprotocol/server-memory

Использование области проекта

Храните конфигурации MCP, специфичные для проекта, в файле .mcp.json:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp"
    }
  }
}

Участники команды при первом использовании MCP-серверов проекта увидят запрос на подтверждение. В недоверенном workspace серверы, которые репозиторий самостоятельно одобрил через закоммиченный .claude/settings.json, не запускаются автоматически командами claude mcp list/get - для них отображается ⏸ Pending approval, пока вы не подтвердите диалог доверия; параметр enableAllProjectMcpServers в недоверенной папке игнорируется (v2.1.196).

Управление конфигурацией MCP

Добавление MCP-серверов

# Add HTTP-based server
claude mcp add --transport http github https://api.github.com/mcp

# Add local stdio server
claude mcp add --transport stdio database -- npx @company/db-server

# List all MCP servers
claude mcp list

# Get details on specific server
claude mcp get github

# Remove an MCP server
claude mcp remove github

# Reset project-specific approval choices
claude mcp reset-project-choices

# Authenticate an MCP server from the CLI (v2.1.186+)
claude mcp login github

# Sign out of an MCP server (v2.1.186+)
claude mcp logout github

# Import from Claude Desktop
claude mcp add-from-claude-desktop

# Add a server from a JSON blob (useful for scripted setup)
claude mcp add-json events-server '{"type":"stdio","command":"npx","args":["@modelcontextprotocol/server-events"]}'

Примечание: В JSON-конфигурациях - .mcp.json, ~/.claude.json или claude mcp add-json - поле type принимает streamable-http как псевдоним для http. В спецификации MCP этот транспорт называется streamable-http, поэтому конфигурации, скопированные напрямую из документации сервера, работают без изменений.

Начиная с v2.1.238, команды claude mcp list и claude mcp get отображают отключённые серверы как ⊘ Disabled, не подключаясь к ним для проверки состояния.

claude mcp login <name> / claude mcp logout <name> - это неинтерактивный эквивалент OAuth-сценария из меню /mcp: вход и выход без его открытия. Добавьте флаг --no-browser к login, чтобы пройти OAuth по SSH или в headless-сессии (сценарий будет перенаправлен через stdin).

Таблица доступных MCP-серверов

Практические примеры

Пример 1: настройка GitHub MCP

Файл: .mcp.json (корень проекта)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Доступные инструменты GitHub MCP:

Управление Pull Request'ами

• list_prs - список всех PR в репозитории
• get_pr - получить детали PR, включая diff
• create_pr - создать новый PR
• update_pr - обновить описание/заголовок PR
• merge_pr - смерджить PR в основную ветку
• review_pr - добавить review-комментарии

Пример запроса:

/mcp__github__get_pr 456

# Returns:
Title: Add dark mode support
Author: @alice
Description: Implements dark theme using CSS variables
Status: OPEN
Reviewers: @bob, @charlie

Управление issues

• list_issues - список всех issues
• get_issue - получить сведения об issue
• create_issue - создать новый issue
• close_issue - закрыть issue
• add_comment - добавить комментарий к issue

Информация о репозитории

• get_repo_info - сведения о репозитории
• list_files - дерево файлов
• get_file_content - прочитать содержимое файла
• search_code - поиск по кодовой базе

Операции с commit

• list_commits - история commit'ов
• get_commit - сведения о конкретном commit
• create_commit - создать новый commit

Настройка:

export GITHUB_TOKEN="your_github_token"
# Or use the CLI to add directly:
claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github

Подстановка переменных окружения в конфигурации

Конфигурации MCP поддерживают подстановку переменных окружения со значениями по умолчанию. Синтаксис ${VAR} и ${VAR:-default} работает в следующих полях: command, args, env, url и headers.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}",
        "X-Custom-Header": "${CUSTOM_HEADER:-default-value}"
      }
    },
    "local-server": {
      "command": "${MCP_BIN_PATH:-npx}",
      "args": ["${MCP_PACKAGE:-@company/mcp-server}"],
      "env": {
        "DB_URL": "${DATABASE_URL:-postgresql://localhost/dev}"
      }
    }
  }
}

Переменные раскрываются во время выполнения:

• ${VAR} - использует переменную окружения; если она не задана, возвращает ошибку
• ${VAR:-default} - использует переменную окружения, а если она не задана, подставляет значение по умолчанию

Пример 2: настройка Database MCP

Конфигурация:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-database"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Пример использования:

User: Fetch all users with more than 10 orders

Claude: I'll query your database to find that information.

# Using MCP database tool:
SELECT u.*, COUNT(o.id) as order_count
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.id
HAVING COUNT(o.id) > 10
ORDER BY order_count DESC;

# Results:
- Alice: 15 orders
- Bob: 12 orders
- Charlie: 11 orders

Настройка:

export DATABASE_URL="postgresql://user:pass@localhost/mydb"
# Or use the CLI to add directly:
claude mcp add --transport stdio database -- npx @modelcontextprotocol/server-database

Пример 3: Workflow с несколькими MCP

Сценарий: ежедневная генерация отчётов

# Daily Report Workflow using Multiple MCPs

## Setup
1. GitHub MCP - fetch PR metrics
2. Database MCP - query sales data
3. Slack MCP - post report
4. Filesystem MCP - save report

## Workflow

### Step 1: Fetch GitHub Data
/mcp__github__list_prs completed:true last:7days

Output:
- Total PRs: 42
- Average merge time: 2.3 hours
- Review turnaround: 1.1 hours

### Step 2: Query Database
SELECT COUNT(*) as sales, SUM(amount) as revenue
FROM orders
WHERE created_at > NOW() - INTERVAL '1 day'

Output:
- Sales: 247
- Revenue: $12,450

### Step 3: Generate Report
Combine data into HTML report

### Step 4: Save to Filesystem
Write report.html to /reports/

### Step 5: Post to Slack
Send summary to #daily-reports channel

Final Output:
✅ Report generated and posted
📊 47 PRs merged this week
💰 $12,450 in daily sales

Настройка:

export GITHUB_TOKEN="your_github_token"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_TOKEN="your_slack_token"
# Add each MCP server via the CLI or configure them in .mcp.json

Пример 4: Операции MCP с файловой системой

Конфигурация:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/home/user/projects"]
    }
  }
}

Доступные операции:

# Use the CLI to add directly:
claude mcp add --transport stdio filesystem -- npx @modelcontextprotocol/server-filesystem /home/user/projects

MCP vs Memory: матрица выбора

Паттерн Request/Response

Переменные окружения

Храните конфиденциальные учётные данные в переменных окружения:

# ~/.bashrc or ~/.zshrc
export GITHUB_TOKEN="ghp_xxxxxxxxxxxxx"
export DATABASE_URL="postgresql://user:pass@localhost/mydb"
export SLACK_TOKEN="xoxb-xxxxxxxxxxxxx"

Затем укажите их в конфигурации MCP:

{
  "env": {
    "GITHUB_TOKEN": "${GITHUB_TOKEN}"
  }
}

Claude в роли MCP-сервера (claude mcp serve)

Claude Code сам может выступать в роли MCP-сервера для других приложений. Это позволяет внешним инструментам, редакторам и системам автоматизации использовать возможности Claude через стандартный протокол MCP.

# Start Claude Code as an MCP server on stdio
claude mcp serve

Затем другие приложения смогут подключаться к этому серверу так же, как к любому MCP-серверу на базе stdio. Например, чтобы добавить Claude Code в качестве MCP-сервера в другом экземпляре Claude Code:

claude mcp add --transport stdio claude-agent -- claude mcp serve

Это удобно для построения мультиагентных сценариев, в которых один экземпляр Claude оркестрирует другой.

Управляемая конфигурация MCP (Enterprise)

В корпоративных развёртываниях IT-администраторы задают политику MCP-серверов через два независимых механизма: файл managed-mcp.json, который разворачивает фиксированный набор серверов под исключительным контролем администратора, и ключи настроек allowedMcpServers / deniedMcpServers, которые фильтруют, какие из настроенных серверов допускаются к загрузке.

Расположение:

• macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
• Linux и WSL: /etc/claude-code/managed-mcp.json
• Windows: C:\Program Files\ClaudeCode\managed-mcp.json

managed-mcp.json использует тот же формат, что и проектный .mcp.json, - словарь mcpServers верхнего уровня. Он разворачивает серверы, а не фильтрует их:

{
  "mcpServers": {
    "example-remote": {
      "type": "http",
      "url": "https://mcp.example.com/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"]
    }
  }
}

Любой пользователь машины может прочитать этот файл, поэтому никогда не размещайте учётные данные в блоке env. Вместо этого используйте подстановку ${VAR}, OAuth или headersHelper.

Фильтрация: allowlist и denylist

allowedMcpServers, deniedMcpServers и allowAllClaudeAiMcps - это ключи настроек, а не поля managed-mcp.json. Чтобы они действительно применялись, разместите их в управляемом источнике настроек - server-managed settings, managed-settings.json, MDM-профиле или реестре:

• allowedMcpServers - allowlist разрешённых серверов. Задайте рядом allowManagedMcpServersOnly: true в том же управляемом источнике, иначе allowlist'ы объединяются из всех областей, и пользователь сможет расширить ваш.
• deniedMcpServers - denylist заблокированных серверов. Объединяется из всех областей в любом случае.
• allowAllClaudeAiMcps - загружает облачные коннекторы claude.ai вместе с развёрнутым managed-mcp.json (v2.1.149+). Считывается только из уровней политик, контролируемых администратором.

Каждая запись - это объект с единственным ключом:

{
  "allowedMcpServers": [
    { "serverUrl": "https://mcp.example.com/*" },
    { "serverCommand": ["/usr/local/bin/company-mcp-server", "--config", "/etc/company/mcp-config.json"] }
  ],
  "deniedMcpServers": [
    { "serverName": "untrusted-server" },
    { "serverUrl": "http://*" }
  ],
  "allowManagedMcpServersOnly": true
}

Третий управляемый параметр, managedMcpServers (v2.1.259+), позволяет организации предоставлять HTTP/SSE MCP-серверы всем пользователям. Записи имеют ту же структуру, что и в .mcp.json; записи, в которых указана команда для запуска, игнорируются.

Примечание: Если сервер одновременно подпадает под allowedMcpServers и deniedMcpServers, приоритет имеет правило запрета.

MCP-серверы, поставляемые плагинами

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

1. Отдельный .mcp.json - поместите файл .mcp.json в корневую директорию плагина
2. Inline в plugin.json - опишите MCP-серверы непосредственно в манифесте плагина

Используйте переменную ${CLAUDE_PLUGIN_ROOT}, чтобы указывать пути относительно директории установки плагина:

{
  "mcpServers": {
    "plugin-tools": {
      "command": "node",
      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/mcp-server.js"],
      "env": {
        "CONFIG_PATH": "${CLAUDE_PLUGIN_ROOT}/config.json"
      }
    }
  }
}

MCP с областью видимости на уровне субагента

MCP-серверы можно объявлять прямо во frontmatter агента через ключ mcpServers:, ограничивая их областью видимости конкретного субагента, а не всего проекта. Это удобно, когда агенту требуется доступ к определённому MCP-серверу, который не нужен остальным агентам в workflow.

---
mcpServers:
  my-tool:
    type: http
    url: https://my-tool.example.com/mcp
---

You are an agent with access to my-tool for specialized operations.

MCP-серверы, привязанные к области субагента, доступны только в контексте выполнения этого агента и не передаются родительскому или смежным агентам.

Ограничения на вывод MCP

Claude Code применяет ограничения на объём вывода MCP-инструментов, чтобы предотвратить переполнение контекста:

# Increase the max output to 50,000 tokens
export MAX_MCP_OUTPUT_TOKENS=50000

Автоматический перевод долгих вызовов инструментов в фон (v2.1.212)

Вызовы MCP-инструментов, выполняющиеся дольше 2 минут, теперь автоматически уходят в фон, благодаря чему сессия остаётся доступной для работы и не блокируется из-за медленного инструмента. Пороговое значение настраивается, а само поведение можно изменить или отключить через CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS:

# Change the auto-background threshold to 5 minutes (300,000ms)
export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=300000

Решение проблемы раздувания контекста через исполнение кода

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

Источник: Code Execution with MCP: Building More Efficient Agents - инженерный блог Anthropic

Проблема: два источника перерасхода токенов

1. Определения инструментов перегружают контекстное окно

Большинство MCP-клиентов загружают все определения инструментов заранее. При подключении к тысячам инструментов модели приходится обрабатывать сотни тысяч токенов ещё до того, как она прочитает запрос пользователя.

2. Промежуточные результаты расходуют дополнительные токены

Каждый промежуточный результат работы инструмента проходит через контекст модели. Возьмём перенос транскрипта встречи из Google Drive в Salesforce: полный текст проходит через контекст дважды - при чтении и при записи в целевую систему. Транскрипт двухчасовой встречи легко может добавить свыше 50 000 токенов.

Решение: MCP-инструменты как программные API

Вместо того чтобы прогонять описания инструментов и результаты их вызова через контекстное окно, агент пишет код, обращающийся к MCP-инструментам как к обычным API. Код исполняется в изолированной песочнице, а модели возвращается только итоговый результат.

Как это работает

Инструменты MCP представлены в виде файлового дерева типизированных функций:

servers/
├── google-drive/
│   ├── getDocument.ts
│   └── index.ts
├── salesforce/
│   ├── updateRecord.ts
│   └── index.ts
└── ...

Каждый файл инструмента содержит типизированную обёртку:

// ./servers/google-drive/getDocument.ts
import { callMCPTool } from "../../../client.js";

interface GetDocumentInput {
  documentId: string;
}

interface GetDocumentResponse {
  content: string;
}

export async function getDocument(
  input: GetDocumentInput
): Promise<GetDocumentResponse> {
  return callMCPTool<GetDocumentResponse>(
    'google_drive__get_document', input
  );
}

Затем агент пишет код, оркеструющий эти инструменты:

import * as gdrive from './servers/google-drive';
import * as salesforce from './servers/salesforce';

// Data flows directly between tools - never through the model
const transcript = (
  await gdrive.getDocument({ documentId: 'abc123' })
).content;

await salesforce.updateRecord({
  objectType: 'SalesMeeting',
  recordId: '00Q5f000001abcXYZ',
  data: { Notes: transcript }
});

Результат: расход токенов снижается с ~150 000 до ~2 000 - сокращение на 98,7%.

Ключевые преимущества

Пример: фильтрация больших наборов данных

// Without code execution - all 10,000 rows flow through context
// TOOL CALL: gdrive.getSheet(sheetId: 'abc123')
//   -> returns 10,000 rows in context

// With code execution - filter in the execution environment
const allRows = await gdrive.getSheet({ sheetId: 'abc123' });
const pendingOrders = allRows.filter(
  row => row["Status"] === 'pending'
);
console.log(`Found ${pendingOrders.length} pending orders`);
console.log(pendingOrders.slice(0, 5)); // Only 5 rows reach the model

Пример: цикл без обращений к модели

// Poll for a deployment notification - runs entirely in code
let found = false;
while (!found) {
  const messages = await slack.getChannelHistory({
    channel: 'C123456'
  });
  found = messages.some(
    m => m.text.includes('deployment complete')
  );
  if (!found) await new Promise(r => setTimeout(r, 5000));
}
console.log('Deployment notification received');

Компромиссы, которые стоит учитывать

Выполнение кода привносит собственную сложность. Запуск сгенерированного агентом кода требует:

• безопасной изолированной среды выполнения (sandbox) с адекватными лимитами ресурсов
• мониторинга и логирования выполняемого кода
• дополнительных накладных расходов на инфраструктуру по сравнению с прямыми вызовами tools

Преимущества - снижение расхода токенов, меньшая задержка, более удобная композиция tools - нужно взвешивать относительно этих издержек на реализацию. Для агентов всего с несколькими MCP-серверами прямые вызовы tools могут оказаться проще. Для агентов, работающих в большом масштабе (десятки серверов, сотни tools), выполнение кода даёт существенный выигрыш.

MCPorter: runtime для композиции MCP-инструментов

MCPorter - это TypeScript runtime и CLI-набор инструментов, который делает вызов MCP-серверов удобным на практике, без шаблонного кода, и помогает бороться с разрастанием контекста за счёт выборочного подключения tools и типизированных обёрток.

Какую задачу решает: вместо того чтобы заранее загружать все определения tools со всех MCP-серверов, MCPorter позволяет находить, инспектировать и вызывать конкретные tools по требованию - сохраняя контекст компактным.

Ключевые возможности:

npx mcporter list          # No install required - discover servers instantly
pnpm add mcporter          # Add to a project
brew install steipete/tap/mcporter  # macOS via Homebrew

Пример - композиция tools на TypeScript:

import { createRuntime, createServerProxy } from "mcporter";

const runtime = await createRuntime();
const gdrive = createServerProxy(runtime, "google-drive");
const salesforce = createServerProxy(runtime, "salesforce");

// Data flows between tools without passing through the model context
const doc = await gdrive.getDocument({ documentId: "abc123" });
await salesforce.updateRecord({
  objectType: "SalesMeeting",
  recordId: "00Q5f000001abcXYZ",
  data: { Notes: doc.text() }
});

Пример - вызов CLI-инструмента:

# Call a specific tool directly
npx mcporter call linear.create_comment issueId:ENG-123 body:'Looks good!'

# List available servers and tools
npx mcporter list

MCPorter дополняет описанный выше подход с выполнением кода, предоставляя runtime-инфраструктуру для вызова MCP-инструментов как типизированных API - благодаря этому легко удерживать промежуточные данные вне контекста модели.

Лучшие практики

Вопросы безопасности

Что делать ✅

• Используйте переменные окружения для всех учётных данных
• Регулярно ротируйте токены и API-ключи (рекомендуется ежемесячно)
• По возможности используйте токены только для чтения
• Ограничивайте область доступа MCP-сервера минимально необходимой
• Отслеживайте использование MCP-серверов и журналы доступа
• Используйте OAuth для внешних сервисов, когда это возможно
• Внедрите rate limiting для MCP-запросов
• Тестируйте MCP-подключения перед использованием в production
• Документируйте все активные MCP-подключения
• Поддерживайте пакеты MCP-серверов в актуальном состоянии

Чего не делать ❌

• Не хардкодьте учётные данные в конфигурационных файлах
• Не коммитьте токены и секреты в git
• Не передавайте токены в командных чатах и email
• Не используйте личные токены в командных проектах
• Не выдавайте лишних прав
• Не игнорируйте ошибки аутентификации
• Не выставляйте MCP-эндпоинты в публичный доступ
• Не запускайте MCP-серверы с правами root/администратора
• Не сохраняйте чувствительные данные в логах
• Не отключайте механизмы аутентификации

Лучшие практики конфигурирования

1. Version Control: храните .mcp.json в git, но для секретов используйте переменные окружения
2. Least Privilege: выдавайте каждому MCP-серверу минимально необходимые права
3. Isolation: по возможности запускайте разные MCP-серверы в отдельных процессах
4. Monitoring: логируйте все MCP-запросы и ошибки для аудита
5. Testing: тестируйте все конфигурации MCP перед развёртыванием в production

Советы по производительности

• Кэшируйте часто используемые данные на уровне приложения
• Формулируйте MCP-запросы точечно, чтобы сократить объём передаваемых данных
• Отслеживайте время отклика MCP-операций
• Предусмотрите rate limiting для внешних API
• Используйте батчинг при выполнении нескольких операций подряд

Инструкция по установке

Предварительные требования

• Установлены Node.js и npm
• Установлен Claude Code CLI
• API-токены/учётные данные для внешних сервисов

Пошаговая настройка

1. Добавьте свой первый MCP-сервер с помощью CLI (на примере GitHub):

claude mcp add --transport stdio github -- npx @modelcontextprotocol/server-github

Или создайте файл .mcp.json в корне проекта:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

2. Задайте переменные окружения:

export GITHUB_TOKEN="your_github_personal_access_token"

3. Проверьте подключение:

claude /mcp

4. Используйте инструменты MCP:

/mcp__github__list_prs
/mcp__github__create_issue "Title" "Description"

Установка для конкретных сервисов

GitHub MCP:

npm install -g @modelcontextprotocol/server-github

MCP для баз данных:

npm install -g @modelcontextprotocol/server-database

Filesystem MCP:

npm install -g @modelcontextprotocol/server-filesystem

Slack MCP:

npm install -g @modelcontextprotocol/server-slack

Устранение неполадок

Начните с текста ошибки (v2.1.219+)

Если сервер не подключается, сначала запустите claude mcp list (или /mcp внутри сессии), прежде чем что-либо менять. Claude Code теперь выводит HTTP-код ответа и текст ошибки от сервера рядом с проблемным сервером, так что вы увидите 401 Unauthorized или 404 Not Found вместо обобщённого «failed to connect»:

# Shows connection status plus HTTP status and error text for failures
claude mcp list

Сначала посмотрите на статус - он подскажет, какое исправление применить:

• 401 / 403 → неверные или просроченные учётные данные; выполните повторную аутентификацию командой claude mcp login <name>
• 404 → неверный URL (обычная причина - отсутствующий суффикс пути /mcp или /sse)
• 5xx / timeout → удалённый сервер недоступен; см. Тайм-аут соединения

Скрытые пробельные символы в значениях конфигурации (v2.1.219+)

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

Если вы видите такое предупреждение, перепроверьте значение в .mcp.json (или переменную окружения, из которой оно подставляется) и уберите лишние пробелы:

# Reveals hidden leading/trailing whitespace between the delimiters
printf '[%s]\n' "$GITHUB_TOKEN"

Пропуск серверов в headless-запусках (v2.1.219+)

Серверы, переданные через --mcp-config и не прошедшие валидацию конфигурации, теперь пропускаются, а не прерывают запуск целиком - из-за этого headless-скрипт может казаться работоспособным, лишившись при этом половины инструментов. Claude Code теперь сообщает, какие серверы были отброшены:

• Headless-запуски / запуски с -p: событие init в stream-json содержит поле mcp_server_errors со списком всех пропущенных записей. Проверяйте его, прежде чем полагаться на результат запуска.
• Интерактивные запуски в терминале: о той же проблеме сообщается предупреждением при старте сессии.

# Inspect skipped --mcp-config entries in a headless run
claude -p "list my tools" --mcp-config ./servers.json \
  --output-format stream-json --verbose \
  | jq -r 'select(.type == "system" and .subtype == "init") | .mcp_server_errors'

MCP-сервер не найден

# Verify MCP server is installed
npm list -g @modelcontextprotocol/server-github

# Install if missing
npm install -g @modelcontextprotocol/server-github

Ошибка аутентификации

# Verify environment variable is set
echo $GITHUB_TOKEN

# Re-export if needed
export GITHUB_TOKEN="your_token"

# Verify token has correct permissions
# Check GitHub token scopes at: https://github.com/settings/tokens

Тайм-аут подключения

• Проверьте сетевое соединение: ping api.github.com
• Убедитесь, что endpoint API доступен
• Проверьте лимиты запросов (rate limits) к API
• Попробуйте увеличить timeout в конфигурации
• Проверьте, не блокирует ли соединение firewall или proxy

Сбои MCP-сервера

• Проверьте логи MCP-сервера: ~/.claude/logs/
• Убедитесь, что все переменные окружения заданы
• Проверьте корректность прав доступа к файлам
• Попробуйте переустановить пакет MCP-сервера
• Проверьте, нет ли других процессов, занимающих тот же порт

Связанные концепции

Memory vs MCP

• Memory: хранит постоянные, неизменяемые данные (настройки, контекст, историю)
• MCP: обращается к динамическим, изменяющимся данным (API, базы данных, сервисы реального времени)

Когда что использовать

• Memory - для пользовательских настроек, истории диалогов, накопленного контекста
• MCP - для актуальных issues в GitHub, живых запросов к БД, данных в реальном времени

Интеграция с другими возможностями Claude

• Комбинируйте MCP с Memory, чтобы получить богатый контекст
• Используйте MCP-инструменты в промптах для более качественного reasoning
• Задействуйте несколько MCP-серверов для сложных workflow

Дополнительные материалы

• Официальная документация MCP
• Спецификация протокола MCP
• Репозиторий MCP на GitHub
• Доступные MCP-серверы
• MCPorter - TypeScript runtime и CLI для вызова MCP-серверов без boilerplate-кода
• Code Execution with MCP - статья в инженерном блоге Anthropic о решении проблемы раздувания контекста
• Справочник Claude Code CLI
• Документация Claude API

Последнее обновление: 6 сентября 2026 Версия Claude Code: 2.1.263 Источники:

• https://code.claude.com/docs/en/mcp
• https://code.claude.com/docs/en/managed-mcp
• https://code.claude.com/docs/en/changelog
• https://github.com/anthropics/claude-code/releases/tag/v2.1.117
• https://github.com/anthropics/claude-code/releases/tag/v2.1.139
• https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
• https://code.claude.com/docs/en/model-config Совместимые модели: Claude Fable 5, Claude Opus 5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 4.5