MCP API

Обзор

MCP API Sprucely.io открывает платформу дашбордов для ИИ-ассистентов и стороннего ПО через Model Context Protocol (MCP) — открытый стандарт для подключения ИИ-моделей к инструментам по HTTP. Любой MCP-совместимый клиент может программно создавать размещённые дашборды, получать их список, просматривать их и добавлять в них данные. Дашборды, созданные через API, принадлежат вашему аккаунту и могут быть опубликованы, встроены или доработаны далее в сервисе. Инструкции по встраиванию готовых дашбордов на собственный сайт см. в разделе простая интеграция дашборда. Если вы используете Claude, быстрее всего начать работу поможет коннектор Sprucely.io.

Подключение

MCP-сервер обслуживается по протоколу Streamable HTTP по адресу:

https://www.sprucely.io/mcp

Подключиться к этому адресу может любой MCP-клиент. Например, одна команда регистрирует сервер в Claude Code:

claude mcp add --transport http sprucely https://www.sprucely.io/mcp

Сервер также можно вызывать напрямую через JSON-RPC 2.0 по HTTP. Большинство MCP-клиентов выполняют рукопожатие протокола автоматически; запрос ниже получает список доступных инструментов с использованием API-ключа:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Аутентификация

Запросы авторизуются стандартным заголовком Authorization Bearer. Поддерживаются два типа учётных данных.

API-ключи — Создавайте API-ключи в разделе MCP вашего профиля. Ключи начинаются с spr_mcp_, показываются только один раз при создании и могут быть отозваны в любой момент. Используйте их для скриптов, серверов и MCP-клиентов без графического интерфейса.

OAuth 2.1 — Интерактивные MCP-клиенты могут вместо этого позволить пользователям входить через свой аккаунт Sprucely.io по протоколу OAuth 2.1. Сервер авторизации поддерживает authorization code flow с PKCE (обязательно), refresh-токены и динамическую регистрацию клиентов, поэтому совместимые клиенты настраиваются автоматически на основе метаданных ресурса:

https://www.sprucely.io/.well-known/oauth-protected-resource

Доступные области действия (scopes): openid, offline_access, dashboards:read и dashboards:write. Области действия проверяются для каждого инструмента: create_dashboard, add_data и set_sharing требуют dashboards:write и без неё возвращают ошибку. Остальным инструментам достаточно dashboards:read.

Для клиентов, которым требуется ручная настройка, конечные точки сервера авторизации таковы:

https://www.sprucely.io/oauth/.well-known/openid-configuration — метаданные сервера авторизации
https://www.sprucely.io/oauth/auth — конечная точка авторизации (требуется PKCE)
https://www.sprucely.io/oauth/token — конечная точка токенов
https://www.sprucely.io/oauth/reg — динамическая регистрация клиентов
https://www.sprucely.io/oauth/jwks — ключи подписи (JWKS)
https://www.sprucely.io/oauth/token/revocation — отзыв токена
https://www.sprucely.io/oauth/token/introspection — интроспекция токена

Инструменты

MCP-сервер предоставляет восемь инструментов: create_dashboard, get_dashboard, list_dashboards, add_data, get_dataset_schema, set_sharing, get_embed_code и storage_status.

Параметры набора данных и дашборда ниже — не особый формат, специфичный для MCP: это тот же самый JSON набора данных/дашборда, который описан на странице формат данных и используется повсюду в сервисе (в API импорта автономной встраиваемой среды выполнения, в макетах, сгенерированных ИИ, и в редакторе дашбордов), поэтому всё, что написано применительно к этому справочнику, действует и здесь.

create_dashboard — Создаёт размещённый дашборд из встроенного набора данных и дерева виджетов и возвращает ссылки для просмотра и встраивания. Параметры:

