Развертывание сервера Didit MCP на собственном хостинге

Основные выводы

• Сервер Didit Model Context Protocol (MCP) имеет открытый исходный код под лицензией MIT. Вы можете собрать его из публичного репозитория GitHub и запустить с помощью Docker, Node.js или безголосного транспорта stdio.
• Самостоятельный хостинг изменяет место выполнения процесса MCP, но не способ его связи с Didit. Каждый режим аутентифицируется как пользователь Didit с токеном доступа Bearer. Режим ключа API приложения для инструментов MCP отсутствует.
• Полный каталог для самостоятельного хостинга содержит 121 инструмент. Размещенная конечная точка Open Authorization (OAuth) намеренно предоставляет 115. Примеры в текущем источнике включают didit_context_get, didit_session_create и didit_transaction_screen_wallet.
• Точка входа HTTP не имеет состояния и принимает трафик MCP через запросы POST. Новый сервер и транспорт создаются для каждого запроса, поэтому балансировщику нагрузки не требуется "привязка" сессии.
• Используйте /healthz для проверок контейнера и балансировщика нагрузки. Настройте общедоступный URI ресурса, источник авторизации, режим проверки токена и секреты явно, прежде чем выставлять сервис.

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

Это руководство посвящено только работе с сервером. Для каталога и поведения инструментов используйте справочник инструментов Didit MCP. Для настройки клиента с управляемой конечной точкой используйте руководство по установке Claude. Полные технические справочники находятся в обзоре MCP и документации по аутентификации.

Выберите точку входа HTTP или stdio

Репозиторий создает один общий каталог инструментов с двумя точками входа. dist/http.js запускает сервер ресурсов Express поверх безгосударственного Streamable HTTP. Это правильный выбор для общего сервиса, доступного нескольким клиентам MCP, контейнерам или пользователям. dist/index.js работает через stdio и предназначен для безголосного локального процесса, запускаемого одним клиентом.

Обе точки входа вызывают одну и ту же логику диспетчеризации, и версия 5 предоставляет только инструменты MCP — не ресурсы или подсказки MCP. Обе аутентифицируют нижестоящие запросы как пользователь Didit. Разница заключается в том, как эти учетные данные пользователя достигают процесса: точка входа HTTP получает и проверяет токен OAuth Bearer вызывающего абонента; точка входа stdio считывает токен Bearer пользователя из DIDIT_ACCESS_TOKEN.

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

Сборка и запуск с помощью Docker

Репозиторий включает многоэтапный Dockerfile на основе Node 20. Этап сборки устанавливает зависимости для разработки, компилирует TypeScript и удаляет пакеты для разработки. Этап производства запускается от имени пользователя node, не являющегося root, и включает проверку работоспособности контейнера.

git clone https://github.com/didit-protocol/mcp.git
cd mcp
cp .env.example .env

docker build -t didit-mcp .
docker run -p 3000:3000 --env-file .env didit-mcp

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

MCP_PORT=3000
MCP_RESOURCE_URI=https://mcp.example.com
MCP_AUTHORIZATION_SERVER_ORIGIN=https://business.didit.me
MCP_TOKEN_VERIFY_MODE=introspection
MCP_OAUTH_CLIENT_ID=replace-with-client-id
MCP_OAUTH_CLIENT_SECRET=replace-with-client-secret
MCP_SCOPES_SUPPORTED="didit:management didit:verification"

Завершите Transport Layer Security (TLS) на вашем входящем шлюзе или балансировщике нагрузки, перенаправьте запросы POST MCP на порт 3000 и сохраните заголовок Authorization. Внешне видимый MCP_RESOURCE_URI должен соответствовать идентификатору ресурса, рекламируемому клиентам; не оставляйте управляемый URI Didit для другого общедоступного источника.

Сборка и запуск напрямую с помощью Node.js

Если ваша платформа уже управляет средой выполнения Node, используйте ту же точку входа HTTP без контейнера. Пакет является частным и не распространяется через npm, поэтому клонируйте репозиторий, а не пытайтесь выполнить опубликованный пакет.

