Proxy-запросы к провайдеру.

Выбор интерфейса

Proxy позволяет обращаться к методам провайдера, для которых нет отдельного инструмента. Это не произвольный HTTP-доступ к любому адресу. Провайдер, credentials и базовый адрес определяются подключением и конфигурацией коннектора. Для некоторых коннекторов origin берётся из подключения и проходит egress-проверку.

Обнаружение mirror endpoint

1. Получите GET /v1/connectors/{connectorId}/endpoints с tools:read. Фильтры: q, group, include_removed, cursor, limit.
2. Выберите endpoint и запросите GET /v1/connectors/{connectorId}/endpoint?method=GET&path=.... path — шаблон из каталога; кодируйте его как query value.
3. Прочитайте input_schema, output_schema, risk, sensitive, idempotent, paging и descriptor_digest. Входная схема содержит точные vendor-поля; формат зависит от провайдера.
4. Заполните параметры и вызовите его call_url методом из описания.

Полный контракт discovery и mirror. Endpoint ID имеет вид метода и шаблона пути. Удалённая запись может присутствовать в списке с include_removed=true; выполнить её нельзя. Endpoint не становится автоматически MCP-инструментом.

Mirror: запрос и ответ

curl "https://context4.me/v1/api/amocrm/api/v4/leads/7" \
  -H "Authorization: Bearer $CONTEXT4_API_KEY" \
  -H "Context4-Connection-Id: $CONTEXT4_CONNECTION_ID"

Это пример формы GET, который применим, если данный endpoint есть в вашем каталоге и аккаунт имеет доступ к сделке. Origin и ключи берутся из вашего окружения. Тело отсутствует у bodyless-метода; для JSON-записи передавайте vendor JSON напрямую. Mirror поддерживает GET, POST, PUT, PATCH, DELETE; HEAD даёт 405 и ничего не исполняет.

Путь зеркалирует путь провайдера после /v1/api/{connectorId}/. Можно передавать / буквально либо закодировать весь vendorPath одним сегментом. Slash внутри одного значения параметра передаётся как %2F, а при кодировании всего пути — %252F. Он допустим только в параметре известного шаблона; . и .. части запрещены.

Query и объявленные vendor-заголовки проверяются входной схемой. Массивы передаются повторёнными именами или разделителем согласно descriptor; неизвестный query и повтор скалярного параметра отклоняются. Нельзя предполагать, что любой входящий заголовок будет отправлен провайдеру.

Вызов требует executions:write, включая GET. Context4-Connection-Id обязателен; чужой коннектор или отозванное подключение даёт platform conflict. Неизвестный endpoint даёт 404 до upstream-запроса, неверные vendor-параметры — 400 до создания execution.

Ответ сохраняет HTTP-статус и JSON-тело провайдера, допустимые etag/retry-after. Context4-Origin: provider отличает его от platform-ошибки, Context4-Execution-Id связывает вызов с выполнением. Ошибка платформы имеет Context4-Origin: platform и problem JSON. Не считайте любой 403 ошибкой политики: проверьте origin.

Каталог mirror включает операции, которые можно передать JSON в обе стороны. Multipart, form body, произвольные bytes и redirect-only download не обещаны. Недоступный provider, таймаут или не-JSON ответ могут дать 503. Каждый mirror-вызов — новый запрос, даже с повторённым Idempotency-Key.

Raw Composio proxy

POST /compat/context4/v1/api/v3.1/tools/execute/proxy принимает:

{
  "connected_account_id": "UUID выбранного подключения",
  "endpoint": "/api/v4/leads",
  "method": "GET",
  "parameters": [
    { "name": "limit", "type": "query", "value": 10 }
  ]
}

Подставьте реальный UUID. method: GET, POST, PUT, DELETE, PATCH, HEAD. endpoint — относительный путь от API base коннектора с начальным /. parameters — массив объектов с name, type (header или query) и строковым/числовым value; in принимается вместо type. Необязательный body — JSON. Повтор имени в этом legacy массиве заменяет предыдущее значение; для vendor-массивов предпочтителен mirror с явной схемой сериализации.

Результат — JSON-конверт {status, data, headers}. HTTP-статус самого compat-запроса отличается от upstream status. Policy refusal даёт 403, quota — 429, недоступный аккаунт — 404; permanent input/provider rejection отображается как validation error, transient failure — 503.

Если передан user_id, выбранный аккаунт проверяется на возможность использования этим principal. Необязательный borrowers сужает набор владельцев до перечисленных и самого principal; он не отменяет tenant-границу. При нескольких аккаунтах выбирайте connected_account_id явно. Session proxy использует закреплённый аккаунт и ограничения сессии.

Границы безопасности и повторов

Запрещены абсолютный URL, //host, traversal, обратный slash, raw fragment и управляющие символы. Raw proxy не принимает encoded slash как обход шаблона. Credentials подключённого сервиса подставляются сервером: не передавайте provider token через proxy.

Caller-заголовки Authorization, Proxy-Authorization, Cookie, Cookie2, x-api-key запрещены. Заголовки управления транспортом (base-url-override, connection-id, provider-config-key, retries, retry-on, decompress, forward-headers-on-redirect, nango-*) также отклоняются. Hop-by-hop заголовки удаляются. Context4 bearer используется для входа в Context4 и не становится credential провайдера.

Raw proxy обходит схему tool wrapper, сохраняя tenant, policy, quota, rate limit и audit. Это не обещание доступа к любому endpoint независимо от возможностей коннектора и его транспорта. Проверяйте документацию самого провайдера и доступность операции. После таймаута записи сверяйте исход: отсутствие ответа не доказывает отсутствие эффекта.