Сервер MCP

basedb надає сервер MCP (POST /mcp, за тією самою адресою, що й інтерфейс): агент — Claude, асистент для програмування, ваш власний агент — знаходить там бази, читає й записує рядки, видаляє їх з вашого дозволу, та пропонує зміни структури.

Підключення агента

Створіть токен у Токени API і MCP… (меню бази, розділ API та агенти), позначивши доступ MCP. Той самий токен працює і для REST API, і для MCP, і відкриває всю базу: її продакшн та інші середовища (див. нижче).

Покладіть токен у змінну середовища BASEDB_TOKEN, ніколи у файл конфігурації. Клієнт, що працює з MCP через HTTP, — зокрема Claude Code, — звертається безпосередньо до …/mcp із заголовком Authorization: Bearer <jeton>. З Claude Code:

claude mcp add --transport http --scope project basedb "http://localhost:3000/mcp" \
  --header 'Authorization: Bearer ${BASEDB_TOKEN}'

Команда записує файл .mcp.json проєкту, де ${BASEDB_TOKEN} лишається посиланням на змінну: самого токена там немає.

{
  "mcpServers": {
    "basedb": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer ${BASEDB_TOKEN}" }
    }
  }
}

Клієнт, який уміє запускати лише локальні програми (stdio), працює через ретранслятор з репозиторію, що читає токен зі змінної, яку називає --token-env:

claude mcp add basedb -- node <dépôt basedb>/apps/mcp/dist/relay.js \
  --url http://localhost:3000/mcp --token-env BASEDB_TOKEN

Потім попросіть агента викликати whoami: він скаже, хто створив токен, яку базу той відкриває, які в нього середовища та дозволи.

Вибір середовища

База може мати кілька середовищ — продакшн, тестування, розробка, — кожне зі своїми таблицями й рядками. Токен на всю базу відкриває їх усі, а середовище вибирається — від найширшого способу до найточнішого:

• назва бази без будь-чого іншого: crm — це продакшн, crm_recette — тестування;

• адреса сервера: …/mcp?environment=recette націлює на тестування все з’єднання. Ретранслятор робить те саме з --environment recette. Так оголошують по одному серверу на кожне середовище, усі з тим самим токеном:

  {
    "mcpServers": {
      "basedb": {
        "type": "http",
        "url": "http://localhost:3000/mcp",
        "headers": { "Authorization": "Bearer ${BASEDB_TOKEN}" }
      },
      "basedb-recette": {
        "type": "http",
        "url": "http://localhost:3000/mcp?environment=recette",
        "headers": { "Authorization": "Bearer ${BASEDB_TOKEN}" }
      }
    }
  }

• аргумент environment кожного інструмента, що називає базу, — для одного виклику: list_records з {"base": "crm", "table": "clients", "environment": "recette"}.

Середовище називається за його значком, без урахування регістру й діакритичних знаків (Recette, recette, developpement для «Développement»), або через production. whoami перелічує ті, які відкриває токен; list_bases і describe_base показують, до якого середовища належить кожна база.

Токен також можна обмежити одним середовищем під час створення: тоді він не бачить жодного іншого.

П’ятнадцять інструментів

Інструмент	Призначення
whoami	хто цей агент, з якими дозволами, у яких середовищах
list_bases, describe_base, describe_table	дослідити структуру, її описи та зовнішній вигляд
list_records, get_record, lookup_records	читати, фільтрувати, знаходити рядок за значенням відображення
create_record, update_record	записувати рядки
delete_record, restore_record	видалити рядок — токеном, створеним для цього, — і повернути його
propose_create_table, propose_add_field, get_proposal	запропонувати зміну структури
propose_update_look	запропонувати колір і піктограму таблиці та її варіантів

Кольори та піктограми

Таблиця та кожен варіант списку вибору мають колір і піктограму, як в інтерфейсі. Агент вибирає їх, коли пропонує:

• propose_create_table приймає color і icon для таблиці;
• propose_add_field приймає color і icon для кожного варіанта select або multi_select;
• propose_update_look змінює їх для наявної таблиці та її варіантів: пропущений ключ залишає наявне значення, null стирає його.

color — це колір #rrggbb. icon — назва піктограми Lucide з тих, які малює інтерфейс, — truck, circle-check, flame…: схема інструмента перелічує їх, а невідома назва відхиляється. describe_base і describe_table повертають поточний зовнішній вигляд. Натомість поле не має піктограми для вибору: інтерфейс малює піктограму його типу.

Видалення рядків

Токен, створений із правами Читання, запис і видалення, дозволяє агенту видаляти рядки, по одному, за їхнім _id. delete_record повертає рядок таким, яким він був, а видалення історизується від імені токена; restore_record повертає рядок під тим самим _id — агент сам виправляє свою помилку, а людина може зробити те саме з історії.

Агент не видаляє:

• токеном на читання або на читання й запис: відмова каже, який токен створити;
• рядок, який каскадний зв’язок забрав би разом з іншими (TOKEN_CASCADE_FORBIDDEN): таке видалення виконується в інтерфейсі, людиною, яка бачить, що воно забирає;
• кілька рядків одразу: жоден інструмент цього не робить.

Чого агент не робить

• Він видаляє лише з вашого дозволу: токен, створений для цього, і лише по одному рядку.
• Він не змінює структуру — ні її зовнішній вигляд: він її пропонує. Пропозиція чекає в Пропозиції агентів… (меню бази), де людина, яка керує структурою, схвалює або відхиляє її; без рішення вона спливає через 24 години.
• Він ніколи не має більше дозволів, ніж людина, яка створила його токен: дозволи токена перетинаються з її дозволами, середовище за середовищем.
• Він не бачить полів, позначених як невидимі для агентів, ані баз, закритих для MCP.

Кожен виклик журналюється за формою його параметрів, але ніколи — за їхніми значеннями.