git clone https://github.com/didit-protocol/mcp.git
cd mcp
npm install
npm run build
node dist/http.js

Процесс считывает те же переменные среды, что и контейнер. Запустите его под вашим супервизором процессов, внедрите секреты через среду развертывания и маршрутизируйте только необходимые конечные точки. Запросы MCP отправляются на POST /mcp. Сервис намеренно отклоняет GET и DELETE на этом маршруте, поскольку он не поддерживает сессии MCP или инициированные сервером потоки.

Node.js не загружает файл .env репозитория автоматически. Экспортируйте значения в оболочку, внедрите их через менеджер сервисов или используйте поддержку файлов среды вашей платформы перед запуском dist/http.js. Также обратите внимание, что npm start запускает точку входа stdio; используйте node dist/http.js или npm run start:http для HTTP.

Запуск без головы через stdio

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

DIDIT_ACCESS_TOKEN=<user-access-token> node dist/index.js

Этот токен является учетными данными Bearer пользователя, а не учетными данными приложения. Храните его как секрет, не допускайте его попадания в историю оболочки и журналы и меняйте его в соответствии с вашей политикой доступа. Если одно развертывание всегда работает в одной организации или приложении, MCP_DEFAULT_ORG и MCP_DEFAULT_APP могут предоставить эту область по умолчанию. В противном случае инструменты могут разрешать область из явных аргументов или контекста аутентифицированного запроса.

В stdio по-прежнему нет режима ключа API приложения. Самостоятельно размещенный HTTP и самостоятельно размещенный stdio оба вызывают конечные точки консоли Didit с областью действия пользователя, поэтому ключ приложения не может заменить токен Bearer пользователя.

Настройка полной поверхности среды

Текущий src/config.ts поддерживает следующие переменные. Большинство развертываний должны сохранять производственные значения по умолчанию Didit API и авторизации и переопределять только идентификатор ресурса, конфигурацию проверки и секреты, необходимые для их топологии.

Общие переменные и переменные stdio

• DIDIT_ACCESS_TOKEN: токен Bearer пользователя для безголосного режима stdio; по умолчанию отсутствует.
• DIDIT_API_BASE_URL: базовая URL-адрес API проверки; по умолчанию https://verification.didit.me/v3.
• DIDIT_AUTH_BASE_URL: базовая URL-адрес API аутентификации; по умолчанию https://apx.didit.me/auth/v2.
• MCP_DEFAULT_ORG и MCP_DEFAULT_APP: необязательные значения по умолчанию для организации и приложения для однопользовательских развертываний.

Переменные сервера ресурсов HTTP

• MCP_PORT: порт прослушивания; по умолчанию 3000.
• MCP_RESOURCE_URI: общедоступный URI сервера ресурсов; по умолчанию https://mcp.didit.me.
• MCP_AUTHORIZATION_SERVER_ORIGIN: источник сервера авторизации; по умолчанию https://business.didit.me.
• MCP_TOKEN_VERIFY_MODE: по умолчанию introspection, или jwks, когда служба авторизации выдает JSON Web Tokens (JWT), подходящие для локальной проверки подписи.
• MCP_OAUTH_CLIENT_ID и MCP_OAUTH_CLIENT_SECRET: по умолчанию отсутствуют; используются в качестве HTTP Basic учетных данных для интроспекции Request for Comments (RFC) 7662.
• MCP_OAUTH_INTROSPECT_URL: по умолчанию https://apx.didit.me/auth/v2/introspect/.
• MCP_SCOPES_SUPPORTED: области обнаружения, разделенные пробелами; по умолчанию didit:management didit:verification.

Переопределения метаданных авторизации

