MCP сървър: инструменти, резултати и внедряване
На тази страница
Урокът е пренаписан на 3 ноември 2026 г. въз основа на страницата Build an MCP server от документацията на OpenAI за плъгини и кода на MCP TypeScript SDK (версия 1.32.2). Предишният урок описваше „действия“ (
defineAction,ActionError) от несъществуващ SDK; тази роля вече се изпълнява от MCP инструментите. Източници: Build an MCP server · MCP TypeScript SDK.
Сървърът, неговата идентичност и инструкции
Създайте MCP сървър със стабилно име и версия. По време на инициализацията той може да върне и поле instructions, което ChatGPT и Codex четат заедно с метаданните на инструментите. Запазете това поле за насоки, които важат за всички инструменти – например задължителен ред на извикване или общ лимит на заявките – и поддържайте основното съдържание в рамките на първите 512 символа. Не копирайте описанията на инструментите тук и не се опитвайте да променяте личността на модела.
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer(
{ name: "acme-projects", version: "1.0.0" },
{
instructions:
"Before modifying a project, call get_project to confirm its ID and status.",
}
);
Един инструмент за всяко действие
Създавайте по един инструмент за всяко отделно действие: list_projects, get_project, update_project, вместо един универсален инструмент с множество режими. Всеки инструмент комбинира име, ориентирано към действието, четливо заглавие, описание, обясняващо кога да се използва, явна схема на входа, схема на изхода (ако връща структурирани данни), точни анотации и обработчик, който упълномощава заявката преди изпълнение. Моделът разчита на тези метаданни, за да реши дали и как да извика инструмента – третирайте ги като част от потребителското изживяване.
import { z } from "zod";
const project = z.object({ id: z.string(), name: z.string(), status: z.enum(["active", "archived"]) });
server.registerTool(
"get_project",
{
title: "View a project",
description:
"Use when the user wants details about a specific project in their Acme workspace. " +
"Requires the ID returned by list_projects.",
inputSchema: { id: z.string().min(1) },
outputSchema: { project: project },
annotations: { readOnlyHint: true, openWorldHint: false, destructiveHint: false },
},
async ({ id }, extra) => {
const user = await authenticate(extra); // Your access control (Lesson 8)
const found = await loadProject(user, id); // Your data access
if (!found) {
return {
isError: true,
content: [{ type: "text", text: `No project ${id} is accessible with this account.` }],
};
}
return {
structuredContent: { project: found },
content: [{ type: "text", text: `Project "${found.name}" (${found.status}).` }],
};
}
);
Функциите authenticate и loadProject са Ваши собствени. Критичният момент е тяхното разположение: упълномощаването се извършва на сървъра при всяка заявка. Никога не разчитайте на модела да решава дали потребителят има право да достъпи данни.
Полезни резултати без интерфейс
Резултатът от инструмент може да съдържа три неща:
structuredContent: лаконични данни, които моделът може да инспектира и използва повторно в последващи извиквания;content: текст или друго MCP съдържание, което му помага да отговори;_meta: данни, предназначени за клиента, скрити от модела.
Връщайте достатъчно информация, за да може моделът да завърши задачата без визуален компонент, използвайки стабилни идентификатори, които последващите инструменти могат да използват повторно. Два аспекта на SDK заслужават внимание. Инструмент, деклариращ outputSchema, трябва да връща съвместимо structuredContent при всички успешни резултати; в противен случай SDK ще генерира грешка при валидация. Бизнес грешка – например липсващ проект или отказано действие – се сигнализира чрез резултат с isError: true, придружен от обяснителен текст, който моделът може да предаде на потребителя; този тип резултат заобикаля валидацията на изходната схема.
Никога не включвайте тайни, токени за достъп или ненужни лични данни в резултата и не третирайте _meta като безопасно скривалище: това поле е скрито от модела, но не е защитено.
Анотации и извличане на информация
Анотациите трябва да отразяват реалното поведение на инструмента: задайте readOnlyHint на true само ако инструментът не може да модифицира нищо, destructiveHint на true, ако може да причини необратим или трудно обратим ефект, и openWorldHint на true, ако засяга публичния интернет или отворени външни субекти. Те помагат на ChatGPT и Codex да изберат правилното поведение за потвърждение; те не заместват логиката за упълномощаване, валидация или потвърждение на Вашия сървър.
Когато сървърът се нуждае от структурирана информация, липсваща в извикването – например дата или избор между две опции – той може да я поиска чрез elicitation, механизъм на MCP протокола. Ограничете това до информация, която потребителят разумно може да предостави; никога не го използвайте за събиране на тайни или за заобикаляне на нормалното удостоверяване.
Множество акаунти и корпоративни знания
Две опционални съвместимости подобряват интеграцията. За да помогнете на потребителите, свързващи множество акаунти, изложете инструмент за профил, който е упълномощен, само за четене и маркиран с _meta["openai/profile"]: true. OpenAI използва това, за да идентифицира свързаните акаунти и да помогне на потребителите да ги разграничат. Профилът се извежда от валидираните удостоверителни данни на заявката и всяко извикване остава ограничено до тези удостоверителни данни.
Функцията company knowledge на ChatGPT може да използва инструментите само за четене на Вашия сървър. За да направите плъгин допустим като източник, внедрете стандартните входни схеми за инструментите search и fetch, маркирайте другите инструменти само за четене с readOnlyHint: true и връщайте абсолютни, отваряеми от потребителя URL адреси за източниците, които моделът трябва да цитира.
Внедряване на крайната точка
Публичното подаване изисква сървър на стабилен, публично достъпен HTTPS адрес. Тази крайна точка трябва да поддържа транспорт streamable HTTP, да отговаря на стабилен URL (обикновено завършващ на /mcp), да отговаря на изискванията за латентност и наличност на Вашите работни потоци, да достига до Вашите услуги и данни, да запазва границите на удостоверяване и упълномощаване и да генерира дневници и метрики за неуспехи при инициализация и извикване на инструменти.
Secure MCP Tunnel на OpenAI Ви позволява да свържете частен сървър с ChatGPT, но не отговаря на изискванията за публично подаване, както и временен тунел или локален адрес. Ако сървърът трябва да остане частен, поставете публичен HTTPS прокси пред него: mTLS, управляван от OpenAI, удостоверява ChatGPT като клиент, OAuth 2.1 удостоверява Вашите потребители, и може да се добави списък с разрешени IP адреси – включително диапазони, публикувани от OpenAI за конектори на ChatGPT, които се актуализират автоматично – но той никога не замества удостоверяването.
Преди да пуснете системата в експлоатация: инжектирайте удостоверителни данни чрез мениджъра за тайни на Вашия хост, конфигурирайте сървъра за упълномощаване и пренасочванията, задайте таймаути и лимити на заявките за скъпи или външно видими инструменти, премахнете отговорите за дебъгване и ненужните лични данни и проверете дали дневниците не съдържат токени или чувствителни резултати. След внедряването повторете теста с MCP Inspector срещу производствения адрес.
Еволюция без прекъсвания
Поддържайте публикуваните имена на инструменти и схеми обратно съвместими: добавяйте полета или инструменти, но не нарушавайте съществуващите договори. Ако метаданните се променят, обновете връзката и повторете своя набор от оценки преди подаване. За интерфейс променете идентификатора на ресурса, когато HTML, JavaScript или CSS се развиват по начин, който може да наруши кеширан компонент.
Напомняния за сигурност
- Цялата входна информация на инструментите е ненадеждна: валидирайте я и налагайте упълномощаване на сървъра
- Изисквайте потвърждение за записи с високо въздействие
- Пазете тайните и чувствителните данни извън метаданните и резултатите
- Водете достатъчно дневници за разследване, но изключвайте удостоверителни данни и ненужни лични данни
- Ограничавайте честотата на скъпи или външно видими действия
Ключови изводи
- Именуван, версиониран сървър с кратки, общи
instructions - По един инструмент за действие, със заглавие, описание на намерението, схеми, анотации и упълномощаване в обработчика
structuredContent, съвместимо с изходната схема,isError: trueза бизнес грешки, нищо тайно в_meta- Публикуване: стабилен, публичен HTTPS чрез streamable HTTP; Secure MCP Tunnel е недостатъчен
- Обратно съвместими договори и версионирани идентификатори на ресурси