toolweave — Інструкція користувача

Версія документа: 4.1 · червень 2026
Версія сервера: v4.21 (Custom Connectors + Analytics)
Адреса: https://toolweave.dev
MCP endpoint: https://toolweave.dev/mcp

Цей документ — для звичайних користувачів toolweave.


Зміст

  1. Що таке toolweave
  2. Підключення нового користувача
  3. Робота через Dashboard
  4. Custom Connectors — власні API
  5. Підключення до різних клієнтів
  6. Що робити, якщо щось не працює
  7. Технічна довідка

1. Що таке toolweave

toolweave — це MCP gateway між Claude (або іншим LLM-клієнтом, що підтримує Model Context Protocol) та зовнішніми сервісами:

AI провайдери (60+ tools): - Anthropic Claude (opus-4.1, sonnet-4.6 — як підпровайдер для tools, не як основний LLM) - OpenAI (GPT, DALL-E, Sora-2, Whisper, TTS) - Google Gemini (2.5-pro, Imagen-4, TTS, Veo 3.1, Lyria-2) - fal.ai (Flux, Kling, Seedance, sync.so lip-sync) - Suno (генерація музики — v5) - Firecrawl (web scraping + search)

DevOps інтеграції: - GitHub (читання/комітинг коду, PR, workflow) - Railway (управління проектами, деплой, логи, env vars) - Vercel (проекти, деплої, домени, env vars, DNS records)

Фінансові API: - Alpha Vantage, Finnhub, Twelve Data (real-time квоти, історичні дані) - SEC EDGAR (фінансова звітність компаній) - Kraken (баланс, ордери, торгівля криптою)

Custom Connectors (новинка v4.21): - Підключайте будь-який REST API через AI-driven discovery - Введіть домен → toolweave знаходить документацію → opus читає → готовий connector - Ваш CRM, ваш bank, ваш SaaS — стають tools у Claude

Тобто через одну точку входу (MCP token) ви отримуєте доступ до 60+ built-in tools + необмежену кількість власних API.

Архітектура BYO (Bring Your Own Keys): ви підключаєте свої власні API-ключі до сервісів. toolweave їх зашифровано зберігає (Fernet AES) та використовує під час викликів. Ваші витрати — на ваших рахунках у відповідних провайдерів.

Пакети: ваш набір доступних провайдерів і ліміт Custom Connectors визначається пакетом, який вам призначив адмін. Подивитись свій пакет можна у /dashboard/keys.


2. Підключення нового користувача

Весь процес займає 5-10 хвилин. Для Claude Desktop — жодних файлів конфігурації редагувати не треба.

Що вам потрібно перед початком

  1. Email — на нього прийде запрошення для входу
  2. Invite-код — отримати у адміна (admin@toolweave.dev)
  3. MCP-клієнт — Claude Desktop, claude.ai web, Antigravity, Cursor, Windsurf, тощо
  4. API-ключі для сервісів, якими хочете користуватись (див. розділ 2.4)

Крок 1: Отримати invite-код

toolweave наразі працює у режимі closed beta. Реєстрація — тільки за запрошенням.

Напишіть листа на admin@toolweave.dev із вашим email. У відповідь отримаєте: - Invite-код у форматі XXXX-XXXX-XXXX-XXXX (дійсний 7 днів, одноразовий) - URL для підключення: https://toolweave.dev/mcp

Крок 2: Залогінитись на toolweave.dev

Відкрийте у браузері https://toolweave.dev/login

У формі введіть: 1. Свій email (той самий, що повідомили адміну) 2. Invite code — отриманий код 3. Натисніть Send magic link

На ваш email прийде лист від toolweave <noreply@toolweave.dev> з темою "Вхід у toolweave". Натисніть кнопку "Увійти →" у листі.

Magic link дійсний 24 години, працює тільки один раз. Браузер автоматично: - Створить ваш обліковий запис у toolweave - Перенаправить вас у dashboard

Крок 3: Підключити MCP-клієнт

Перейдіть до розділу 5 цього документа і знайдіть інструкції для вашого клієнта: - Claude Desktop — UI flow без config файлу - Antigravity, Cursor, Windsurf — manual token у config - Claude Code (CLI)claude mcp add

Крок 4: Додати свої API-ключі