• DIDIT_AUTH_ISSUER: по умолчанию MCP_AUTHORIZATION_SERVER_ORIGIN.
• DIDIT_OIDC_DISCOVERY_URL: документ обнаружения OpenID Connect (OIDC); по умолчанию источник авторизации плюс /.well-known/oauth-authorization-server.
• DIDIT_JWKS_URL: конечная точка JSON Web Key Set (JWKS); по умолчанию https://apx.didit.me/auth/config/jwks/.
• DIDIT_OIDC_AUTHORIZE_URL: по умолчанию источник авторизации плюс /authorize.
• DIDIT_OIDC_TOKEN_URL: по умолчанию источник авторизации плюс /api/auth/oauth-token.
• DIDIT_OIDC_REGISTRATION_URL: по умолчанию источник авторизации плюс /api/auth/oauth-register.

Используйте introspection для непрозрачных токенов доступа. Сервер отправляет их на настроенную конечную точку интроспекции, используя MCP_OAUTH_CLIENT_ID и MCP_OAUTH_CLIENT_SECRET. Используйте jwks только тогда, когда ваша служба авторизации настроена на выдачу подписанных токенов доступа JWT для этого клиента; затем сервер проверяет подписи по DIDIT_JWKS_URL. Изменение режима проверки не создает другую модель идентификации: проверенный субъект остается пользователем Didit.

Клиенты MCP могут использовать динамическую регистрацию клиентов (DCR) с консолью Didit Business во время своего потока авторизации. Эта регистрация клиента отделена от MCP_OAUTH_CLIENT_ID и MCP_OAUTH_CLIENT_SECRET сервера ресурсов, которые аутентифицируют запросы интроспекции. Предоставьте эти учетные данные на стороне сервера через соответствующий канал развертывания Didit, а не предполагайте, что регистрация клиента может их заменить.

Проверки работоспособности и безгосударственное масштабирование

Процесс HTTP предоставляет GET /healthz и возвращает JSON, содержащий status, service и version. Образ Docker уже проверяет его каждые 30 секунд после 15-секундного периода запуска. Вы можете использовать ту же конечную точку для готовности Kubernetes, группы целевых объектов Application Load Balancer или внешнего зонда доступности.

curl -fsS http://localhost:3000/healthz

Маршрут MCP по своей сути не имеет состояния. Для каждого аутентифицированного POST процесс создает новый сервер и транспорт Streamable HTTP с отключенной генерацией сеансов, передает проверенные учетные данные вызывающего абонента через контекст для каждого запроса, завершает диспетчеризацию и закрывает транспорт. В памяти нет сеанса, который последующий запрос должен был бы найти на той же реплике.

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

В результате горизонтальным репликам не требуются "липкие" сеансы. Любой работоспособный экземпляр может обрабатывать следующий POST, и поэтапные развертывания не требуют очистки сеансов, кроме обычной обработки текущих запросов. Планирование мощности должно быть сосредоточено на параллелизме запросов, задержке API Didit нижестоящего уровня и вашей обычной политике тайм-аутов и повторных попыток.

Проверка перед предоставлением доступа к сервису

• Убедитесь, что /healthz успешно работает из того же сетевого пути, что и балансировщик нагрузки.
• Убедитесь, что неаутентифицированные запросы MCP получают запрос авторизации, а не вывод инструмента.
• Завершите поток OAuth 2.1 с Proof Key for Code Exchange (PKCE), затем вызовите didit_context_get, чтобы убедиться, что видны ожидаемые организации и приложения.
• Ознакомьтесь с расширенной документацией MCP, прежде чем изменять конечные точки обнаружения или проверку токенов.
• Используйте страницу разработчика Didit MCP для получения информации о поддерживаемой управляемой поверхности и актуальных ссылках.

Если самостоятельный хостинг больше не является требованием, управляемая конечная точка удаляет описанные выше операции сервера ресурсов среды выполнения и OAuth. Пользователи Claude могут добавить его с помощью прямой ссылки на коннектор Didit. Независимо от того, запускаете ли вы процесс или это делает Didit, основное правило идентично: операции MCP аутентифицируются как пользователь Didit, никогда как ключ API приложения.