Использование MCP-серверов с SDK GitHub Copilot

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

В этой статье

Примечание.

Это развивающаяся функция. См. выпуск #36 для дальнейшего обсуждения.

Что такое MCP?

Протокол контекста модели (MCP) — это открытый стандарт для подключения ассистентов ИИ к внешним инструментам и источникам данных. MCP-серверы могут:

  • Выполните код или скрипты
  • Базы данных запросов
  • Файловые системы доступа
  • Вызов внешних API
  • И многое другое

Типы серверов

SDK поддерживает два типа MCP-серверов:

TypeОписаниеВариант использования
Local/StdioРаботает как подпроцесс, общается через stdin/stdoutЛокальные инструменты, доступ к файлам, пользовательские скрипты
HTTP/SSEУдалённый сервер с доступом через HTTPОбщие сервисы, облачные инструменты

Configuration

Проверка конфигурации и жизненного цикла

session.rpc.mcp.listConfigured() — это безпараметров, пассивное чтение инвентаризации. Он не запускает или перезапускает серверы, проверяет подлинность, применяет политику песочницы или ожидает запуска сервера. Обнаружение конфигурации и фильтрация политик определяют, какие серверы отображаются и их enabled значения.

Для этого экспериментального RPC требуется выровненный выпуск пакета SDK или среды выполнения. Его более ранний предварительный ответ может live быть опущен; Пакеты SDK, использующие требуемый контракт жизненного цикла, не поддерживают более раннюю фигуру ответа. При предоставлении внешней среды выполнения обновите его вместе с пакетом SDK. Общая версия протокола не изменяется и не определяет эту экспериментальную редакцию контракта.

Каждая запись включает в себя live.status. Настроенный сервер без материализованного сервера среды выполнения сообщает о существующем not_configured состоянии даже в том trueслучаеenabled. Сервер среды выполнения, который был явно остановлен отчетами stopped. Материализованные серверы сообщают о фактическом жизненном цикле, включая pending, needs-auth``connectedиfailed; сбои, включаются live.error при наличии.

Конфигурация и жизненный цикл описывают различные факты. Если URL-адрес сервера, проверка подлинности или источник конфигурации изменяется, пока старое подключение остается в живых, инвентаризация по-прежнему сообщает о фактическом жизненном цикле подключения. Состояние connected не означает, что применена последняя конфигурация. Среда выполнения владеет этим наблюдением; клиенты не должны заменять кэшированное состояние только на имя сервера.

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

Только имя startServer или разрешает и restartServer инициализирует только запрошенный сервер после возобновления холодного сеанса без первого вызова list. Это включает конфигурации пользователей и подключаемых модулей и встроенный сервер GitHub, настроенный с помощьюgithubMcpToolConfig. Он не запускает другие настроенные серверы или переопределяет отключенное состояние, требования к проверке подлинности, политику песочницы или приоритет источника конфигурации.

Node.js / TypeScript

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const session = await client.createSession({
    model: "gpt-5",
    mcpServers: {
        // Local MCP server (stdio)
        "my-local-server": {
            type: "local",
            command: "node",
            args: ["./mcp-server.js"],
            env: { DEBUG: "true" },
            cwd: "./servers",
            tools: ["*"],  // "*" = all tools, [] = none, or list specific tools
            timeout: 30000,
        },
        // Remote MCP server (HTTP)
        "github": {
            type: "http",
            url: "https://api.githubcopilot.com/mcp/",
            headers: { "Authorization": "Bearer ${TOKEN}" },
            tools: ["*"],
        },
    },
});

Python

import asyncio
from copilot import CopilotClient
from copilot.session import PermissionHandler

async def main():
    client = CopilotClient()
    await client.start()

    session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5", mcp_servers={
        # Local MCP server (stdio)
        "my-local-server": {
            "type": "local",
            "command": "python",
            "args": ["./mcp_server.py"],
            "env": {"DEBUG": "true"},
            "cwd": "./servers",
            "tools": ["*"],
            "timeout": 30000,
        },
        # Remote MCP server (HTTP)
        "github": {
            "type": "http",
            "url": "https://api.githubcopilot.com/mcp/",
            "headers": {"Authorization": "Bearer ${TOKEN}"},
            "tools": ["*"],
        },
    })

    response = await session.send_and_wait("List my recent GitHub notifications")
    print(response.data.content)

    await client.stop()