Відкрийте https://toolweave.dev/dashboard/keys у браузері.

Сторінка показує три зони:

1. Admin-only (toolweave-funded): Провайдери, чиї ключі надає сам toolweave. Вам нічого додавати не треба.

2. BYO (Bring Your Own): Можете додати свій ключ. Якщо не додасте — для admin-користувачів є fallback на серверний ключ.

3. Personal (only your key): Обов'язково додайте свій ключ — fallback'у немає.

Для кожного провайдера видно: - Configured — чи додано ваш ключ (зелений індикатор) - Active source — який саме ключ зараз драйвить runtime calls (ваш чи адмінський) - 🧪 Test — кнопка перевірити роботу ключа на лайв endpoint провайдера

Де отримати ключі:

Провайдер Де отримати
anthropic https://console.anthropic.com/account/keys
openai https://platform.openai.com/api-keys
gemini https://aistudio.google.com/apikey
fal https://fal.ai/dashboard/keys
suno https://sunoapi.org
firecrawl https://firecrawl.dev/app/api-keys
github https://github.com/settings/tokens
railway https://railway.com/account/tokens
vercel https://vercel.com/account/tokens
alpha_vantage https://www.alphavantage.co/support/#api-key
finnhub https://finnhub.io/dashboard
twelve_data https://twelvedata.com/account/api-keys
kraken https://www.kraken.com/u/security/api → Create new API key (зверніть увагу, що Kraken видає два окремих рядки — публічний key і приватний secret)

Натисніть Add / Update біля провайдера, введіть значення, натисніть Save. Ключі шифруються (Fernet AES) і зберігаються у базі. Адмін НЕ бачить значення ваших ключів (тільки факт що ключ налаштовано).

Крок 5: Перевірка

У Claude напишіть:

Які провайдери toolweave у мене налаштовані?

Claude має викликати list_providers і повернути список з вашими ключами.

Або у dashboard натисніть 🧪 Тестувати на будь-якому провайдері — побачите зелений panel якщо ключ працює.

Якщо все працює — toolweave готовий.


3. Робота через Dashboard

Dashboard — це веб-інтерфейс для управління вашим обліковим записом. Доступний на https://toolweave.dev/dashboard після логіну.

Головна сторінка /dashboard

Показує: - Привітання - Поточне витрачання токенів за місяць - Місячний бюджет токенів - Назва вашого пакета - Список ваших MCP токенів - Список налаштованих API-ключів - Статистика Custom Connectors (якщо feature включено у пакеті)

/dashboard/keys — API ключі

Список провайдерів вашого пакета у трьох зонах (admin-only / byo / personal).

Для кожного провайдера: - Configured indicator — чи додано ваш ключ - Active source line — кольорова точка з підписом "активний: ваш ключ" / "адмінський ключ" / "немає" - 🧪 Test button — для testable провайдерів. Перевіряє ключ на лайв endpoint, повертає результат у зеленому/червоному panel

Дії: - Add / Update — додати або оновити ключ - Delete — видалити ключ. Після цього інструменти для цього провайдера перестануть працювати від вашого імені

/dashboard/tokens — MCP токени

Список ваших активних MCP токенів. Після підключення через Claude Desktop UI тут з'являється токен з назвою на кшталт "Claude Connector (2026-05-18 14:32 UTC)".

Дії: - Create new token — створити новий токен (для іншого пристрою чи MCP-клієнта). Plaintext показується ОДИН раз — копіюйте одразу - Revoke — відкликати токен. Після revoke токен миттєво перестає працювати

/dashboard/analytics — аналітика (новинка v4.21)

Особистий dashboard вашого використання за останні 30 днів:

/dashboard/connectors — Custom Connectors (новинка v4.21)

Управління власними конекторами. Деталі — у розділі 4.

/dashboard/lang/uk або /dashboard/lang/en

Перемикає інтерфейс на українську або англійську.

/me — JSON ваших даних

Технічний endpoint. Повертає JSON з user_id, email, мовою, бюджетом, пакетом.

Вихід

Натисніть Logout у dashboard. Cookie очиститься. Це НЕ revoke MCP-токени — клієнти продовжуватимуть працювати зі своїми токенами. Logout впливає тільки на сесію у dashboard.


4. Custom Connectors — власні API

