MCP-интеграция

Подключите AI-ассистентов через один общий URL Basalt MCP.

Обзор

Что такое MCP?

MCP (Model Context Protocol) — открытый стандарт для подключения AI-ассистентов к внешним источникам данных. Basalt предоставляет один общий remote MCP endpoint, через который AI-инструменты — Codex, Claude Code, Cursor, VS Code и другие — могут работать с реальными данными вашей студии напрямую.

Вместо того чтобы вручную копировать детали проектов в чат, ваш AI-ассистент может сам обращаться к проектам, задачам и заметкам по запросу, а также создавать и обновлять записи.

URL MCP

URL Basalt MCP: https://basaltpms.com/api/mcp. Он одинаковый для всех студий и не содержит company_id.

Также можно открыть Настройки → Интеграции → MCP и скопировать URL или готовую команду/конфиг для нужного клиента. Авторизовать MCP-доступ могут только пользователи с ролью Администратор или Владелец. При первом подключении AI-клиент откроет окно браузера для OAuth — войдите в аккаунт Basalt, выберите студию и одобрите запрошенные разрешения.

Доступные инструменты

Инструменты чтения (mcp:read)

Доступны с областью mcp:read и предоставляют доступ к данным студии только для чтения:

Инструмент	Описание
`search`	Полнотекстовый поиск по проектам, задачам и заметкам
`fetch`	Получить ресурс по URL
`list_projects`	Список проектов студии с фильтрами
`get_project`	Полные данные проекта
`list_todos`	Список задач с фильтрами: статус, приоритет, исполнитель
`get_todo`	Полные данные задачи, включая подзадачи
`list_notes`	Список заметок студии
`get_note`	Содержимое заметки

Инструменты записи (mcp:write)

Требуют область mcp:write и применяют ту же систему ролей, что и интерфейс Basalt. Операции удаления через MCP недоступны.

Инструмент	Описание
`create_todo`	Создать задачу (требуется роль менеджера или выше)
`update_todo`	Обновить задачу (менеджер+ или автор/исполнитель)
`complete_todo`	Отметить задачу выполненной
`create_project`	Создать проект (требуется роль менеджера или выше)
`update_project`	Обновить детали проекта (менеджер+)
`create_note`	Создать заметку
`update_note`	Обновить заметку (владелец или доступ shared-edit)

Настройка клиента

Быстрая настройка из Basalt

Общий endpoint: https://basaltpms.com/api/mcp. Самый простой путь — скопировать готовую команду или конфиг из Настройки → Интеграции → MCP; Basalt показывает готовые варианты для Codex, Claude Code, Cursor и VS Code.

После подключения клиента OAuth откроется в браузере и попросит выбрать аккаунт Basalt и студию, к которой будет привязан этот клиент.

Codex

Добавьте Basalt один раз из терминала:

codex mcp add basalt --url 'https://basaltpms.com/api/mcp'

Если ваш Codex-клиент отдельно запрашивает вход, выполните codex mcp login basalt. OAuth откроется в браузере и попросит выбрать аккаунт Basalt и студию.

Claude Code

Добавьте Basalt как user-scoped MCP-сервер, чтобы он был доступен во всех проектах:

claude mcp add --transport http basalt --scope user 'https://basaltpms.com/api/mcp'

Затем выполните /mcp внутри Claude Code, чтобы завершить OAuth-аутентификацию и выбрать студию.

Claude Desktop и Claude.ai

Для удалённых MCP-серверов используйте UI подключений, а не файл конфигурации:

Откройте Customize → Connectors
Нажмите Add custom connector
Вставьте общий URL Basalt MCP
Нажмите Connect и завершите OAuth в браузере

Для организационных планов администратор пространства может предварительно разрешить пользовательские подключения.

Cursor

Добавьте Basalt в глобальный конфиг Cursor MCP по пути ~/.cursor/mcp.json:

{"mcpServers":{"basalt":{"url":"https://basaltpms.com/api/mcp"}}}

Затем выполните следующую команду для аутентификации, либо добавьте этот же URL через Cursor Settings → MCP:

cursor-agent mcp login basalt

Windsurf

Откройте Windsurf Settings → Cascade → MCP Servers → Add Server
Выберите Streamable HTTP
Вставьте общий URL Basalt MCP
Завершите OAuth в браузере

VS Code / GitHub Copilot

Откройте Command Palette (Cmd/Ctrl+Shift+P)
Выполните MCP: Add Server
Выберите Workspace или Global
Вставьте общий URL Basalt MCP и завершите OAuth

Cline и Gemini CLI

Cline

cline mcp add basalt 'https://basaltpms.com/api/mcp' --type http

Gemini CLI

gemini mcp add -s user -t http basalt 'https://basaltpms.com/api/mcp'

Оба клиента запрашивают OAuth при первом подключении к серверу.

Права и безопасность

Области доступа

При авторизации выберите нужный уровень доступа:

mcp:read — только чтение: просмотр и поиск проектов, задач и заметок
mcp:write — дополнительно позволяет создавать и обновлять записи (с учётом вашей роли в студии)

Расширить область доступа без повторной авторизации невозможно. Токен обновления всегда использует исходную область.

Отзыв доступа

Чтобы остановить локальный доступ, удалите или отключите Basalt MCP-сервер внутри AI-клиента.

Basalt также аннулирует MCP-доступ, когда пользователь выходит из студии или теряет требуемую роль Администратора/Владельца. Серверный отзыв доступа аннулирует access tokens, refresh tokens и authorization codes для затронутого клиента; последующие вызовы инструментов вернут ошибку 401.

Лимиты и текущие ограничения

Лимиты запросов:

Любой вызов инструмента: 120 в минуту на клиент и IP
Вызовы инструментов записи: 30 в минуту на пользователя и IP

Текущие ограничения:

Одна выбранная студия на выданный токен
Инструменты портала и финансов недоступны
Операции удаления не поддерживаются