РазделПодключить свой ИИ: адрес сервера и вход

Подключить свой ИИ: адрес сервера и вход

Как подключить к Syncra Claude, ChatGPT, Cursor или своего агента: адрес сервера, вход от имени человека, отключение и запросы OAuth для тех, кто пишет программу сам.

К Syncra можно подключить ИИ-приложение: Claude, ChatGPT, Cursor или собственного агента. Подключение идёт по MCP (Model Context Protocol) — это открытый стандарт, по которому ИИ-приложение вызывает действия внешнего сервиса. После подключения приложение читает и пишет в Syncra от имени человека, который его подключил, и с его правами. Подключить приложение может любой участник рабочего пространства. Роль администратора не нужна, ключ в настройках создавать не нужно: человек входит в Syncra в браузере и нажимает «Разрешить».

Адрес сервера

https://ai-syncra.ru/api/mcp

Этот же адрес показывает сама Syncra. Откройте окно «Настройки»: оно открывается из меню аккаунта в боковой панели или сочетанием Cmd+, на macOS и Ctrl+, на Windows и Linux. Перейдите в раздел «Подключённые приложения». В группе «Подключить приложение» рядом с адресом есть кнопка «Копировать».

Свойство Значение
Транспорт MCP Streamable HTTP. Сессий нет, сервер отвечает обычным JSON
Вход OAuth 2.1: код авторизации с PKCE (только S256) и ключ обновления
Область доступа Одна: mcp
Ключ доступа Начинается с syncat_, действует 3600 секунд
Ключ обновления Начинается с syncrt_, действует 90 дней и меняется при каждом использовании

Что получает приложение

  • Приложение действует от имени человека. Оно видит каналы, личные сообщения, задачи и страницы базы знаний, которые видит этот человек, и может писать сообщения, создавать и менять задачи и страницы.
  • Доступ распространяется на все рабочие пространства этого человека. Режима «только чтение» и доступа к одному пространству нет.
  • Ключ доступа открывает только /api/mcp. Остальные адреса Syncra его не принимают.
  • Приложение не может само выдать доступ другому приложению: «Разрешить» нажимает только человек.
  • Сообщение, отправленное приложением, не отмечает чаты человека прочитанными.

Список действий по группам — на странице Инструменты для ИИ.

Как проходит подключение

  1. Человек копирует адрес в Syncra: «Настройки», раздел «Подключённые приложения», кнопка «Копировать».
  2. В ИИ-приложении он добавляет новое удалённое MCP-подключение и вставляет адрес. Если приложение спрашивает тип, это Streamable HTTP.
  3. Приложение открывает браузер на странице Syncra. Если человек не вошёл в аккаунт, Syncra попросит войти.
  4. Открывается страница разрешения. В её заголовке стоит название приложения и слова «просит работать в Syncra от вашего имени». Ниже написано «Вы вошли как» и адрес почты, рядом есть ссылка «Другой аккаунт». Строка «После ответа вы вернётесь на …» называет, куда уйдёт браузер: сайт приложения, а для приложения на компьютере — адрес с его собственной схемой, например cursor, или локальный адрес.
  5. Человек нажимает «Разрешить». Браузер возвращается в приложение, и в нём появляются инструменты Syncra. Кнопка «Отклонить» доступа не даёт.

На странице есть предупреждение: «Разрешайте, только если вы сами только что начали подключать Syncra в этом приложении.» Если запрос появился неожиданно, нажмите «Отклонить».

Ссылка на страницу разрешения действует 15 минут и срабатывает один раз. После этого страница покажет «Запрос устарел», и подключение нужно начать в приложении заново.

Шаги для Claude, ChatGPT и Cursor

Меню этих приложений меняют их разработчики, поэтому названия пунктов у вас могут отличаться. Ниже — порядок действий. Если пункт называется иначе, ищите слова «коннекторы» или «MCP».

Claude

  1. Откройте настройки Claude и раздел с коннекторами.
  2. Добавьте свой коннектор: введите имя, например Syncra, и вставьте адрес https://ai-syncra.ru/api/mcp.
  3. Запустите подключение. Claude откроет страницу Syncra, на ней нажмите «Разрешить».

В Claude Code сервер добавляют командой в терминале:

claude mcp add --transport http syncra https://ai-syncra.ru/api/mcp

Затем в Claude Code выполните команду /mcp, выберите syncra и пройдите вход в браузере.

ChatGPT

  1. Откройте настройки ChatGPT и раздел с коннекторами.
  2. Создайте новый коннектор, вставьте адрес https://ai-syncra.ru/api/mcp как адрес MCP-сервера и выберите вход через OAuth.
  3. ChatGPT откроет страницу Syncra, на ней нажмите «Разрешить».