Custom Connectors — це flagship-фіча toolweave v4.21. Дозволяє підключити будь-який REST API через AI-driven discovery, без написання JSON-конфігів.

Концепт

Замість того щоб вручну описувати endpoints, авторизацію, параметри:

  1. Ви вводите URL або просто домен
  2. toolweave запускає AI-аналіз: - opus-first: opus-4.1 перевіряє чи знає цей API з training data → готова схема - search-fallback: якщо ні, firecrawl шукає документацію → opus читає першу сторінку - multi-page exploration: opus автоматично знаходить додаткові сторінки docs → паралельний scrape → агрегація у одну схему
  3. Готовий connector з'являється у preview
  4. Додаєте API key, активуєте → доступний у Claude як rідний tool

Створення нового connector'у

  1. /dashboard/connectors/new
  2. Source URL — або повний URL до docs (https://docs.example.com/api), або просто домен (bank.gov.ua)
  3. Suggested name — slug для connector_id (опціонально, по дефолту згенерується)
  4. Hint — підказка опціонально (наприклад "fx rates" — допоможе opus сфокусуватись)
  5. 🔍 Run discovery

Бачите live progress log:

→ Перевіряю чи знаю цей API
· Не знаю цей API — шукаю документацію
→ Шукаю docs у Google
✓ Знайдено 3 сторінок на цьому домені
→ Зчитую головну сторінку
✓ Сторінка завантажена (12453 символів)
→ Аналізую сторінку, шукаю інші API-розділи
✓ Знайдено 5 endpoints на цій сторінці
· Виявлено ще 3 сторінок для додаткового аналізу
→ Завантажую 3 додаткових сторінок паралельно
✓ Завантажено 3/3 сторінок
→ Об'єдную 4 сторінок у фінальну схему
✓ Підсумок: 17 endpoints із 4 сторінок
✓ Готово! Відкриваю preview...

Час: 3 сек (opus знає API) до 90 сек (3-5 pages multi-page analysis).

Preview сторінка

Detail page connector'а

Після save — /dashboard/connectors/{id}:

Виклик з Claude

Активні connectors доступні через універсальний tool connector_call:

Claude, виклич connector "nbu" endpoint "get_exchange_rates" з параметром date=20260603

Claude знаходить ваш connector серед available, формує запит, повертає response.

Безпекові обмеження

Куди звертатись якщо щось не так


5. Підключення до різних клієнтів

Toolweave підтримує два режими підключення:

OAuth UI flow — клієнт автоматично відкриває браузер для логіну, отримує токен сам. Підтримується у Claude Desktop / Claude.ai / Claude Code.

Manual Bearer token — ви створюєте токен у dashboard, копіюєте у config клієнта. Працює з будь-яким MCP-сумісним клієнтом.

5.1 Claude Desktop (UI flow)

  1. Settings (шестерня) → Connectors
  2. Add custom connector (або Add MCP server)
  3. Name: toolweave, URL: https://toolweave.dev/mcp
  4. Connect

Claude Desktop відкриє вікно браузера. Якщо ви вже залогінені у dashboard — миттєво отримає токен. Якщо ні — пройдіть magic link flow.

5.2 Claude Desktop (manual config)

Альтернатива якщо UI flow не працює:

  1. Створіть токен у /dashboard/tokensCreate new token → скопіюйте tw_...
  2. Відкрийте config файл: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json
  3. Додайте секцію:
{
  "mcpServers": {
    "toolweave": {
      "type": "url",
      "url": "https://toolweave.dev/mcp",
      "headers": {
        "Authorization": "Bearer tw_ВАШ_ТОКЕН"
      }
    }
  }
}
  1. Повністю закрийте Claude Desktop (Quit) і відкрийте знову

5.3 Google Antigravity

Antigravity не підтримує OAuth flow, тому потрібен manual Bearer token.

Крок 1: Створіть токен у dashboard, скопіюйте tw_....

Крок 2: У Antigravity → Additional Options → MCP ServersManage MCP ServersView raw config.

Шлях config файлу: - Windows: C:\Users\<USERNAME>\.gemini\antigravity\mcp_config.json - macOS / Linux: ~/.gemini/antigravity/mcp_config.json

Крок 3: Додайте секцію:

{
  "mcpServers": {
    "toolweave": {
      "serverUrl": "https://toolweave.dev/mcp",
      "headers": {
        "Authorization": "Bearer tw_ВАШ_ТОКЕН_ТУТ"
      }
    }
  }
}

Увага: Antigravity використовує serverUrl (не url).

Крок 4: Збережіть. У Antigravity натисніть Refresh на MCP Servers.

5.4 Cursor

  1. Створіть токен у dashboard
  2. SettingsMCPAdd new MCP server
  3. Name: toolweave, Type: HTTP, URL: https://toolweave.dev/mcp
  4. Headers: Authorization: Bearer tw_ВАШ_ТОКЕН

Або вручну у ~/.cursor/mcp.json:

{
  "mcpServers": {
    "toolweave": {
      "url": "https://toolweave.dev/mcp",
      "headers": {
        "Authorization": "Bearer tw_ВАШ_ТОКЕН"
      }
    }
  }
}

5.5 Windsurf

Аналогічно Cursor — manual Bearer токен у ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "toolweave": {
      "url": "https://toolweave.dev/mcp",
      "headers": {
        "Authorization": "Bearer tw_ВАШ_ТОКЕН"
      }
    }
  }
}