name — название дашборда (обязательный параметр)
dataset — набор данных для визуализации: name, headers (названия столбцов), types (по одному типу базы данных на каждый заголовок — VARCHAR, BOOLEAN, INTEGER, BIGINT, FLOAT, DOUBLE, DATE или TIMESTAMP) и entries (строки, каждая в виде массива значений в порядке заголовков), до 100 столбцов и 50 000 необработанных, построчных записей за один вызов (обязательный параметр). Записи не должны быть предварительно агрегированы: отправляйте по одной строке на каждую исходную запись и позвольте dataFunction каждой диаграммы вычислять количество, суммы, средние значения и так далее непосредственно при отрисовке.
dashboard — от 1 до 40 виджетов верхнего уровня, сверху вниз (обязательный параметр). Каждый виджет — это dash_chart (тип диаграммы — area, bar, cell, dot, hexbin или line — привязки столбцов к измерениям x, y, d и r, необязательный dataFunction и необязательный заголовок), dash_table, блок dash_text, dash_spacer или контейнер dash_stacker_hor/dash_stacker_ver. Стекеры вкладываются рекурсивно — дочерние элементы стекера сами могут включать другие стекеры, — что позволяет располагать виджеты в строки и столбцы произвольной глубины вложенности. То, какие виды столбцов (категориальный, непрерывный или дата/время) принимают измерения x/y/d/r каждого типа диаграммы, и как группировка столбца с датой по периоду с помощью seasonX/seasonY делает его категориальным, описано для каждого поля через tools/list и на странице формата данных.
theme — необязательные цвета для дашборда в целом (фон, текст, основной/приглушённый/дополнительный акценты); любой виджет всё равно может переопределить собственный цвет или фон
shared — виден ли дашборд всем, у кого есть ссылка (необязательный параметр, по умолчанию false). Новые дашборды приватны, пока вы не установите значение true или не вызовете позже set_sharing.

Результат содержит dashboardId и datasetId нового дашборда (понадобятся далее для add_data, get_dataset_schema, set_sharing и get_embed_code), а также его url, viewUrl и фрагмент кода iframe для встраивания. Пример — создание дашборда со столбчатой диаграммой и общим акцентным цветом дашборда:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "create_dashboard",
      "arguments": {
        "name": "Regional Sales",
        "dataset": {
          "name": "Sales",
          "headers": ["region", "revenue"],
          "types": ["VARCHAR", "DOUBLE"],
          "entries": [
            ["North", 1250.5],
            ["South", 980.25],
            ["East", 1420.0]
          ]
        },
        "dashboard": {
          "type": "dash",
          "children": [
            { "type": "dash_chart", "chartType": "bar", "x": "region", "d": "revenue", "dataFunction": "sum", "title": "Revenue by region" }
          ]
        },
        "theme": { "themePrimary": "#6E2BDC" }
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "datasetId": "data_e5f6g7h8",
  "name": "Regional Sales",
  "shared": false,
  "rows": 3,
  "columns": 2,
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}

get_dashboard — Возвращает название дашборда, статус публикации, идентификаторы наборов данных и ссылки. Параметр: dashboardId (обязательный). Пример:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_dashboard",
      "arguments": {
        "dashboardId": "dash_a1b2c3d4"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "name": "Regional Sales",
  "shared": false,
  "archived": false,
  "datasetIds": ["data_e5f6g7h8"],
  "source": "mcp",
  "updatedAt": "2026-07-29T10:15:00.000Z",
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}

list_dashboards — Выводит список дашбордов в вашем аккаунте, отсортированный по времени последнего обновления, с собственными datasetIds для каждого — так набор данных можно сразу передать в get_dataset_schema или add_data без отдельного вызова get_dashboard. Параметры: limit и offset для постраничного вывода, query для фильтра по названию без учёта регистра (все необязательные). Пример:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "list_dashboards",
      "arguments": {
        "limit": 10,
        "query": "sales"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "total": 1,
  "limit": 10,
  "offset": 0,
  "hasMore": false,
  "dashboards": [
    {
      "dashboardId": "dash_a1b2c3d4",
      "name": "Regional Sales",
      "shared": false,
      "datasetIds": ["data_e5f6g7h8"],
      "source": "mcp",
      "updatedAt": "2026-07-29T10:15:00.000Z",
      "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
      "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
      "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
    }
  ]
}

add_data — Добавляет записи в набор данных существующего дашборда; все дашборды, использующие этот набор данных, обновляются автоматически. Параметры:

dashboardId — дашборд, в который добавляются данные (обязательный)
entries — строки, позиционно выровненные с заголовками набора данных, до 50 000 за один вызов (обязательный параметр) — действует то же правило о необработанных, построчных данных, что и для create_dashboard. Сначала вызовите get_dataset_schema, если точные названия/порядок столбцов дашборда ещё не известны. Используйте этот инструмент, чтобы загружать большие наборы данных партиями или поддерживать дашборды в актуальном состоянии.
run_id — необязательный ключ идемпотентности для конкретной партии (необязательный параметр). Если предыдущий вызов add_data с тем же dashboardId и run_id уже завершился успешно, повторный вызов вернёт тот же результат вместо повторного добавления строк — благодаря этому партию можно безопасно повторить после тайм-аута или обрыва соединения. Используйте новый run_id для каждой отдельной партии (например, UUID или хеш её содержимого).