Если в настройках нет пункта для своего коннектора, посмотрите справку ChatGPT: возможность добавлять свои коннекторы зависит от тарифа и настроек самого ChatGPT.

Cursor

  1. Откройте файл .cursor/mcp.json в папке проекта. Чтобы сервер был доступен во всех проектах, используйте ~/.cursor/mcp.json.
  2. Добавьте сервер:
{
  "mcpServers": {
    "syncra": {
      "url": "https://ai-syncra.ru/api/mcp"
    }
  }
}
  1. В настройках Cursor, в списке MCP-серверов, начните вход для syncra. Откроется страница Syncra, на ней нажмите «Разрешить».

Как отключить приложение

Откройте «Настройки», раздел «Подключённые приложения». Под заголовком «ИИ-приложения, которые работают от вашего имени» перечислены подключённые приложения. В каждой строке написано, когда приложение подключено и когда им пользовались в последний раз, либо «ещё не пользовалось». Нажмите «Отключить». Приложение теряет доступ сразу. Чтобы вернуть его, подключите заново.

Приложение может и само отказаться от доступа: для этого есть запрос POST /api/oauth/revoke, он описан ниже.

Свой агент: вход по OAuth

Claude, ChatGPT, Cursor и другие готовые приложения проходят вход сами: им достаточно адреса сервера. Этот раздел нужен, если вы сами пишете программу, которая подключается к Syncra. Дальше она называется клиентом. Порядок такой: узнать адреса, зарегистрировать клиента, отправить человека на страницу разрешения, обменять код на ключи, обновлять ключ доступа.

Регистрация клиента открыта: её не подтверждает команда Syncra. Доступ даёт человек на странице разрешения.

GET /.well-known/oauth-protected-resource/api/mcp

Сообщает, какой сервер авторизации защищает /api/mcp. Тот же ответ приходит по адресу /.well-known/oauth-protected-resource.

curl "https://ai-syncra.ru/.well-known/oauth-protected-resource/api/mcp"

Ответ 200:

{
  "resource": "https://ai-syncra.ru/api/mcp",
  "authorization_servers": ["https://ai-syncra.ru"],
  "scopes_supported": ["mcp"],
  "bearer_methods_supported": ["header"],
  "resource_name": "Syncra"
}

GET /.well-known/oauth-authorization-server

Возвращает адреса и возможности сервера авторизации.

curl "https://ai-syncra.ru/.well-known/oauth-authorization-server"

Ответ 200:

{
  "issuer": "https://ai-syncra.ru",
  "authorization_endpoint": "https://ai-syncra.ru/api/oauth/authorize",
  "token_endpoint": "https://ai-syncra.ru/api/oauth/token",
  "registration_endpoint": "https://ai-syncra.ru/api/oauth/register",
  "revocation_endpoint": "https://ai-syncra.ru/api/oauth/revoke",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none", "client_secret_post", "client_secret_basic"],
  "revocation_endpoint_auth_methods_supported": ["none", "client_secret_post", "client_secret_basic"],
  "scopes_supported": ["mcp"],
  "authorization_response_iss_parameter_supported": true
}

POST /api/oauth/register

Регистрирует клиента и возвращает его client_id.

Параметр Тип Обязателен Описание
redirect_uris массив строк да От 1 до 10 адресов возврата, каждый до 2000 символов. Правила ниже
client_name строка нет Название приложения, его человек видит на странице разрешения. До 200 символов. Если не передать, Syncra возьмёт хост первого адреса возврата
client_uri строка нет Адрес сайта приложения
token_endpoint_auth_method строка нет Как клиент подтверждает себя при обмене кода: none, client_secret_post или client_secret_basic. По умолчанию client_secret_basic
grant_types массив строк нет Допустимы только authorization_code и refresh_token
response_types массив строк нет Допустим только code

Правила для адреса возврата:

  • https — любой хост;
  • http — только localhost, 127.0.0.1 и [::1]. Порт при входе может быть любым;
  • собственная схема приложения, например myapp://callback, разрешена;
  • схемы javascript:, data:, file:, vbscript:, blob: и about: запрещены;
  • части после # в адресе быть не должно.
curl -X POST "https://ai-syncra.ru/api/oauth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My agent",
    "redirect_uris": ["https://agent.example.com/callback"],
    "token_endpoint_auth_method": "none"
  }'

Ответ 201:

{
  "client_id": "syncc_...",
  "client_id_issued_at": 1762732800,
  "client_name": "My agent",
  "redirect_uris": ["https://agent.example.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none",
  "scope": "mcp"
}

Клиент с методом none секрета не получает: его подтверждает пара code_verifier и code_challenge (PKCE), она описана в следующем разделе. Для методов client_secret_post и client_secret_basic в ответе есть ещё два поля: "client_secret": "syncs_..." и "client_secret_expires_at": 0. Секрет показывается только в этом ответе.

Ошибка приходит с кодом 400, например:

{
  "error": "invalid_redirect_uri",
  "error_description": "redirect_uris must list 1 to 10 URLs."
}

GET /api/oauth/authorize

Начинает вход: на этот адрес ваше приложение отправляет браузер человека.

Параметр Тип Обязателен Описание
response_type строка да Всегда code
client_id строка да Идентификатор из ответа регистрации
redirect_uri строка да, если у клиента больше одного адреса возврата Должен совпадать с зарегистрированным. Для http на локальном адресе порт может отличаться
code_challenge строка да SHA-256 от code_verifier в кодировке base64url, от 43 до 128 символов из набора A-Z, a-z, 0-9, -, _
code_challenge_method строка да Всегда S256
state строка нет Вернётся в адресе возврата без изменений
scope строка нет Допустимо только mcp
resource строка нет Если передан, должен указывать на /api/mcp этого сервера

code_verifier и code_challenge можно получить так:

VERIFIER=$(openssl rand -base64 60 | tr -d '=+/\n' | cut -c1-64)
CHALLENGE=$(printf '%s' "$VERIFIER" | openssl dgst -sha256 -binary | openssl base64 | tr '+/' '-_' | tr -d '=\n')

Адрес, который нужно открыть в браузере:

https://ai-syncra.ru/api/oauth/authorize?response_type=code&client_id=syncc_...&redirect_uri=https%3A%2F%2Fagent.example.com%2Fcallback&code_challenge=<CHALLENGE>&code_challenge_method=S256&state=<STATE>&scope=mcp&resource=https%3A%2F%2Fai-syncra.ru%2Fapi%2Fmcp

Syncra отвечает кодом 302, а при превышении лимита — кодом 429. Куда уйдёт браузер, зависит от запроса.

Запрос в порядке. Браузер попадает на страницу разрешения https://ai-syncra.ru/oauth/consent?request=<id>. Когда человек нажал «Разрешить», браузер уходит на адрес возврата с кодом:

https://agent.example.com/callback?code=syncode_...&state=<STATE>&iss=https%3A%2F%2Fai-syncra.ru

Человек нажал «Отклонить». Браузер уходит на адрес возврата с ошибкой:

https://agent.example.com/callback?error=access_denied&error_description=The+person+declined.&state=<STATE>&iss=https%3A%2F%2Fai-syncra.ru

Клиент известен, но не подошёл другой параметр, например code_challenge или scope. Браузер сразу уходит на адрес возврата с такими же параметрами error и error_description, страницу разрешения человек не видит.

Syncra не знает такого client_id либо адрес возврата не зарегистрирован. Тогда браузер в приложение не возвращается: человек видит страницу «Ссылка для подключения не работает».

Код из адреса возврата действует 10 минут и срабатывает один раз.

POST /api/oauth/token

Обменивает код на ключи и обновляет ключ доступа. Тело запроса — форма (application/x-www-form-urlencoded), JSON тоже принимается.

Параметр Тип Обязателен Описание
grant_type строка да authorization_code или refresh_token
code строка для authorization_code Код из адреса возврата
code_verifier строка для authorization_code Строка, из которой получен code_challenge: от 43 до 128 символов из набора A-Z, a-z, 0-9, -, ., _, ~
redirect_uri строка нет Если передан, должен совпадать с адресом из запроса на вход
refresh_token строка для refresh_token Действующий ключ обновления
client_id строка да Идентификатор клиента. Клиент с методом client_secret_basic передаёт его в заголовке
client_secret строка для client_secret_post Секрет клиента

Клиент подтверждает себя тем способом, который выбрал при регистрации. Метод none: только client_id в теле. Метод client_secret_post: client_id и client_secret в теле. Метод client_secret_basic: заголовок Authorization: Basic со строкой client_id:client_secret в base64. Другой способ вернёт 401 с ошибкой invalid_client.

Обмен кода:

curl -X POST "https://ai-syncra.ru/api/oauth/token" \
  -d "grant_type=authorization_code" \
  -d "code=syncode_..." \
  -d "code_verifier=$VERIFIER" \
  --data-urlencode "redirect_uri=https://agent.example.com/callback" \
  -d "client_id=syncc_..."

Ответ 200:

{
  "access_token": "syncat_...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "syncrt_...",
  "scope": "mcp"
}

Обновление ключа доступа:

curl -X POST "https://ai-syncra.ru/api/oauth/token" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=syncrt_..." \
  -d "client_id=syncc_..."

Ответ 200 той же формы: новый ключ доступа и новый ключ обновления. Старый ключ обновления больше не действует, сохраняйте новый.

Если код или уже использованный ключ обновления предъявить второй раз, Syncra отзывает весь доступ приложения, и человеку придётся подключить его заново. Повторный код или ключ означает, что его могли украсть, поэтому сервер закрывает доступ целиком.

Ошибка приходит с кодом 400, например:

{
  "error": "invalid_grant",
  "error_description": "The code is invalid or was already used."
}

POST /api/oauth/revoke

Отзывает доступ приложения. Достаточно любого из двух ключей пары: отзывается подключение целиком.

Параметр Тип Обязателен Описание
token строка да Ключ доступа или ключ обновления
client_id строка да Идентификатор клиента. Клиент подтверждает себя так же, как при обмене кода
curl -X POST "https://ai-syncra.ru/api/oauth/revoke" \
  -d "token=syncrt_..." \
  -d "client_id=syncc_..."

Ответ 200 с пустым телом. Неизвестный ключ ошибкой не считается.

Первый вызов

POST /api/mcp

Принимает один запрос MCP в формате JSON-RPC 2.0 и возвращает ответ в JSON.

Заголовок Обязателен Значение
Authorization да Bearer syncat_...
Content-Type да application/json
Accept да application/json, text/event-stream. Оба типа требует транспорт MCP, хотя сервер всегда отвечает JSON
curl -X POST "https://ai-syncra.ru/api/mcp" \
  -H "Authorization: Bearer syncat_..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_workspaces","arguments":{}}}'