5.6 Claude Code (CLI)

claude mcp add toolweave https://toolweave.dev/mcp

При першому виклику буде redirect у браузер для авторизації.

5.7 Інші MCP-клієнти

Будь-який клієнт, що підтримує Streamable HTTP transport і Bearer auth:


6. Що робити, якщо щось не працює

Antigravity / Cursor / Windsurf не може підключитись

Найчастіша причина — неправильне ім'я параметра у JSON config:

Клієнт Параметр URL
Antigravity serverUrl
Cursor url
Windsurf url
Claude Desktop urltype: "url")

Інші перевірки: - Bearer token починається з tw_ (без Bearer префіксу всередині значення) - Немає пробілів спереду/ззаду токена - URL точно https://toolweave.dev/mcp/mcp, без trailing slash) - JSON синтаксично валідний (https://jsonlint.com/) - Клієнт повністю перезапущено

Claude Desktop каже "вже є коннект з таким URL"

Причина: локальний кеш Claude Desktop тримає старий запис.

Рішення: 1. Відкрийте config файл: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.json 2. Очистіть mcpServers (або видаліть запис toolweave) 3. Повністю закрийте Claude Desktop через системний трей/menubar (Quit), не просто закрийте вікно 4. Відкрийте знову → Settings → Connectors → Add → toolweave

Причина 1: домен toolweave.dev не verified у Resend. Рішення: напишіть на admin@toolweave.dev.

Причина 2: лист потрапив у спам. Рішення: перевірте папку Спам/Junk, додайте noreply@toolweave.dev у whitelist.

Tool каже "Provider 'X' is not included in your package 'Y'"

Причина: провайдер не входить у ваш пакет.

Рішення: напишіть на admin@toolweave.dev з проханням додати цей провайдер до вашого пакета або змінити пакет.

Tool каже "Provider 'X' is disabled in your package 'Y'"

Причина: провайдер у вашому пакеті є, але адмін його вимкнув.

Рішення: напишіть на admin@toolweave.dev.

Tool каже "No personal 'X' key set"

Причина: ваш пакет вимагає особистий ключ для цього провайдера, а ви його не додали.

Рішення: додайте ключ у /dashboard/keys. Інструкція як отримати ключі — у кроці 4 розділу 2.

Tool каже "Your monthly token budget is exhausted"

Причина: ви досягли свого місячного ліміту токенів.

Рішення: напишіть на admin@toolweave.dev з проханням підняти бюджет, або зачекайте до 1 числа наступного місяця.

Custom Connector не працює після activate

  1. Перевірте чи додано API key (якщо auth type не "none")
  2. Натисніть 🧪 Test на detail page — побачите точну причину помилки
  3. Можлива причина: невірна base URL (опус помилився з discovery). Edit schema мануально через connector_update_meta (наразі через admin, у майбутніх версіях буде UI)

Discovery лімит вичерпано

Причина: ви використали усі 10 lifetime спроб на discovery нових connectors.

Рішення: напишіть на admin@toolweave.dev з проханням підняти ліміт. Зазвичай 10 достатньо для початку — якщо ви робите багато експериментів, ми збільшимо.

