MCP (Model Context Protocol)

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

Обзор

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

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

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

Архитектура 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=<абсолютный путь к корню репозитория> - по тому же соглашению, что и для hooks. В плагинных и проектных файлах .mcp.json можно ссылаться на ${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

Рабочие каталоги сессии (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

Переопределение discovery метаданных OAuth

Если ваш MCP server возвращает ошибки на стандартном endpoint метаданных OAuth (/.well-known/oauth-authorization-server), но при этом предоставляет рабочий OIDC endpoint, вы можете указать Claude Code получать метаданные OAuth с определённого URL. Задайте 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. Учётные данные обновляются на лету без ручного переподключения. См. Использование динамических заголовков для пользовательской аутентификации.

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-промпты как slash-команды

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

/mcp__<server>__<prompt>

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

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

Когда один и тот же MCP-сервер определён на нескольких уровнях (local, project, user), приоритет имеет локальная конфигурация. Это позволяет без конфликтов переопределять настройки 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 token, когда несколько серверов одновременно пытаются его обновить. Это устраняет ситуацию «каждое утро приходится заново авторизовываться», с которой сталкивались пользователи с несколькими MCP-серверами под защитой OAuth.

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

Ссылаться на MCP-ресурсы прямо в prompt можно с помощью синтаксиса упоминаний через @:

@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. В недоверенной рабочей области серверы, самоодобренные репозиторием через закоммиченный .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, поэтому конфигурации, скопированные из документации самого сервера, работают без изменений.

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 в ветку main
• review_pr - добавить комментарии к ревью

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

/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 - поиск по кодовой базе

Операции с commits

• list_commits - история commits
• 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 поддерживают подстановку переменных окружения со значениями по умолчанию в качестве fallback. Синтаксис ${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. Настройка 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: рабочий процесс с несколькими 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

Текущая дата: вторник, 4 августа 2026 г.

Настройка: </query>

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"]
    }
  }
}

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

Настройка: </query>

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

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

Шаблон «запрос/ответ»

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

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

# ~/.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. Этот файл обеспечивает исключительный контроль над тем, какие MCP-серверы разрешены или заблокированы в рамках всей организации.

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

• macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
• Linux: ~/.config/ClaudeCode/managed-mcp.json
• Windows: %APPDATA%\ClaudeCode\managed-mcp.json

Возможности:

• allowedMcpServers - белый список разрешённых серверов
• deniedMcpServers - чёрный список запрещённых серверов
• allowAllClaudeAiMcps - управляемая настройка, разрешающая загрузку облачных MCP-коннекторов claude.ai в рамках всей организации (v2.1.149+)
• Поддержка сопоставления по имени сервера, команде и URL-шаблонам
• Политики MCP уровня организации применяются раньше пользовательской конфигурации
• Предотвращает несанкционированные подключения к серверам

Пример конфигурации:

{
  "allowedMcpServers": [
    {
      "serverName": "github",
      "serverUrl": "https://api.github.com/mcp"
    },
    {
      "serverName": "company-internal",
      "serverCommand": "company-mcp-server"
    }
  ],
  "deniedMcpServers": [
    {
      "serverName": "untrusted-*"
    },
    {
      "serverUrl": "http://*"
    }
  ]
}

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

MCP-серверы из состава плагина

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

1. Отдельный файл .mcp.json - поместите файл .mcp.json в корневой каталог плагина.
2. Встроенное описание в 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-серверу, который не требуется остальным агентам в рабочем процессе.

---
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-серверы, привязанные к области subagent, доступны только в контексте выполнения этого агента и не разделяются с родительским или родственными агентами.

Ограничения на вывод 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 Engineering Blog

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

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

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

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

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

Решение: MCP-инструменты как code 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) с соответствующими лимитами ресурсов
• Мониторинга и логирования выполняемого кода
• Дополнительных накладных расходов на инфраструктуру по сравнению с прямыми вызовами инструментов

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

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

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

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

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

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

Пример - композиция инструментов на 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 endpoints в публичный доступ
• Не запускайте MCP-серверы с правами root/admin
• Не кэшируйте чувствительные данные в логах
• Не отключайте механизмы аутентификации

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

1. Version Control: держите .mcp.json в git, но используйте переменные окружения для секретов
2. Least Privilege: выдавайте каждому MCP-серверу минимально необходимые права
3. Изоляция: по возможности запускайте разные MCP-серверы в отдельных процессах
4. Мониторинг: логируйте все MCP-запросы и ошибки для аудита
5. Тестирование: проверяйте все 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

Database 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-код ответа и текст ошибки от сервера рядом со сбойным сервером, так что вместо общего «failed to connect» вы увидите 401 Unauthorized или 404 Not Found:

# 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
• Убедитесь, что API endpoint доступен
• Проверьте rate limits API
• Попробуйте увеличить timeout в конфигурации
• Проверьте, не блокируют ли соединение firewall или proxy

Падения MCP-сервера

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

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

Memory и MCP

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

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

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

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

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

Дополнительные ресурсы

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

Последнее обновление: 4 августа 2026 Версия Claude Code: 2.1.220 Источники:

• https://code.claude.com/docs/en/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