Пример:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "add_data",
      "arguments": {
        "dashboardId": "dash_a1b2c3d4",
        "entries": [
          ["West", 875.0]
        ],
        "run_id": "batch-2026-07-29T10:20:00Z"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "datasetId": "data_e5f6g7h8",
  "addedRows": 1,
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}
# Calling again later with the same dashboardId + run_id (e.g. after a dropped
# connection) is safe: the rows are not appended twice, and the response also
# carries "duplicate": true instead of appending again.

get_dataset_schema — Возвращает названия и типы столбцов набора данных. Используйте его перед вызовом add_data (или при построении новой диаграммы на основе того же набора данных), когда точные названия/порядок/типы столбцов заранее не известны — например, в новой сессии или если дашборд создал другой агент. Параметр: datasetId (обязательный). Пример:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "get_dataset_schema",
      "arguments": {
        "datasetId": "data_e5f6g7h8"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "datasetId": "data_e5f6g7h8",
  "headers": ["region", "revenue"],
  "types": ["VARCHAR", "DOUBLE"]
}

set_sharing — Включает или отключает публичную ссылку дашборда. Отключение отзывает доступ и для всех более ранних версий дашборда, поэтому ссылка, опубликованная ранее, перестаёт работать. Параметры: dashboardId и shared (оба обязательные). Пример:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 7,
    "method": "tools/call",
    "params": {
      "name": "set_sharing",
      "arguments": {
        "dashboardId": "dash_a1b2c3d4",
        "shared": true
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "shared": true,
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}

get_embed_code — Возвращает ссылку для просмотра, которой можно поделиться, и фрагмент кода iframe для встраивания дашборда — тот же код ссылки/встраивания, который уже возвращают create_dashboard и set_sharing, на случай если он понадобится ещё раз отдельно. Ссылка работает для посторонних, только пока дашборд опубликован. Параметр: dashboardId (обязательный). Пример:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
      "name": "get_embed_code",
      "arguments": {
        "dashboardId": "dash_a1b2c3d4"
      }
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "dashboardId": "dash_a1b2c3d4",
  "shared": true,
  "url": "https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4",
  "viewUrl": "https://www.sprucely.io/service/dashboards/view/123/dash_a1b2c3d4",
  "iframe": "<iframe src=\"https://www.sprucely.io/service/dashboards/embed/123/dash_a1b2c3d4\" style=\"width:100%;height:640px;border:0\" title=\"Sprucely dashboard\" loading=\"lazy\"></iframe>"
}

storage_status — Показывает, сколько хранилища использовано в аккаунте и сколько осталось — полезно перед вызовом create_dashboard или add_data, достаточно крупным, чтобы приблизиться к лимиту хранилища тарифа. Без параметров. Пример:

curl -X POST https://www.sprucely.io/mcp \
  -H "Authorization: Bearer spr_mcp_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 9,
    "method": "tools/call",
    "params": {
      "name": "storage_status",
      "arguments": {}
    }
  }'

# Result (result.structuredContent in the JSON-RPC response):
{
  "used": 5242880,
  "limit": 104857600,
  "percent": 5,
  "plan": "Regular",
  "over": 0,
  "blocked": false
}

Лимиты и ошибки

Конечная точка MCP принимает до 25 запросов в минуту на клиента и тела запросов размером до 25 МБ — загружайте более крупные наборы данных партиями через add_data.
Наборы данных принимают до 100 столбцов и 50 000 строк за один вызов, а дашборд — до 40 виджетов на каждом уровне вложенности. Сохранённые дашборды учитываются в квоте хранилища вашего тарифа — вызовите storage_status, чтобы проверить оставшийся запас перед крупным вызовом create_dashboard или add_data.
Используются стандартные коды состояния HTTP: 401 для отсутствующих или недействительных учётных данных (с вызовом WWW-Authenticate, указывающим на метаданные ресурса), 403 для отозванных или недостаточных учётных данных, 413 для запросов избыточного размера и 429 при превышении лимита частоты запросов.