Клієнт підключив toolweave, але інструменти не з'являються

  1. У dashboard перевірте, чи MCP token не revoked
  2. У клієнті статус toolweave має бути "Connected" / "Running"
  3. Перезавантажте клієнт повністю (Quit + повторне відкриття)
  4. У новому чаті напишіть: "Список доступних інструментів toolweave"

Причини: - Magic link прострочений (>24 годин) - Magic link вже використаний один раз - Invite-код прострочений або використаний

Рішення: напишіть на admin@toolweave.dev, попросіть новий invite-код, або (якщо у вас вже є акаунт) натисніть "Send magic link" ще раз.

Сервер недоступний

Перевірте https://toolweave.dev/health — має повернути {"status": "ok"}.

Якщо ні — сервер недоступний, чекайте поки адмін відновить.

Якщо геть нічого не допомагає

Напишіть на admin@toolweave.dev з описом: 1. Що ви робили (точні кроки) 2. Що очікували 3. Що отримали (текст помилки, screenshot) 4. Час інциденту (приблизно) 5. Який клієнт (Claude Desktop / Antigravity / Cursor / Windsurf / Claude Code)


7. Технічна довідка

Структура URL (для користувачів)

Шлях Призначення
/ Лендінг (UA/EN switcher)
/login Сторінка логіну
/dashboard Головна користувача
/dashboard/keys API-ключі (3 zones + test buttons)
/dashboard/tokens MCP-токени
/dashboard/analytics Аналітика використання
/dashboard/connectors Custom Connectors
/dashboard/connectors/new Створити новий connector
/mcp MCP endpoint (для клієнтів)
/me JSON ваших даних
/info JSON версії сервера
/health Статус сервера
/docs/user-guide Цей документ
/docs/ai-guide Інструкція для AI-агентів
/docs/terms Terms of Service
/docs/privacy Privacy Policy

Авторизація MCP-клієнта

Два варіанти Bearer token у заголовку Authorization:

Тип Формат Як отримати
Per-user OAuth tw_xxxxxxxx UI flow Claude Desktop (автоматично)
Per-user manual tw_xxxxxxxx /dashboard/tokens → Create new token

Доступні MCP-tools (60+)

Залежить від вашого пакета. Повний список доступних на сервері:

AI text: anthropic_chat, openai_chat, gemini_text

AI image: openai_image, gemini_image, fal_image

AI video: openai_video_* (Sora-2), gemini_video_* (Veo 3.1), fal_image_to_video_* (Kling)

AI audio: openai_tts, openai_transcribe, gemini_tts, suno_music_* (v5)

Lip-sync: fal_lipsync_* (sync.so v2)

Web tools: firecrawl_scrape, firecrawl_search, firecrawl_crawl_*

GitHub: 11 tools — github_get_repo, github_get_file, github_list_files, github_commit_file, github_create_branch, github_create_pr, github_list_prs, github_get_pr, github_list_commits, github_list_workflow_runs, github_get_workflow_logs

Railway: 17 tools — projects, services, deployments, logs, env vars, domains, volumes

Vercel: 17 tools — projects, deployments, domains, DNS, env vars

Фінансові: av_* (Alpha Vantage — quote, time_series, indicators), fh_* (Finnhub — quote, news, profile, recommendations, earnings), td_* (Twelve Data — quote, exchange_rate, time_series, statistics, market_state), sec_* (SEC EDGAR — financial_summary, recent_filings, company_facts, ticker_lookup)

Kraken: 18 tools — system_status, ticker, ohlc, depth, balance, open_orders, closed_orders, add_order, cancel_order, trade_volume

Custom Connectors: connector_list, connector_describe, connector_call

Utility: upload_media, get_usage_stats, list_providers, list_video_jobs

Список і опис кожного — викличте у Claude: "Покажи доступні toolweave tools".

Безпекові обмеження

Шифрування

Token-based billing

З v4.19 використовуємо tokens як уніфіковану одиницю замість USD. Кожна дія коштує фіксовану кількість токенів:

Точні ціни — у pricing.py на сервері. Ваш бюджет видно у /dashboard.

Email доставка

Magic links доставляє Resend з адреси noreply@toolweave.dev.

Контакти


Цей документ актуальний для toolweave v4.21. Перевірте https://toolweave.dev/info для актуальної версії сервера.