Ответ 200:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      { "type": "text", "text": "..." }
    ]
  }
}

В поле text лежит ответ Syncra в виде строки с JSON: её нужно разобрать ещё раз. Метод tools/list возвращает список инструментов с описанием параметров. Как устроены вызовы и ошибки инструментов, описано на странице Инструменты для ИИ.

Код Тело ответа Что случилось
401 {"error":"invalid_token"} Заголовка Authorization нет, ключ неверный, истёк или отозван. В заголовке ответа WWW-Authenticate есть resource_metadata с адресом описания сервера
405 {"error":"method_not_allowed"} Запрос методом GET или DELETE. Сервер принимает только POST
406 ошибка JSON-RPC с кодом -32000 В заголовке Accept нет application/json или text/event-stream

Получив 401, обновите ключ доступа. Если не действует и ключ обновления, человек отключил приложение или доступ отозван: начните вход заново.

Ошибки OAuth

Ошибки регистрации, обмена и отзыва приходят в одной форме: {"error":"<код>","error_description":"<текст>"}. Код ответа 400, для invalid_client — 401.

Ошибка Где встречается Что значит
invalid_redirect_uri регистрация Адрес возврата не проходит правила
invalid_client_metadata регистрация Тело не JSON-объект либо в нём недопустимый метод, тип доступа или тип ответа
invalid_client обмен, отзыв Неизвестный client_id либо клиент подтвердил себя не так, как при регистрации
invalid_request вход, обмен Не хватает обязательного параметра либо PKCE задан неверно
invalid_grant обмен Код или ключ обновления неверный, истёк, уже использован или выдан другому клиенту
unsupported_grant_type обмен grant_type не authorization_code и не refresh_token
unsupported_response_type вход response_type не code
invalid_scope вход Запрошена область, отличная от mcp
invalid_target вход resource не указывает на /api/mcp
access_denied вход Человек нажал «Отклонить»

Ошибки входа приходят не телом ответа, а параметрами error и error_description в адресе возврата.

Ограничения

Адрес Лимит
POST /api/oauth/register 20 запросов в час с одного IP-адреса
GET /api/oauth/authorize 60 запросов в минуту с одного IP-адреса
POST /api/oauth/token 120 запросов в минуту с одного IP-адреса
POST /api/oauth/revoke 60 запросов в минуту с одного IP-адреса

Сверх лимита сервер отвечает 429 с телом {"error":"Too many requests"}. Заголовка Retry-After в ответе нет.

Чего нет:

  • областей доступа, кроме mcp: доступа «только чтение» или к одному рабочему пространству;
  • входа без человека: потоков client credentials, implicit и device;
  • кабинета разработчика для регистрации приложений. Клиент регистрируется запросом POST /api/oauth/register;
  • сессий, потоковых ответов и уведомлений от сервера к клиенту;
  • ресурсов и промптов MCP. Сервер отдаёт только инструменты.

Адрес /api/mcp, адреса описания сервера и запросы регистрации, обмена и отзыва можно вызывать из браузера с любого сайта: сервер отвечает с заголовком Access-Control-Allow-Origin: *.