sugra-api-mcp

Опубликован в каталоге коннекторов Anthropic. Доступен в Claude в веб-версии, на компьютерах и мобильных устройствах, а также в Claude Code и Cowork.

Опубликован в официальном каталоге плагинов OpenAI. Доступен для ChatGPT и Codex.

Предоставьте любому AI-агенту доступ к более чем 1 600 конечным точкам данных о рынках, экономике, компаниях, государственных структурах, новостях, климате, морских перевозках и проверке организаций — через один MCP-сервер.

Работает с ChatGPT, Claude, Gemini, xAI, Cursor, VS Code и любым MCP-клиентом.

Официальный сервер Model Context Protocol для Sugra API: один коннектор, каталог конечных точек и структурированные результаты инструментов с указанием источника в каждом ответе.

Пример работы

Агент самостоятельно отвечает на реальный вопрос: определяет сущности, получает актуальные данные и историю, а также указывает источник и время обновления для каждого значения.

Другие примеры:

Макроэкономический анализ — по одному запросу формируется полная таблица инфляции и ключевых ставок стран G7. Для каждой ячейки указаны дата и источник; недоступные значения отмечаются, а не выдумываются.

Сводка по разным областям — данные о нефти Brent, морской погоде и региональных рисках объединяются для отдела морских перевозок; для каждого значения указаны источник и временная метка.

Как выглядит сеанс

Пример транскрипта размещённого MCP (показанные здесь три составных инструмента работают на размещённой конечной точке). Пример зафиксирован в конкретный момент: формулировки и значения могут отличаться в разных запусках и при публикации новых данных BLS.

macro indicator cpi_us (U.S. Bureau of Labor Statistics) get_snapshot("cpi_us") -> latest reading with freshness, provenance and quota cost get_timeseries("cpi_us", metric="macro_series", range="1y") -> 12 monthly points with an explicit downsampling flag

Agent: US CPI printed 2.9% year over year in the latest release, down from 3.5% twelve months earlier - a steady decline since spring. Source: U.S. Bureau of Labor Statistics via the Sugra API.">

User: Where does US inflation stand, and how has it trended over the past year?

resolve_entity("US inflation")
  -> macro indicator cpi_us (U.S. Bureau of Labor Statistics)
get_snapshot("cpi_us")
  -> latest reading with freshness, provenance and quota cost
get_timeseries("cpi_us", metric="macro_series", range="1y")
  -> 12 monthly points with an explicit downsampling flag

Agent: US CPI printed 2.9% year over year in the latest release, down from
3.5% twelve months earlier - a steady decline since spring.
Source: U.S. Bureau of Labor Statistics via the Sugra API.

Каждый результат инструмента содержит структурированные метаданные — источник, актуальность данных и стоимость запроса с учётом лимитов. Благодаря этому агенты могут указывать источники и планировать расход запросов, а не гадать.

Как это работает

flowchart LR
    A["AI agent<br/>(ChatGPT, Claude, Gemini, xAI, IDEs)"] --> B["Sugra MCP<br/>gateway tools, plus agent tools when hosted"]
    B --> C["Sugra API<br/>1,600+ endpoints, 36 data domains"]
    C --> D["160+ primary sources<br/>markets, economics, government,<br/>news, climate, maritime"]

За шлюзом работает Sugra API: более 160 первичных источников — государственные статистические службы, центральные банки, межправительственные организации и другие учреждения. Они предоставляют данные для более чем 1 600 конечных точек в 36 областях. Сервер включает полный каталог конечных точек, поэтому поиск, описание и выбор наборов инструментов выполняются локально, без сетевых запросов. К API обращаются только при получении данных.

Что агенты создают с его помощью