asyncio.run(main())

Go

package main

import (
    "context"
    "log"
    copilot "github.com/github/copilot-sdk/go"
)

func main() {
    ctx := context.Background()
    client := copilot.NewClient(nil)
    if err := client.Start(ctx); err != nil {
        log.Fatal(err)
    }
    defer client.Stop()

    session, err := client.CreateSession(ctx, &copilot.SessionConfig{
        Model: "gpt-5",
        MCPServers: map[string]copilot.MCPServerConfig{
            "my-local-server": copilot.MCPStdioServerConfig{
                Command: "node",
                Args:    []string{"./mcp-server.js"},
                Tools:   []string{"*"},
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    defer session.Disconnect()

    // Use the session...
}

.NET

using GitHub.Copilot;

await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-5",
    McpServers = new Dictionary<string, McpServerConfig>
    {
        ["my-local-server"] = new McpStdioServerConfig
        {
            Command = "node",
            Args = new List<string> { "./mcp-server.js" },
            Tools = new List<string> { "*" },
        },
    },
});

Отключение настроенных серверов на сеанс

Задайте disabledMcpServers точные имена серверов MCP, которые не должны выполняться в сеансе. Параметр ограничен отдельным запросом на создание или возобновление работы; Он не изменяет глобальные параметры MCP или конфигурацию сервера.

const session = await client.createSession({
    mcpServers: {
        filesystem: { type: "local", command: "npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "."] },
        github: { type: "http", url: "https://api.githubcopilot.com/mcp/" },
    },
    disabledMcpServers: ["github"],
});
SDKСвойство конфигурации
Node.jsdisabledMcpServers
Pythondisabled_mcp_servers
GoDisabledMCPServers
.NETDisabledMcpServers
JavasetDisabledMcpServers(...)
Rustwith_disabled_mcp_servers(...)

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

Перечисление и получение запросов

Экспериментальное пространство имен MCP предоставляет проводные JSON-RPC методы session.mcp.prompts.list и session.mcp.prompts.get. Используйте приведенные ниже методы доступа к пакету SDK для конкретного языка, чтобы вызвать их. Эти методы предназначены для одного подключенного сервера в текущем сеансе; Они не объединяют результаты из нескольких серверов.

SDKВывод списка запросовПолучение запроса
Node.jssession.rpc.mcp.prompts.list(...)session.rpc.mcp.prompts.get(...)
Pythonsession.rpc.mcp.prompts.list(...)session.rpc.mcp.prompts.get(...)
Gosession.RPC.MCP.Prompts().List(...)session.RPC.MCP.Prompts().Get(...)
.NETsession.Rpc.Mcp.Prompts.ListAsync(...)session.Rpc.Mcp.Prompts.GetAsync(...)
Javasession.getRpc().mcp.prompts.list(...)session.getRpc().mcp.prompts.get(...)
Rustsession.rpc().mcp().prompts().list(...)session.rpc().mcp().prompts().get(...)

Для перечисления требуется serverName и принимается необязательный непрозрачный cursorкод. Каждый вызов возвращает одну страницу типизированных определений запроса и необязательный nextCursor. Передайте этот курсор в другой вызов списка, чтобы запросить следующую страницу. Определения включают имена, необязательные названия и описания, а также определения аргументов. Пропущенный флаг аргумента required по-прежнему отличается от false.

Получение запроса требуется serverName и promptNameс необязательным arguments словарем, значения которого являются строками. Опущение arguments оставляет аргументы запроса MCP отсутствующими; передача {} отправляет явно пустой словарь. Среда выполнения сохраняет это различие для сервера. Результат содержит необязательное описание и упорядоченные сообщения с типизированными ролями и непрозрачными JSON content. Перед интерпретацией каждого блока содержимого type проверьте содержимое; содержимое не преобразуется в текст. Вложенные ресурсы, заметки, метаданные, незнакомые типы контента и дополнительные поля содержимого сохраняют свою структуру JSON. Расширения сервера для типизированных дескрипторов, сообщений и конвертов результатов доступны в additionalPropertiesразделе . Само имя additionalProperties расширения сервера сохраняется как запись внутри этой карты, а не объединяется в нее. Дискриминатор верхнего уровня resultType: "complete" протокола используется средой выполнения; он не возвращается в качестве поля пакета SDK или расширения сервера. Запросы завершаются явным образом, если среда выполнения не может сохранить необработанный ответ, включая кадры ответа stdio, превышающие ограничение записи 1 MiB.

Возвращенные сообщения запроса не отправляются в модель или используются для выполнения инструментов или получения ссылочных ресурсов. Приложение решает, как использовать результат. При создании этого результата сервер MCP может запрашивать выборку или получение с помощью нескольких продолжений кругового пути. Эти запросы используют те же настроенные ответы узла, что и другие операции MCP; Запрос запроса не предоставляет дополнительного разрешения или обход решения узла. Ошибка отсутствующих ответов или респондентов завершается сбоем запроса, а отклонение с получением снимка возвращается серверу без изменений. Продолжения только для состояния не вызывают ни одного ответа.

После существующего mcp.prompts.list_changed события сеанса переведите список запросов именованного сервера, чтобы обновить представление приложения.

Применение политики песочницы перед запуском MCP

createSession resumeSession Перед началом разработки перед sandboxConfig обнаружением корневой конфигурации, подключаемым модулем или явно настроенным сервером MCP перед применением политики песочницы. Он принимает ту же конфигурацию, что session.rpc.options.update({ sandboxConfig })и .

const sandboxConfig = {
    enabled: true,
    sandboxMcpServers: true,
    userPolicy: { network: { allowOutbound: false } },
};
const session = await client.createSession({
    onPermissionRequest: approveAll,
    sandboxConfig,
});

Повторно укажите конфигурацию при холодном возобновлении; бездействие сохраняет текущую политику сеанса резидента. Возобновление резидентного возобновления не может отменить уже запущенные процессы. Проверка управляемой политики использует ту же семантику прямого узла, что и обновление параметров: конфликтующий запрос завершается ошибкой создания или возобновления, а не возвращается к незавернутому сеансу, при data.code этом задано значение managed_sandbox_policy_conflict в ошибке JSON-RPC. Среда выполнения не назначает параметры, производные sandboxConfigSource от этой явной конфигурации узла.

Позже идентичный options.update({ sandboxConfig }) не перезапускает серверы MCP, в том числе при нормализации управляемой политики. Другая эффективная политика песочницы MCP сохраняет обычное поведение перезапуска.

Проверьте среду выполнения version , возвращаемую server.connect (ConnectResult) с минимальным выпуском среды выполнения, который требуется приложению для этой функции. Версия протокола SDK не является сигналом для каждой функции. Старые среды выполнения игнорируют неизвестные поля создания и возобновления, поэтому приложение, поддерживающее их, может отправлять sandboxConfig при открытии и повторять его в обновлении дополнительных параметров. Это обновление безвредно в вспомогательных средах выполнения, но старые среды выполнения по-прежнему могут запускать MCP до поступления обновления; требовать поддерживаемую версию среды выполнения, если ограничение от первого процесса является обязательным.

Настройка средства

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

Разрешить все инструменты

Используйте "*" для включения всех инструментов, предоставляемых сервером MCP:

tools: ["*"]

Разрешите определённые инструменты

Предоставьте список имён инструментов для ограничения доступа:

tools: ["bash", "edit"]

Агенту будут доступны только указанные инструменты.

Отключите все инструменты

Используйте пустой массив для отключения всех инструментов:

tools: []

Notes

  • Это tools поле определяет, какие инструменты разрешены.
  • Отдельного allow или disallow конфигурационного устройства нет — доступ к инструменту контролируется напрямую через этот список.

Быстрый старт: сервер файловой системы MCP

Вот полный рабочий пример с использованием официального @modelcontextprotocol/server-filesystem сервера MCP:

import { CopilotClient } from "@github/copilot-sdk";

async function main() {
    const client = new CopilotClient();

    // Create session with filesystem MCP server
    const session = await client.createSession({
        mcpServers: {
            filesystem: {
                type: "local",
                command: "npx",
                args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
                tools: ["*"],
            },
        },
    });

    console.log("Session created:", session.sessionId);

    // The model can now use filesystem tools
    const result = await session.sendAndWait({
        prompt: "List the files in the allowed directory",
    });

    console.log("Response:", result?.data?.content);

    await session.disconnect();
    await client.stop();
}

main();

Output:

Session created: 18b3482b-bcba-40ba-9f02-ad2ac949a59a
Response: The allowed directory is `/tmp`, which contains various files
and subdirectories including temporary system files, log files, and
directories for different applications.

Совет

Вы можете использовать любой MCP-сервер из каталога MCP Servers. Популярные варианты включают @modelcontextprotocol/server-github, @modelcontextprotocol/server-sqliteи @modelcontextprotocol/server-puppeteer.

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

Локальный/stdio сервер

PropertyTypeОбязательныйОписание
type
"local" или "stdio"НетТип сервера (по умолчанию локальный)
commandstringДаКоманда для выполнения
argsstring[]ДаАргументы команд
envobjectНетПеременные среды
cwdstringНетРабочий каталог
toolsstring[]НетИнструменты для включения (["*"] для всех, [] для никого)
timeoutnumberНетТайм-аут в миллисекундах

Удалённый сервер (HTTP/SSE)

PropertyTypeОбязательныйОписание
type
"http" или "sse"ДаТип сервера
urlstringДаURL-адрес сервера
headersobjectНетHTTP-заголовки (например, для аутентификации)
oauthClientIdstringНетНепустый идентификатор клиента для статического настроенного клиента OAuth
oauthScopesstring[]НетНепустый массив допустимых маркеров области RFC 6749. Требуется oauthClientId; используется, если область вызова сервера не указана или предоставляет пустую область, прежде чем резервные метаданные защищенного ресурса
oauthPublicClientbooleanНетЯвляется ли настроенный клиент OAuth общедоступным и не требует секрета клиента.
oauthGrantTypestringНетТип предоставления OAuth для настроенного клиента, например client_credentials
toolsstring[]НетИнструменты для включения
timeoutnumberНетТайм-аут в миллисекундах

Владение OAuth для удаленных серверов

Выберите одну модель владения OAuth для каждой попытки проверки подлинности:

  1. Обратный цикл, управляемый средой выполнения: вызов session.mcp.oauth.login без URI перенаправления. Среда выполнения открывает локальный прослушиватель обратного вызова и владеет обнаружением, PKCE, проверкой состояния, обменом маркерами, сохраняемостью, обновлением и повторном подключением.
  2. Обратный вызов, управляемый средой выполнения: вызов session.mcp.oauth.login с доверенным общедоступным URI перенаправления HTTPS. Узел получает обратный вызов, но среда выполнения продолжает принадлежать протоколу OAuth и учетным данным.
  3. Управляемый узлом OAuth: используйте обработчик запроса проверки подлинности MCP пакета SDK и верните маркер доступа, приобретенный на узле. Узел владеет авторизацией и обновлением.

Не регистрируйте обработчик OAuth, управляемый узлом, для попытки проверки подлинности, которая использует обратный вызов, управляемый средой выполнения. Подождите, пока удаленный сервер не войдет в needs-auth состояние, а затем вызовите созданный session.rpc.mcp.oauth.login метод непосредственно с именем сервера и URI обратного вызова:

{
    "serverName": "remote-mcp",
    "redirectUri": "https://agent.example.com/oauth/callback"
}

Выбранный статический, CIMD или динамически зарегистрированный клиент OAuth должен объявлять точный универсальный код ресурса (URI). Универсальный код ресурса (URI) должен использовать ПРОТОКОЛ HTTPS и не должен содержать запрос или фрагмент. Если требуется взаимодействие с браузером authorizationUrl , результат содержит и authorizationId. Откройте authorizationUrl в браузере пользователя и сохраните authorizationId его в целевом сеансе.

После перенаправления сервера авторизации на конечную точку вызовите созданный session.rpc.mcp.oauth.complete метод:

{
    "authorizationId": "<opaque-state>",
    "callbackUrl": "https://agent.example.com/oauth/callback?code=...&state=..."
}

Создание callbackUrl из настроенного источника общедоступного перенаправления и пути, а также исходного запроса обратного вызова. Не передайте URL-адрес внутренней службы или url-адрес доверия, предоставленный Forwarded клиентом или X-Forwarded-* заголовками. Среда выполнения проверяет источник, порт, путь, состояние и ответ OAuth перед приемом доставки. Обмен маркерами, сохраняемость и повторное подключение MCP затем продолжают асинхронно.

Передача маркера доступа отклоненного обратно в среду выполнения

Для запроса OAuth узла и reason: "refresh"``runtimeRefreshSupported: trueобработчик может вернуться { "kind": "runtimeRefresh" } вместо получения маркера доступа на замену. Среда выполнения выполняет неинтерактивное продление с помощью существующего сохраненного гранта внутри исходной операции авторизации. Он не запускает новый поток согласия или не вызывает независимый authenticationStateChanged RPC обновления. Замена сохраняет свой сохраненный прованс гранта, поэтому более поздние области внедрения хранимых маркеров остаются доступными. Маркер, предоставленный непосредственно узлом, не помечен как сохраненный маркер и не может быть перезаписан этим путем внедрения.

Возвращается только этот ответ, когда ожидающий запрос объявляет поддержку. Отсутствующие возможности являются ложными и сохраняют устаревший контракт токена или отмены. Если обработчик возвращает передачу запроса без возможности, пакет SDK отправляет cancelled вместо этого, поэтому ожидающий запрос не остается открытым. Предоставленный маркер имеет приоритет над раздаткой, и отмена остается отменой.

SDKCapabilityРезультат передачи
Node.jsrequest.runtimeRefreshSupported{ kind: "runtimeRefresh" }
Pythonrequest["runtimeRefreshSupported"]{"kind": "runtimeRefresh"}
Go
MCPAuthRuntimeRefreshHandler аргумент возможностейMCPAuthResultRuntimeRefresh()
.NETMcpAuthContext.RuntimeRefreshSupportedMcpAuthResult.RefreshInRuntime()
Java
McpAuthHandler.handleWithRuntimeRefresh аргумент возможностейMcpAuthResponse.runtimeRefresh()
RustMcpAuthHandler::handle_with_runtime_refreshMcpAuthResponse::RuntimeRefresh

Принятие ответа подтверждает передачу, а не обновление, повторное подключение или завершение средства. Для принятой передачи создается один раз, mcp.oauth_completed когда исходное резервирование авторизации достигает результата терминала. Он outcome использует только существующие значения: token при успешном восстановлении, а cancelled также при отмене или сбое. Сохраняемое mcp.oauth_recovery_completed событие имеет то же самое requestId и serverName различает результат терминала, включая повторное подключение: succeeded, cancelledили failed. Версии ПАКЕТА SDK, предшествующие этому событию, получают его как неизвестный тип события.

Пока среда выполнения не примет runtimeRefresh ответ, существующие ответы сохраняют свое предыдущее значение. Ответ узла { kind: "cancelled" } отклоняет запрос. refresh Для запроса среда выполнения может запросить повторную проверку подлинности. Если узел не отвечает, среда выполнения возвращается к обычной локальной обработке OAuth, включая кэшированные учетные данные, и не mcp.oauth_recovery_completed выдает события. Это изменение не переклассифицирует ответ узла cancelled как stop. Исходный вызов сохраняется только с помощью принятой runtimeRefresh передачи.

После принятия исходное вызов может повториться после установки учетных данных и повторно подключить существующий сеанс, конфигурацию, политику и ограждения разрешений. Остановка основного поворота или завершение сеанса отменяет исходное резервирование авторизации; Остановленное вызов не может позже повторить или опубликовать результат. Уже выданный обмен вращающимся предоставлением может завершить сохранение замены после отмены, но не может установить устаревшие учетные данные, повторно подключиться или возобновить отмененное вызов.

Недоступное сохраненное предоставление или сбой обновления завершает исходное вызов без запроса интерактивной повторной проверки подлинности. Сбой повторного подключения также завершает вызов; Успешное получение маркера не является успешным результатом средства.

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

Крайние сроки OAuth HTTP применяются к отдельным запросам, а не к полному разрешению на передачу или предоставление хранилища. Отмена может вернуться до того, как выданный обмен поселится, и удаление сеансов ожидает отслеживаемых работников поселений. Общий срок урегулирования отсутствует, поэтому узлы не должны рассматривать отмену, принятие передачи или время ожидания HTTP в качестве доказательства завершения работы хранилища.

Диагностика MCP с областью действия сеанса

Задайте для diagnostics: { sources: { mcp: { level: "debug" } } } создания или возобновления сеанса, чтобы принять участие в диагностике MCP. Каждое исходное offзначение по умолчанию. Уровни поддержкиerror: , warning, info``debugи trace. Этот параметр отличается от уровня logLevelпроцесса клиента.

Предупреждение

Записи диагностики могут содержать содержимое, предоставленное пользователем или сервером, на каждом уровне включено: warning и выше может включать stderr сервера, а debug``trace также также может включать полезные данные MCP, аргументы инструментов и пути. Рассматривайте каждую запись как конфиденциальную. Не загружайте записи в виде телеметрии или не экспортируйте их без преднамеренных действий узла.

Созданный session.rpc.diagnostics API позволяет узлам настраивать и читать области сеанса, привязанные к диагностике в памяти. MCP является первым и в настоящее время поддерживается только источником. Явно выберите его при sources: ["mcp"] чтении; чтение не включает запись. Используйте один остановляемый цикл чтения для каждой выходной поверхности и сохраните его курсор. Цикл чтения владеет курсором и презентацией; Среда выполнения владеет записью, фильтрацией, хранением, истечением срока действия курсора и пробуждением.

import { approveAll, CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
const stop = new AbortController();
const appendLine = (line: string) => console.log(line);

await client.start();
const session = await client.createSession({
    onPermissionRequest: approveAll,
    diagnostics: { sources: { mcp: { level: "debug" } } },
});

try {
    let cursor: string | undefined;
    while (!stop.signal.aborted) {
        const page = await session.rpc.diagnostics.read({
            sources: ["mcp"],
            cursor,
            max: 100,
            waitMs: 30_000,
        });
        if (page.cursorStatus === "expired") {
            appendLine("MCP diagnostic entries were dropped.");
        }
        for (const entry of page.entries) {
            const detail = entry.details.data ? ` ${entry.details.data}` : "";
            appendLine(
                `${entry.timestamp} [${entry.level}] [${entry.source}:${entry.details.serverName}] ${entry.message}${detail}`,
            );
        }
        cursor = page.cursor;
    }
} finally {
    await session.disconnect();
    await client.stop();
}

Сигнал прерывания останавливает цикл после завершения текущего ограниченного чтения; Он не передается в вызов RPC. Отключение записи вызывает выдающееся чтение.

Запуск MCP отложен: включение или чтение диагностики не запускает сервер. Настройте mcpServers при создании сеанса, а затем обычно используйте сеанс или вызов session.rpc.mcp.startServer({ serverName }) установленного сервера для устранения неполадок инициализации без выполнения запроса модели.

У каждой записи есть source: "mcp"метка времени, серьезность, сообщение и необязательно agentId для агентов, не являющихся корневыми. Типизированный details содержит жизненный цикл, протокол, http или stderr категории, имя сервера, свежий connectionId для каждой попытки подключения, а также дополнительное направление протокола и диагностические данные. Срок хранения MCP ограничен 1024 записями и 4 МиБ на сеанс. Отдельные закодированные записи ограничены 16 КИБ и переносятся truncated при сокращении. Считывает по умолчанию 100 записей, принимает не более 500 и не использует данные других читателей. Используйте droppedCount, когда он присутствует на просроченной курсоре, чтобы показать известную потерю. Каждое успешное чтение возвращает состояние курсора и курсора, включая пустые операции чтения. Сохраняйте возвращенный курсор даже при отсутствии записей. Курсор принадлежит к его исходному выбору; запустите без курсора при изменении этого выделения. Отсутствующие, пустые, повторяющиеся или неподдерживаемые источники отклоняются, так как являются неправильными курсорами и недопустимыми числовыми границами. Ни записи, ни параметры записи не сохраняются в журнале сеансов.

Вызов session.rpc.diagnostics.configure({ sources: { mcp: { level: "off" } } }) для отключения записи MCP и очистки сохраненного буфера. Конфигурация обновляет только явно именованные источники и возвращает действующие уровни источника. Отклонена пустая или неизвестная конфигурация источника; добавление другого поддерживаемого источника в будущем не будет неявно выбирать существующий вызывающий объект.

Остановите цикл чтения узла; операции чтения при отключении ведения журнала возвращаются немедленно, а не ожидая. Выдающийся длинный опрос просыпается при отключении ведения журнала. Опущение во время возобновления резидентного возобновления diagnostics сохраняет текущую конфигурацию; для сеанса с холодной загрузкой требуется новое согласие. Включение диагностики из начального off состояния может начать запись для уже активного подключения MCP. После отключения configure({ sources: { mcp: { level: "off" } } })диагностики повторное включение может возобновить запись для одного и того же динамического подключения и его существующего идентификатора подключения. Записи, которые уже были в полете при отключении диагностики, удаляются.

Среда выполнения удаляет настроенные и структурно распознанные учетные данные из диагностики HTTP до достижения этого API, но это не гарантирует, что произвольные секреты, предоставленные сервером, отсутствуют. Он не предоставляет карты заголовков запросов или ответов. Только выбранные метаданные, такие как Content-Type, Acceptи MCP-Protocol-Version, имеют право на запись, но его значения по-прежнему ненадежны и могут содержать конфиденциальное содержимое. Заголовки проверки подлинности, файлы cookie, идентификаторы сеансов, значения запросов, URL-адрес пользователя и фрагменты опущены. Пути URL-адресов сохраняются для устранения неполадок, поэтому не помещайте учетные данные в сегменты путей. Полезные данные протокола и stderr также могут содержать содержимое пользователя или произвольные секреты сервера.

Troubleshooting

Инструменты не отображаются или не вызываются

  1. Проверьте, что сервер MCP запускается правильно

    • Проверьте, правильны ли команды и args
    • Убедитесь, что серверный процесс не вылетает при запуске
    • Ищите ошибку в stderr

  2. Конфигурация инструментов проверки

    • Убедитесь, tools что он настроен или ["*"] перечисляет конкретные инструменты, которые вам нужны
    • Пустой массив [] означает, что инструменты не включены

  3. Проверьте подключение для удалённых серверов

    • Убедитесь, что URL доступен
    • Проверьте, правильны ли заголовки аутентификации

Распространенные проблемы

IssueSolution
"MCP-сервер не найден"Убедитесь, что путь команды правильный и выполнимый
"Соединение отказано" (HTTP)Проверьте URL и убедитесь, что сервер работает
Ошибки «Тайм-аут»Увеличьте timeout значение или проверьте производительность сервера
Инструменты работают, но не называютсяУбедитесь, что ваш запрос явно требует функциональности инструмента

Подробные рекомендации по отладке смотрите Руководство по отладке серверов MCP.

См. также