Подключить свой ИИ: адрес сервера и вход
Как подключить к 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 его не принимают. - Приложение не может само выдать доступ другому приложению: «Разрешить» нажимает только человек.
- Сообщение, отправленное приложением, не отмечает чаты человека прочитанными.
Список действий по группам — на странице Инструменты для ИИ.
Как проходит подключение
- Человек копирует адрес в Syncra: «Настройки», раздел «Подключённые приложения», кнопка «Копировать».
- В ИИ-приложении он добавляет новое удалённое MCP-подключение и вставляет адрес. Если приложение спрашивает тип, это Streamable HTTP.
- Приложение открывает браузер на странице Syncra. Если человек не вошёл в аккаунт, Syncra попросит войти.
- Открывается страница разрешения. В её заголовке стоит название приложения и слова «просит работать в Syncra от вашего имени». Ниже написано «Вы вошли как» и адрес почты, рядом есть ссылка «Другой аккаунт». Строка «После ответа вы вернётесь на …» называет, куда уйдёт браузер: сайт приложения, а для приложения на компьютере — адрес с его собственной схемой, например
cursor, или локальный адрес. - Человек нажимает «Разрешить». Браузер возвращается в приложение, и в нём появляются инструменты Syncra. Кнопка «Отклонить» доступа не даёт.
На странице есть предупреждение: «Разрешайте, только если вы сами только что начали подключать Syncra в этом приложении.» Если запрос появился неожиданно, нажмите «Отклонить».
Ссылка на страницу разрешения действует 15 минут и срабатывает один раз. После этого страница покажет «Запрос устарел», и подключение нужно начать в приложении заново.
Шаги для Claude, ChatGPT и Cursor
Меню этих приложений меняют их разработчики, поэтому названия пунктов у вас могут отличаться. Ниже — порядок действий. Если пункт называется иначе, ищите слова «коннекторы» или «MCP».
Claude
- Откройте настройки Claude и раздел с коннекторами.
- Добавьте свой коннектор: введите имя, например Syncra, и вставьте адрес
https://ai-syncra.ru/api/mcp. - Запустите подключение. Claude откроет страницу Syncra, на ней нажмите «Разрешить».
В Claude Code сервер добавляют командой в терминале:
claude mcp add --transport http syncra https://ai-syncra.ru/api/mcp
Затем в Claude Code выполните команду /mcp, выберите syncra и пройдите вход в браузере.
ChatGPT
- Откройте настройки ChatGPT и раздел с коннекторами.
- Создайте новый коннектор, вставьте адрес
https://ai-syncra.ru/api/mcpкак адрес MCP-сервера и выберите вход через OAuth. - ChatGPT откроет страницу Syncra, на ней нажмите «Разрешить».
Если в настройках нет пункта для своего коннектора, посмотрите справку ChatGPT: возможность добавлять свои коннекторы зависит от тарифа и настроек самого ChatGPT.
Cursor
- Откройте файл
.cursor/mcp.jsonв папке проекта. Чтобы сервер был доступен во всех проектах, используйте~/.cursor/mcp.json. - Добавьте сервер:
{
"mcpServers": {
"syncra": {
"url": "https://ai-syncra.ru/api/mcp"
}
}
}
- В настройках 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: *.