Навыки для Sugra API находятся в Sugra-Systems/sugra-api-skills. Сервер предоставляет пять из них как ресурсы MCP (sugra://skills/...) из зафиксированного коммита этого репозитория: после подключения прочитайте URI с помощью resources/read.

Навыки для агентов

Эти навыки помогают освоить работу с каталогом. Плагин Claude Code также подключается к размещённому серверу Sugra MCP. Плагины Codex и Grok, а также папки с навыками не добавляют инструментов MCP, поэтому подключите сервер отдельно — размещённый или локальный. Пакет плагинов для каждого агента находится в Sugra-Systems/sugra-api-plugins.

Claude Code

/plugin marketplace add Sugra-Systems/sugra-api-plugins
/plugin install sugra-api-skills@sugra-api-plugins

Навыки отображаются с префиксом /sugra-api-skills:, например /sugra-api-skills:discover-and-call. Плагин также добавляет размещённый сервер https://mcp.sugra.ai/mcp; войдите в него один раз через /mcp.

Codex

codex plugin marketplace add Sugra-Systems/sugra-api-plugins
codex plugin add sugra-api-skills@sugra-api-plugins

Grok

grok plugin install Sugra-Systems/sugra-api-plugins#xai

Antigravity

git clone https://github.com/Sugra-Systems/sugra-api-plugins
agy plugin install ./sugra-api-plugins/antigravity

CLI, приложение Antigravity и IDE используют один и тот же плагин. В нём также объявлен размещённый сервер, но Antigravity CLI 1.4.9 пока не запускает сервер, объявленный плагином: добавьте его с помощью agy mcp add (Antigravity).

GitHub Copilot

copilot plugin marketplace add Sugra-Systems/sugra-api-plugins
copilot plugin install sugra-api-skills@sugra-api-plugins

Copilot CLI использует тот же плагин, что и Claude Code. Плагин также добавляет размещённый сервер https://mcp.sugra.ai/mcp; при первом подключении Copilot CLI откроет в браузере страницу входа в Sugra.

Cursor и другие агенты

npx skills add https://mcp.sugra.ai

Также можно скопировать папки с навыками из sugra-api-skills в каталог навыков агента.

ChatGPT

Навыки можно установить из каталога плагинов OpenAI. MCP-сервер подключается как размещённый коннектор по адресу https://mcp.sugra.ai/mcp (постоянный псевдоним: https://app.sugra.ai/mcp).

В сервер входят шесть сценариев запросов. В клиентах, поддерживающих запросы MCP, они становятся готовыми процессами, запускаемыми одним нажатием:

Анализ рынков и макроэкономики — «Сравни инфляцию и ключевые ставки центральных банков стран G7». (macro_briefing)
Сводки по акциям с указанием источников — «Как сегодня обстоят дела у NVIDIA: цена, профиль компании и ситуация на рынке?» (market_snapshot)
Проверка санкций и соблюдения требований — «Проверь этого поставщика и определи его идентификатор LEI». (sanctions_screening)
Сравнение секторов — «Энергетика и технологии: сравни оценки и потоки капитала». (sector_compare)
Данные о климате, морских перевозках и торговле — «Морские перевозки в Красном море на этой неделе: проходы через узкие места, цена нефти и погода на маршруте». (earth_conditions plus the transport and commodities catalog)
Поиск источников — «Какие данные по инструментам с фиксированным доходом есть в каталоге и какие учреждения их предоставляют?» (source_overview)

В каждом ответе указаны источник и актуальность данных, поэтому агенты ссылаются на источники, а не гадают.

Размещённый MCP (рекомендуется)

Установка не требуется. В Claude, ChatGPT и Codex добавьте сервер Sugra API MCP из каталога:

Claude (веб-версия, компьютерная и мобильная версии, Claude Code и Cowork): Добавить в Claude — ссылка откроет сервер Sugra API MCP в каталоге коннекторов Anthropic. Подключите его и войдите в аккаунт Sugra. В claude.ai каталог находится в разделе Customize > Connectors. Claude Code, авторизованный через аккаунт claude.ai, автоматически обнаружит коннектор; он отображается в списке /mcp.
ChatGPT и Codex: Добавить в ChatGPT — ссылка откроет сервер Sugra API MCP в каталоге плагинов OpenAI.

Для любого другого MCP-клиента или при ручной настройке используйте размещённую конечную точку Streamable HTTP:

https://mcp.sugra.ai/mcp

Инструменты шлюза, а также составные инструменты для агентов resolve_entity, get_snapshot и get_timeseries
Авторизация через OAuth в коннекторах Claude и ChatGPT либо заголовок Authorization: Bearer sugra_xxx_... с API-ключом
В качестве пользовательского коннектора в claude.ai: Customize -> Connectors -> Add custom connector
В ChatGPT: Settings -> Connectors -> Add MCP server

Уже добавили Sugra в Claude как пользовательский коннектор? Это подключение продолжит работать и будет отображаться в разделе "Custom". Если подключить сервер Sugra API MCP из каталога, появятся два подключения. Сначала удалите пользовательский коннектор, а затем подключитесь через каталог.

Локальный пакет

Работает на вашем компьютере через stdio или по HTTP при самостоятельном размещении; для работы нужен API-ключ:

pip install sugra-api-mcp

Восемь инструментов шлюза
stdio для настольных клиентов и IDE, Streamable HTTP для самостоятельного размещения
Аутентификация с помощью SUGRA_API_KEY

Получите бесплатный API-ключ на странице app.sugra.ai/register (бесплатный тариф: 50 запросов в день).

Быстрый старт

pip install sugra-api-mcp
export SUGRA_API_KEY=sugra_xxx_...   # free key: app.sugra.ai/register
sugra-api-mcp call quotes_symbol_price --params '{"symbol":"AAPL"}'

Тот же запрос можно выполнить через агента: подключите сервер к своему клиенту (см. следующий раздел) и спросите: «Почём сейчас торгуются акции AAPL? Используй Sugra». Агент найдёт в каталоге quotes_symbol_price и вызовет его, указав тикер.

Подключение клиента

Поддерживаемые клиенты:

Anthropic Claude: Claude Desktop, Claude Code (CLI), claude.ai (веб-версия)
OpenAI GPT: ChatGPT (через MCP-коннектор)
Google: Antigravity (CLI, приложение и IDE), Gemini Code Assist (VS Code и JetBrains)
GitHub: Copilot CLI
xAI: удалённые MCP Tools в xAI SDK и Responses API
IDE: VS Code (встроенная поддержка), Cursor, Zed, Cline, Continue.dev, Windsurf
Пользовательские агенты: любые решения на базе Python или TypeScript MCP SDK

Claude Desktop (stdio)

Добавьте конфигурацию в claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: версия Claude Desktop для Linux недоступна. В Linux установите пакет с помощью pip install sugra-api-mcp и используйте Claude Code (CLI), IDE-клиент или размещённую HTTP-конечную точку ниже.

{
  "mcpServers": {
    "sugra": {
      "command": "sugra-api-mcp",
      "env": {
        "SUGRA_API_KEY": "sugra_xxx_yourkey..."
      }
    }
  }
}

Перезапустите Claude Desktop. Инструменты Sugra появятся в меню инструментов.

Claude Code (Anthropic CLI)

Уже вошли в Claude Code с учётной записью claude.ai? Подключить Claude — это позволит подключить MCP-сервер Sugra API из каталога коннекторов в claude.ai. После этого он появится в /mcp, и устанавливать его локально не потребуется. Чтобы использовать локальный пакет:

claude mcp add sugra -- sugra-api-mcp
# затем задайте переменную окружения, которую считывает sugra-api-mcp
export SUGRA_API_KEY=sugra_xxx_...

Также можно вручную отредактировать ~/.claude/config.json, используя ту же структуру, что и в конфигурации Claude Desktop выше.

Чтобы установить навыки в виде плагина, который также подключает размещённый сервер:

/plugin marketplace add Sugra-Systems/sugra-api-plugins
/plugin install sugra-api-skills@sugra-api-plugins

Один раз войдите в сервер плагина через /mcp. Если также подключён коннектор Sugra API из claude.ai, Claude Code покажет только сервер плагина. При одновременном запуске локального пакета будут доступны два сервера Sugra. Удалите локальный сервер командой claude mcp remove sugra или не устанавливайте плагин и скопируйте папки навыков из sugra-api-skills в ~/.claude/skills/.

Использование с Antigravity

Antigravity (CLI agy, приложение Antigravity и IDE) подключается к размещённой конечной точке и выполняет вход через учётную запись Sugra, поэтому указывать ключ в конфигурации не нужно:

agy mcp add sugra-api https://mcp.sugra.ai/mcp

При первом обращении агента к серверу Antigravity откроет в браузере страницу входа Sugra. Размещённая конечная точка предоставляет инструменты шлюза и три инструмента агента, доступных только в размещённой версии. Чтобы добавить навыки, установите плагин (Antigravity).

Использование с GitHub Copilot CLI

Copilot CLI подключается к размещённой конечной точке и выполняет вход через учётную запись Sugra, поэтому указывать ключ в конфигурации не нужно:

copilot mcp add --transport http sugra-api https://mcp.sugra.ai/mcp

При первом подключении к серверу Copilot CLI откроет в браузере страницу входа Sugra. Чтобы войти повторно, используйте /mcp auth sugra-api. Плагин (GitHub Copilot) добавляет тот же сервер вместе с навыками, поэтому после установки плагина эту команду можно не выполнять.

Cursor, Zed, Cline, Continue.dev, Windsurf

У каждого из этих клиентов есть файл настроек MCP — обычно mcp.json или аналогичный. Он использует ту же структуру конфигурации stdio, что и Claude Desktop.

ChatGPT

Подключить ChatGPT — установить MCP-сервер Sugra API из каталога плагинов OpenAI. Также можно добавить размещённую HTTP-конечную точку ниже в качестве MCP-коннектора: ChatGPT не запускает локальные процессы stdio.

HTTP (claude.ai, ChatGPT, удалённые агенты)

В claude.ai команда Подключить Claude подключает MCP-сервер Sugra API из каталога коннекторов Anthropic. В ChatGPT команда Подключить ChatGPT устанавливает сервер из каталога плагинов OpenAI. Для ручной настройки или подключения любого другого MCP-клиента с поддержкой Streamable HTTP используйте размещённую конечную точку:

https://mcp.sugra.ai/mcp

Пройдите OAuth-аутентификацию в процессе подключения или используйте Authorization: Bearer sugra_xxx_....

Чтобы добавить пользовательский коннектор в claude.ai: Customize -> Connectors -> Add custom connector.

В ChatGPT: Settings -> Connectors -> Add MCP server.

Справочник инструментов

Локальный пакет предоставляет восемь инструментов шлюза. Размещённая версия дополнительно включает три составных аналитических инструмента (см. раздел «Размещённый MCP» выше). Пакет предоставляет ровно восемь инструментов:

Инструмент	Назначение
`fetch_data`	Один шаг: находит наиболее подходящую конечную точку для запроса на естественном языке и вызывает её. Объединяет поиск и вызов в одном обращении.
`search_endpoints`	Поиск в каталоге конечных точек, включённом в пакет. Поиск во время выполнения не обращается к `/openapi.json`.
`describe_endpoint`	Просмотр конечной точки по `operation_id`: путь, метод, параметры, обязательные входные данные, `agent_hints` и `request_body_schema` для операций POST с JSON-телом запроса.
`call_endpoint`	Вызов операции Sugra API по `operation_id`. Произвольные вызовы по пути больше не поддерживаются.
`list_toolsets`	Список групп каталога с количеством конечных точек и описаниями.
`list_sources`	Метаданные источников каталога, включённого в пакет.
`sugra_entity_screen`	Проверка имени по санкционным спискам и спискам наблюдения (Sugra Entity).
`sugra_entity_lookup`	Составной поиск организации по идентификатору: `anchor` принимает значение `lei` или `vat`, а `value` — соответствующий идентификатор. Возвращает данные о регистрации и результат проверки (Sugra Entity).

Инструменты call_endpoint и fetch_data поддерживают форматирование ответа с помощью параметров limit, fields и include_raw. Форматирование работает как с ответами в обёртке ({"data": ...}), так и без неё. В fields можно указывать пути к вложенным объектам через точку (geo.city), а в meta.shaped приводятся сведения о фактически применённых преобразованиях (fields_applied / fields_unmatched, limit_applied, records_path, order, kept_end), а не повторно передаются параметры запроса. Параметры limit и fields применяются к списку записей: к списку в обёртке data, массиву верхнего уровня или единственному списку внутри объекта data, если список содержится ровно в одном из следующих полей: data, entries, events, history, items, observations, points, records, results, rows, series, timeseries (например, data.items в ответе с последними новостями или data.observations в ряду FRED). Если в data нет единственного такого списка, но каждое из его значений — объект, содержащий ровно один список observations, как в случае с несколькими именованными подрядами, расположенными рядом, параметр limit ограничивает каждый список data..observations отдельно. При этом fields по-прежнему задаёт имена ключей в data. Соседние с этим списком ключи, например total и count, остаются без изменений, а вложенные в записи списки не обрезаются. Если значение fields совпадает с ключом самого объекта data, вместо этого выбирается соответствующий объект. Если ни один элемент проекции не совпадает с данными, ответ остаётся без изменений. В meta.shaped.limit_applied указано, было ли применено ограничение, а в meta.shaped.records_path — путь к использованному списку (data, data., data.*.observations или null, если список записей не использовался). Параметр limit сохраняет самые новые записи, если каждая запись содержит ключ даты или периода (например, date, period или year) в одном формате и список упорядочен по нему в одном направлении: для списка от старых записей к новым сохраняются последние N записей в исходном порядке, а для списка от новых к старым — первые N. В остальных случаях сохраняются первые N записей. Если limit ограничивает список записей, в meta.shaped.order указывается asc, desc или unknown, а в meta.shaped.kept_end — newest или first. Для соседних подрядов эти значения представлены в виде карты по именам подрядов. Массив верхнего уровня JSON (или скалярное значение) всегда оборачивается в {"data": ...}, чтобы результат MCP оставался объектом. Иначе проверка выходных данных FastMCP сообщает об ошибке при успешном вызове и отбрасывает строки.

Параметр fields принимает не более 32 путей. Длина каждого пути не должна превышать 256 символов, а число частей, разделённых точками, — 16. При превышении любого из этих ограничений вызов возвращает projection_too_large до отправки запроса. При использовании fields проекция обрабатывает не более 100 000 элементов списка, выполняется не дольше 5 секунд и применяется к ответу объёмом не более 2 000 000 символов JSON. Это ограничение намного выше лимита результата в 18 000 символов, который применяется после проекции: прогноз погоды на 16 дней занимает около 295 000 символов до того, как fields=["daily"] сокращает его до допустимого размера. Без параметра fields эти ограничения не применяются. Форматирование выполняется в отдельном пуле из двух рабочих потоков, а не в цикле обработки событий: одновременно может выполняться или ожидать поток не более 8 задач, из них не более 4 — от одного клиента. Если за 2 секунды для вызова не найдётся свободного слота, он вернёт server_busy с областью shaping или caller_shaping.

Инструмент describe_endpoint возвращает рассчитанные для каждой конечной точки подсказки agent_hints, чтобы агенты могли заранее оценить время выполнения и допустимый параллелизм:

duration_class — fast (менее ~2 с, данные получены из снимка), slow (проксирование запросов к внешнему сервису в реальном времени, иногда более 15 с) или heavy (отдельные запросы к внешнему сервису для каждого элемента; крупные пакеты могут превысить тайм-аут шлюза)
max_concurrency — рекомендуемый предел параллельных вызовов из одного сеанса
bulk_cost — для пакетных конечных точек с отдельной обработкой каждого элемента: за каждый элемент в теле запроса списывается один кредит запроса (API указывает общее количество в заголовке ответа X-RateLimit-Cost)

Инструменты агентов только для размещённой версии (mcp.sugra.ai/mcp)

Размещённая конечная точка MCP по адресу https://mcp.sugra.ai/mcp предоставляет те же восемь инструментов и ещё три составных инструмента для агентов, недоступных через stdio или при самостоятельном развёртывании:

Инструмент	Назначение
`resolve_entity`	Преобразование произвольного текста (тикера, названия компании, индикатора, криптовалюты или валютной пары) в каноническую сущность рынка или макроэкономики. Для неоднозначных совпадений возвращается ранжированный список кандидатов — автоматический выбор не выполняется.
`get_snapshot`	Формирование единого составного представления текущего состояния по сущности и указанному сценарию. Включает сведения о свежести данных, их происхождении и полноте, а также информацию о тарификации. За составные вызовы списывается фиксированное количество запросов (1–2) из дневной квоты.
`get_timeseries`	Получение ограниченного временного ряда по сущности и метрике (`price`, `macro_series`, `etf_flows`, `etf_monthly_flows`) с явным указанием, применялось ли уменьшение частоты данных. `etf_flows` оценивает потоки с периодичностью подачи документов, а `etf_monthly_flows` содержит сведения о ежемесячных создании и погашении долей фонда по данным его собственных документов NPORT-P.

Эти три инструмента используют внутренний составной контур, для которого требуются учётные данные инфраструктуры, доступные только в размещённой версии. Код инструментов включён в пакет, но регистрируется только HTTP-точкой входа размещённой версии и только при наличии этих учётных данных. Команда pip install sugra-api-mcp (stdio и самостоятельно развёрнутый HTTP-сервер) всегда предоставляет классический шлюз с восемью инструментами. Примеры инструментов, доступных только в размещённой версии, во всей документации помечены соответствующим образом. Для проверки организаций по реестрам (LEI / VAT) и санкционным спискам используйте sugra_entity_lookup и sugra_entity_screen: они работают при любом типе подключения.

Набор инструментов ChatGPT

Если в initialize MCP-сеанс указывает имя клиента openai-mcp (ChatGPT) или не передаёт имя клиента, но использует User-Agent, начинающийся с этого значения, ему вместо search_endpoints, describe_endpoint, call_endpoint и fetch_data предоставляется список из 142 типизированных инструментов, а также остальные инструменты, перечисленные выше. Для каждой операции предусмотрен отдельный инструмент с именем, образованным от глагола, например get_stock_quotes или get_price_history, собственной схемой входных данных и компактным результатом. Типизированные инструменты не принимают необработанные географические данные (координаты, адреса, почтовые индексы). Некоторые типизированные инструменты могут принимать меньше входных данных, чем соответствующая операция: для get_latest_news, search_news и search_global_news_articles обязательны только тема или имя и количество результатов. Другие клиенты по-прежнему могут передавать все входные данные этих операций через call_endpoint. Из 145 определённых типизированных инструментов три перечисленных выше не отображаются в таких сеансах (CHATGPT_UNLISTED_TYPED_TOOLS в sugra_api_mcp/server.py). Сеанс не получает названий инструментов, которые ему недоступны: описания list_toolsets и list_sources не содержат подсказки о фильтрации через search_endpoints, а тексты подсказок и ресурсы sugra://skills/, которые он получает, упоминают только доступные ему инструменты. Для всех остальных клиентов перечисленные выше инструменты остаются без изменений; любой клиент по-прежнему может вызывать любой из этих инструментов по имени. Набор инструментов задан в sugra_api_mcp/catalog/data/typed_tools.json.

CLI

Запуск сервера не изменился:

sugra-api-mcp
sugra-api-mcp --transport streamable-http --port 8001

Команды для работы с каталогом и шлюзом:

sugra-api-mcp doctor
sugra-api-mcp list-toolsets
sugra-api-mcp search "NASDAQ futures"
sugra-api-mcp describe cot_financial
sugra-api-mcp call quotes_symbol_price --params '{"symbol":"AAPL"}'

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

Настройки для пользователей локальных установок, MCP-клиентов, Docker в режиме stdio и изолированных сред для каталогов (например, Glama Try in Browser). Укажите только эту переменную:

Переменная	Обязательна	Значение по умолчанию	Описание
`SUGRA_API_KEY`	Для вызовов API	-	Ваш ключ API Sugra (`sugra_...`). Получите бесплатный ключ на странице app.sugra.ai/register (бесплатный тариф: 50 запросов в день). Для запуска сервера ключ не нужен: инструменты каталога (`search_endpoints`, `describe_endpoint`, `list_toolsets`, `list_sources`) работают без него; инструменты, вызывающие API, возвращают структурированную ошибку `missing_api_key`, пока ключ не будет задан. В режиме HTTP при наличии Bearer-токена клиента ключ используется только как резервный вариант.

Необязательные параметры (не задавайте их без необходимости):

Переменная	Значение по умолчанию	Описание
`SUGRA_API_BASE`	`https://sugra.ai`	Переопределяет базовый URL API Sugra (только для самостоятельного хостинга или beta API).
`SUGRA_TIMEOUT`	`30`	Тайм-аут HTTP-запросов от этого сервера к API Sugra, в секундах.

Параметры только для операторов, использующих собственный Streamable HTTP (CORS и разрешённые хосты обратного прокси, настройка сервера авторизации OAuth и общие секреты), описаны в документации по самостоятельному хостингу. Не размещайте секреты оператора в общедоступных изолированных средах каталогов. Параметр SUGRA_MCP_TRUST_PROXY_HEADERS (по умолчанию выключен) разрешает серверу читать заголовки X-Real-IP и X-Forwarded-Host. Включайте его только за обратным прокси, который перезаписывает оба заголовка при каждом запросе. Не используйте его, если клиенты могут обращаться к процессу напрямую. Подробности приведены в том же руководстве.

Параметр SUGRA_MCP_LIMITS (по умолчанию выключен) включает ограничения на запросы, которые подсчитываются в памяти самого сервера. Настройки описаны в том же руководстве.

HTTP-транспорт с OAuth

При запуске с параметром --transport streamable-http сервер разрешает неаутентифицированные запросы MCP для обнаружения возможностей (initialize, notifications/initialized, tools/list, resources/list, prompts/list и ping). Это позволяет ChatGPT Apps и другим клиентам со смешанной аутентификацией получать метаданные инструментов. Для вызова инструментов по-прежнему требуется заголовок Authorization: Bearer .... Поддерживаются два формата токенов:

Обычный ключ API (sugra_...) — передаётся дальше в заголовке x-api-key. Совместим с ранее настроенными локальными подключениями по ключу API.
OAuth JWT — подпись проверяется с помощью JWKS издателя. Аудитория должна соответствовать https://app.sugra.ai/mcp, токен должен содержать sugra:read, а доступ к размещённому сервису проверяется через APP до получения основного ключа API пользователя. Успешные запросы с размещённым OAuth обновляют активность подключения MCP в APP.

Большинству пользователей вместо самостоятельной настройки OAuth стоит использовать размещённую конечную точку https://mcp.sugra.ai/mcp, передавая ключ API в качестве Bearer-токена. Сейчас для входа автономные OAuth-клиенты используют псевдоним https://app.sugra.ai/mcp. Если вы запускаете собственный HTTP-процесс, ознакомьтесь с документацией по самостоятельному хостингу.

Тайм-ауты и формат ошибок

SUGRA_TIMEOUT ограничивает длительность каждого HTTP-запроса от этого сервера к API Sugra (по умолчанию — 30 секунд). Это лишь одно звено в цепочке. Если вызов инструмента завершается ошибкой, поле elapsed_ms в её данных поможет определить, на каком звене возникла проблема:

размещённый прокси (app.sugra.ai) 86400s, фактически без ограничений -> этот сервер (httpx) SUGRA_TIMEOUT, по умолчанию 30s -> API Sugra -> внешние сервисы 15-60s на вызов каждого внешнего сервиса, на стороне сервера">

MCP client (agent harness)         own tool timeout, often 60-180s, client-controlled
  -> hosted proxy (app.sugra.ai)   86400s, effectively unlimited
    -> this server (httpx)         SUGRA_TIMEOUT, default 30s
      -> Sugra API -> upstreams    15-60s per upstream call, server-side

Ошибки инструментов возвращаются в виде структурированного JSON, а не исключений. Это позволяет агентам выбирать подходящую стратегию повторной попытки:

Значение `error`	Значение	Стратегия повтора
`upstream_timeout`	Ответ не получен за время, заданное `SUGRA_TIMEOUT` (`elapsed_ms` близко к `timeout_s` x 1000).	Повторите запрос один раз: прерванная попытка обычно завершается на стороне сервера и прогревает кэш внешнего сервиса. Затем сузьте запрос — уменьшите размер пакета или задайте более строгие фильтры.
`upstream_connect_error`	Не удалось подключиться к API Sugra (ошибка DNS, соединение отклонено).	Повторите запрос через небольшую паузу.
`upstream_transport_error`	Соединение прервано во время запроса.	Повторите запрос один раз.
`invalid_request_url`	Не удалось сформировать запрос. Чаще всего причина в том, что длина URL с параметрами превышает 65 536 символов; запрос не отправлялся.	Уменьшите количество параметров или сократите их значения либо разделите запрос.
`unusable_api_key`	Ключ API содержит символ, который этот сервер не может передать в заголовке запроса: символ вне ASCII, перенос строки или другой управляющий символ, а также пробел или табуляцию в начале или конце ключа. Запрос не отправлялся.	Не повторяйте запрос: ключ необходимо заменить (см. раздел «Устранение неполадок»).
`response_too_deep`	Ответ API имеет слишком глубокую вложенность, чтобы его можно было обработать, поэтому он не возвращается.	Повторите запрос один раз. Если ошибка сохраняется, сообщите о ней.
текстовое сообщение + `status_code`	API ответил с HTTP-статусом 4xx/5xx. Если API передал заголовок Retry-After, также возвращается `retry_after`.	При статусах 429/503 соблюдайте интервал `retry_after`. При статусах 4xx исправьте запрос.
`tool_execution_failed`	Непредвиденная ошибка внутри шлюза (включено поле `exception_type`).	Если ошибка сохраняется, сообщите о ней.
`query_too_long`	Запрос `search_endpoints` или `fetch_data` содержит более 64 терминов или 1000 символов (в ответ включены `max_terms` и `max_chars`). Термином считается последовательность из двух или более ASCII-букв или цифр; повторяющиеся термины учитываются. Поиск не выполнялся.	Сократите запрос до названия инструмента, ряда данных, места или задачи.
`projection_too_large`	Для проекции `fields` превышено одно из ограничений. Поле `limit_kind` указывает, какое именно: `fields` (более 32 путей), `path_chars` (путь длиннее 256 символов), `path_parts` (более 16 частей пути, разделённых точками), `rows` (обработано более 100 000 элементов списка), `shaping_ms` (обработка дольше 5 секунд) или `raw_chars` (ответ до проекции превышает 2 000 000 символов). В ответ включены поля `limit`, `actual`, `field_index` (начиная с 0, для `path_chars` и `path_parts`) и `operation_id`; текст поля не передаётся. При превышении первых трёх ограничений запрос не отправляется.	Укажите меньше полей или сократите пути, добавьте `limit`, сузьте запрос или не используйте `fields`.
`server_busy`	Достигнут предел параллельных запросов. Для общего ограничения сервера значение `scope` равно `tool_calls`, `search` или `shaping`; для ограничения на одного вызывающего — `caller_tool_calls`, `caller_search` или `caller_shaping`. Если `scope` равен `shaping` или `caller_shaping`, запрос к API уже выполнен, но его ответ отброшен. При любом другом значении `scope` обработка не выполнялась.	Повторите запрос через несколько секунд.

Во всех данных об ошибках есть поле elapsed_ms. Поле url присутствует при транспортных ошибках и ошибках HTTP, но отсутствует при tool_execution_failed: такая ошибка может возникнуть до формирования URL. Для трёх транспортных ошибок и invalid_request_url поле status_code равно null (HTTP-статус не получен). Если клиент сравнивает status_code как числовое значение, необходимо предварительно проверить, что оно не равно null. Если вместо этого вызов инструмента завершается обычным сообщением клиента без структурированного JSON, значит, сработал тайм-аут в среде агента выше этого сервера. Увеличьте тайм-аут вызова инструмента на стороне клиента, а не SUGRA_TIMEOUT.

Примеры

Спросите Claude:

«Найди фьючерсы NASDAQ среди конечных точек Sugra».
«Опиши операцию cot_financial».
«Вызови quotes_symbol_price для символа AAPL и верни только символ и цену».
«Покажи доступные наборы инструментов Sugra».

Устранение неполадок

Ищете get_market_price, get_macro_indicator или get_news? Эти названия подготовленных инструментов встречаются в некоторых старых каталогах, но в этот пакет они никогда не входили. Для запросов на естественном языке в один шаг используйте fetch_data, а для явного выбора маршрута — search_endpoints и call_endpoint.

missing_api_key в ответах инструментов

Сервер запускается и отображает список инструментов без ключа, но инструменты, вызывающие API (call_endpoint, fetch_data и инструменты для работы с сущностями), возвращают {"error": "missing_api_key"}, пока сервер не сможет найти ключ. Способ проверки зависит от того, как вы запускаете сервер:

В качестве инструмента MCP из клиента (Claude, ChatGPT, Gemini, xAI, IDE и т. д.): проверьте блок env в файле конфигурации MCP. Укажите полный ключ, например sugra_ao1_..., без пустого значения и дополнительных кавычек.
В Shell или CI: перед запуском sugra-api-mcp выполните export SUGRA_API_KEY=sugra_....
В режиме HTTP: укажите ключ в .env или EnvironmentFile для systemd, а не в Shell.

Команда sugra-api-mcp doctor показывает, виден ли ключ процессу.

unusable_api_key в ответах инструментов

В ключе, который сервер использует для вызова, есть символ, недопустимый в заголовке запроса: буква вне ASCII, невидимый символ, перевод строки или другой управляющий символ, пробел или табуляция в начале либо конце строки. Поэтому инструменты для вызова API не отправляют запрос и возвращают {"error": "unusable_api_key"}. Повторная попытка завершится так же. Действия зависят от источника ключа:

При копировании ключа в файл конфигурации или переменную окружения к нему мог добавиться невидимый символ. Скопируйте ключ заново со страницы app.sugra.ai/developer/keys.
В самом ключе может быть такой символ — он встречается в некоторых старых ключах. Замените ключ на новый на странице app.sugra.ai/developer/keys. При подключении через авторизацию (claude.ai, ChatGPT) сервер использует ключ вашей учётной записи и повторно считывает его в течение пяти минут. Если на странице нет возможности заменить ключ, напишите по адресу support@sugra.systems.

401 Unauthorized или 403 Forbidden в ответах инструментов

Ключ принят, но запрос отклонён. Возможные причины:

Вы создали новый ключ на странице app.sugra.ai/developer/keys, но в конфигурации остался старый.
Опечатка: ключ состоит только из строчных букв и цифр, без пробелов и завершающих символов новой строки.
Бесплатный тариф отключён. Войдите в систему и проверьте его статус.

429 Too Many Requests

Достигнут дневной лимит вашего тарифа. В заголовках ответа есть X-RateLimit-Reset с меткой времени в UTC, когда счётчик будет сброшен (в полночь UTC). При работе через MCP результат инструмента содержит reason: daily_limit_reached, status_code: 429, retry_after и retry_hint. В подсказке модели предлагается не вызывать инструменты для получения данных до сброса счётчика — в указанное в X-RateLimit-Reset время или в 00:00 UTC, если API не указал время сброса либо передал недопустимое значение, — и сообщить об этом пользователю. Если API указал daily_limit и plan, они также включаются в ответ. Сведения о тарифах: sugra.systems/api/pricing.

До достижения лимита результат call_endpoint или fetch_data показывает, сколько запросов осталось: meta.quota содержит limit, remaining (число запросов, оставшихся на сегодня) и resets_at, полученные из заголовков ответа API X-RateLimit-*. Если API не сообщил квоту, в результате не будет meta.quota.

Invalid Host header (только при самостоятельном размещении в режиме HTTP)

FastMCP защищает от DNS rebinding для публичных имён хостов за обратным прокси. Описание настройки разрешённых хостов см. в docs/self-hosting.md.

Результат инструмента усечён: уведомление meta.truncated

Некоторые конечные точки возвращают очень большие данные: длинные истории цен, почасовые прогнозы и полные каталоги. Результат ограничен 18,000 символами JSON с ASCII-экранированием. Поэтому символ CJK или символ с диакритическим знаком считается шестью символами — длиной его escape-последовательности, — а объём текста вне ASCII оценивается с запасом. Клиенты по-разному ограничивают объём данных, передаваемых модели: Claude Code записывает результат инструмента длиной более 50,000 символов в файл, вместо того чтобы передавать его модели, а Codex ограничивает результат по числу токенов согласно заданному пользователем бюджету и удаляет его среднюю часть, если превышен лимит. Все проверенные нами структуры данных длиной до 18,000 символов, включая самую плотную, укладывались в стандартный бюджет Codex. Однако более плотный результат или меньший бюджет, заданный в клиенте, всё равно могут быть усечены клиентом. Ограничение одинаково для всех клиентов.

Результат большего размера обрезается до установленного предела независимо от его структуры. Списки, расположенные не более чем на два уровня ниже data (data, data., data.. — имя ключа может быть любым), измеряются по записям. Большой список обрезается раньше небольших списков рядом с ним, при этом в обрезанном списке остаётся как минимум одна запись. Список сохраняет самые новые записи в соответствии с тем же правилом порядка, что и limit; если это правило неприменимо, сохраняются первые записи. При вызове через call_endpoint записи прогноза или календаря вместо этого сохраняются начиная с сегодняшнего дня — от самых старых к новым или наоборот; значение kept_end при этом равно nearest.

fetch_data выполняет операцию через call_endpoint и обрезает результат тем же способом. Значение meta.fetch_data (оно добавляется, если meta в ответе — объект или отсутствует) учитывается в общем ограничении. Обрезка выполняется в пуле обработки данных, а не в цикле событий. Если пул занят, сервер отвечает server_busy. На обрезку отводится 5 секунд; время проверяется между записями, а по его истечении результат отклоняется. Фиксированные инструменты прекращают ожидание через полсекунды после истечения этого времени, а call_endpoint — через полсекунды после истечения двух таких интервалов, поскольку для него отдельно выполняется проекция fields. В обоих случаях сервер отвечает response_too_large. Если обрезку не удалось запустить за 2 секунды ожидания пула, сервер отвечает server_busy.

Ошибки Sugra API и ошибки, возникшие при обращении к нему, ограничиваются 17,000 символами до любых последующих проверок. Это же правило применяется к отказам, которые формирует сам сервер и которые могут включать данные из запроса: неизвестный operation_id или параметр, неразрешённый путь. Если значение не помещается в отведённый объём — например, длинное сообщение API, URL или заголовок, — оно обрезается с добавлением ..., а рядом указывается _truncated: true. Ни один ключ не удаляется, поэтому статус и все короткие значения остаются без изменений.

Фиксированные инструменты проверяют тело ответа с ошибкой так же, как и любой другой результат. Если размер полезной нагрузки с ошибкой превышает ограничение, call_endpoint передаёт её без измерения.

В meta.truncated указано, что именно было обрезано: reason (exceeds_response_size_cap), path самого большого обрезанного списка с его original_count, kept_count, order и kept_end, размеры original_chars, kept_chars и cap_chars, а также запись lists для каждого пути (с kept_range — первой и последней сохранёнными датами), если обрезано несколько списков. Кроме того, retry_hint указывает, какие данные удалось сохранить, и содержит только параметры, доступные для этой операции.

В прогнозе продолжительностью примерно до двух недель сохраняются почасовые данные начиная с сегодняшнего дня и весь список daily. В подсказке предлагается указать fields=["daily"] или уменьшить params.forecast_days. Для прогноза на 16 дней могут быть удалены и последние дни. В этом случае подсказка предлагает только уменьшить params.forecast_days, хотя запрос с fields=["daily"] возвращает все 16 дней в пределах ограничения. В истории котировок сохраняются самые новые бары, а в подсказке предлагается ограничить params.limit или сузить диапазон params.start и params.end.

Если результат невозможно обрезать до допустимого размера, сервер возвращает ошибку response_too_large. В сообщении указываются размер и ограничение в символах, а также крупная часть, из-за которой результат не помещается: отдельная запись, превышающая лимит; запись, которая не помещается вместе с остальной частью ответа и уведомлением об обрезке (с указанием обоих размеров и числа других списков с такими записями); по одной записи из каждого списка, которые не помещаются только вместе (с указанием их общего размера и размера самой большой записи); либо слишком большая часть вне списков. Если возможно, в сообщении также перечисляются значения fields, которые исключают эту большую часть. Само сообщение об отказе всегда помещается в ограничение. Если это невозможно, в нём остаются только строка с размером и URL, обрезанный до 300 символов.

Python version 3.13 or higher is required

Для работы sugra-api-mcp требуется Python 3.13 или новее. Проверьте версию командой python --version. Если у вас установлена версия 3.12 или более ранняя:

Ubuntu: установите Python 3.13 или новее из пакетов дистрибутива либо через PPA deadsnakes.
macOS: brew install python@3.13
Windows: загрузите установщик с сайта python.org

Затем создайте виртуальное окружение заново.

Размещённый сервис mcp.sugra.ai/mcp возвращает ошибку 5xx

После развёртывания размещённая конечная точка может ненадолго перезапуститься. Подождите 60 секунд и повторите запрос. Если проблема не исчезнет, напишите по адресу support@sugra.systems.

Локальная отладка вызовов инструментов

Запустите сервер с использованием stdio и включите запись сообщений JSON-RPC:

&1 | tee mcp-debug.log">

SUGRA_API_KEY=sugra_... sugra-api-mcp 2>&1 | tee mcp-debug.log

Отправьте JSON-RPC вручную из второго терминала с помощью nc или инспектора MCP.

Разработка

git clone https://github.com/Sugra-Systems/sugra-api-mcp
cd sugra-api-mcp
pip install -e ".[dev,http]"
export SUGRA_API_KEY=sugra_...
python -m sugra_api_mcp  # stdio mode
python -m sugra_api_mcp --transport streamable-http --port 8001  # HTTP mode
python scripts/build_endpoint_catalog.py  # rebuild bundled catalog from sibling API openapi.json
python scripts/build_endpoint_catalog.py --source https://sugra.ai/openapi.json  # from the live spec
# On DRIFT, catalog-parity.yml opens or updates PR branch ci/catalog-resync.

Запустите тесты:

pytest

Docker

Соберите образ из корневой папки репозитория:

docker build -t sugra-api-mcp .

Запустите в режиме stdio (он используется по умолчанию) для MCP-клиентов, которые запускают локальный процесс:

docker run -i --rm -e SUGRA_API_KEY=sugra_... sugra-api-mcp

Запустите транспорт Streamable HTTP на порту 8001 с помощью Docker Compose:

export SUGRA_API_KEY=sugra_...
docker compose up -d

Затем укажите в настройках MCP-клиента адрес http://localhost:8001/mcp. Сервис Compose передаёт переменную SUGRA_API_KEY и необязательные параметры (SUGRA_API_BASE, SUGRA_TIMEOUT), если они заданы в оболочке, а также проверяет работоспособность контейнера по адресу http://localhost:8001/health. Настройки реверс-прокси и OAuth для операторов описаны в документации по самостоятельному размещению.

Каждый ответ приложения, включая сообщения об ошибках, содержит заголовок Server: sugra-api-mcp. Этот заголовок добавляется и к ответу 400, который возвращает сам uvicorn, если запрос не удаётся разобрать с помощью парсера httptools. Этот парсер устанавливается вместе с дополнительным компонентом http и используется uvicorn по умолчанию. При использовании парсера h11 ответ 400 отправляется без этого заголовка.

Чтобы добавить версию пакета в этот заголовок (sugra-api-mcp/) и в ответ /health, задайте в окружении сервера переменную SUGRA_MCP_SERVER_VERSION со значением 1 (или true, yes, on). Если переменная не задана, версия в ответе /health не указывается.

Обратите внимание на аутентификацию: в образ не встроены переменные окружения, и для запуска контейнера они не требуются. В режиме HTTP клиенты проходят аутентификацию для каждого запроса с помощью заголовка Authorization: Bearer sugra_.... Поэтому SUGRA_API_KEY, заданный для контейнера, используется только как резервный ключ для запросов без Bearer-токена.