MCP API

Przegląd

Interfejsy API MCP Sprucely.io udostępniają platformę dashboardów asystentom AI i oprogramowaniu zewnętrznemu za pośrednictwem Model Context Protocol (MCP) - otwartego standardu łączenia modeli AI z narzędziami przez HTTP. Każdy klient zgodny z MCP może programowo tworzyć hostowane dashboardy, wyświetlać ich listę, sprawdzać ich szczegóły oraz dopisywać do nich dane. Dashboardy utworzone przez te API należą do Twojego konta i można je udostępniać, osadzać lub dalej edytować w serwisie. Aby osadzić powstałe dashboardy na własnej stronie, zapoznaj się z notatkami na temat prostej integracji dashboardu. Jeśli korzystasz z Claude, najszybszym sposobem, by zacząć, jest konektor Sprucely.io.

Połączenie

Serwer MCP jest dostępny przez Streamable HTTP pod adresem:

https://www.sprucely.io/mcp

Każdy klient MCP może połączyć się z tym punktem końcowym. Na przykład jedno polecenie rejestruje serwer w Claude Code:

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

Możesz też wywołać serwer bezpośrednio za pomocą JSON-RPC 2.0 przez HTTP. Większość klientów MCP przeprowadza uzgadnianie protokołu automatycznie; poniższe żądanie wyświetla listę dostępnych narzędzi przy użyciu klucza 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"}'

Uwierzytelnianie

Żądania są autoryzowane za pomocą standardowego nagłówka Authorization Bearer. Obsługiwane są dwa typy poświadczeń.

Klucze API - Twórz klucze API w sekcji MCP swojego profilu. Klucze zaczynają się od spr_mcp_, są widoczne tylko raz, w momencie utworzenia, i można je unieważnić w dowolnej chwili. Używaj ich w skryptach, na serwerach i w klientach MCP bez interfejsu użytkownika (headless).

OAuth 2.1 - Interaktywne klienty MCP mogą zamiast tego pozwolić użytkownikom zalogować się na konto Sprucely.io za pomocą OAuth 2.1. Serwer autoryzacji obsługuje przepływ kodu autoryzacji z PKCE (wymagane), tokeny odświeżania oraz dynamiczną rejestrację klienta, dzięki czemu zgodne klienty konfigurują się automatycznie na podstawie metadanych zasobu:

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

Dostępne zakresy: openid, offline_access, dashboards:read i dashboards:write. Zakresy są egzekwowane dla każdego narzędzia osobno: create_dashboard, add_data i set_sharing wymagają dashboards:write i bez niego zwracają błąd. Pozostałe narzędzia potrzebują wyłącznie dashboards:read.

Dla klientów wymagających ręcznej konfiguracji, punkty końcowe serwera autoryzacji są następujące:

https://www.sprucely.io/oauth/.well-known/openid-configuration - metadane serwera autoryzacji
https://www.sprucely.io/oauth/auth - punkt końcowy autoryzacji (wymagane PKCE)
https://www.sprucely.io/oauth/token - punkt końcowy tokenów
https://www.sprucely.io/oauth/reg - dynamiczna rejestracja klienta
https://www.sprucely.io/oauth/jwks - klucze podpisujące (JWKS)
https://www.sprucely.io/oauth/token/revocation - unieważnianie tokenów
https://www.sprucely.io/oauth/token/introspection - introspekcja tokenów

Narzędzia

Serwer MCP udostępnia osiem narzędzi: create_dashboard, get_dashboard, list_dashboards, add_data, get_dataset_schema, set_sharing, get_embed_code i storage_status.

Poniższe parametry dataset i dashboard nie są formatem specyficznym dla MCP - to dokładnie ten sam JSON zbioru danych/dashboardu, opisany na stronie format danych i używany wszędzie indziej w serwisie (w API importu samodzielnego, osadzalnego środowiska uruchomieniowego, w układach generowanych przez AI oraz w edytorze dashboardów), więc wszystko, co napisano względem tamtego dokumentu referencyjnego, dotyczy również tego miejsca.

create_dashboard - Tworzy hostowany dashboard z wbudowanego zbioru danych i drzewa widżetów oraz zwraca linki do podglądu i osadzenia. Parametry:

name - tytuł dashboardu (wymagane)
dataset - zbiór danych do zwizualizowania: name, headers (nazwy kolumn), types (jeden typ bazy danych na każdy nagłówek - VARCHAR, BOOLEAN, INTEGER, BIGINT, FLOAT, DOUBLE, DATE lub TIMESTAMP) oraz entries (wiersze, każdy jako tablica wartości w kolejności nagłówków), do 100 kolumn i 50 000 surowych wpisów na poziomie wiersza na wywołanie (wymagane). Wpisy nie mogą być wstępnie zagregowane: wyślij jeden wiersz na każdy rekord źródłowy, a policzenie sum, średnich itd. pozostaw funkcji dataFunction danego wykresu w momencie renderowania.
dashboard - od 1 do 40 widżetów najwyższego poziomu, od góry do dołu (wymagane). Każdy widżet to dash_chart (typ wykresu - area, bar, cell, dot, hexbin lub line - mapowania kolumn dla x, y, d i r, opcjonalna dataFunction i opcjonalny tytuł), dash_table, blok dash_text, dash_spacer lub kontener dash_stacker_hor/dash_stacker_ver. Kontenery typu stacker zagnieżdżają się rekurencyjnie - dzieci kontenera mogą same zawierać kolejne kontenery - dzięki czemu widżety można układać w wiersze i kolumny o dowolnej głębokości. To, jakie rodzaje kolumn (kategoryczne, ciągłe lub data/czas) przyjmują wymiary x/y/d/r danego typu wykresu, oraz w jaki sposób grupowanie kolumny czasowej w powtarzający się okres za pomocą seasonX/seasonY czyni ją kategoryczną, jest udokumentowane przy każdym polu poprzez tools/list oraz na stronie Format danych.
theme - opcjonalne kolory obowiązujące dla całego dashboardu (tło, tekst, akcenty podstawowy/subtelny/drugorzędny); każdy widżet może mimo to nadpisać własny kolor lub tło
shared - czy dashboard jest widoczny dla każdego, kto ma link (opcjonalne, domyślnie false). Nowe dashboardy są prywatne, dopóki nie ustawisz tej wartości na true lub nie wywołasz później set_sharing.

Wynik zawiera dashboardId i datasetId nowego dashboardu (potrzebne później do add_data, get_dataset_schema, set_sharing i get_embed_code), a także jego url, viewUrl oraz fragment kodu do osadzenia iframe. Przykład - utworzenie dashboardu z wykresem słupkowym i akcentem kolorystycznym obowiązującym dla całego dashboardu:

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 - Zwraca nazwę dashboardu, status udostępniania, identyfikatory zbiorów danych oraz linki. Parametr: dashboardId (wymagane). Przykład:

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 - Zwraca listę dashboardów na Twoim koncie, uporządkowaną według ostatniej aktualizacji, każdy z własnym polem datasetIds, dzięki czemu zbiór danych można przekazać bezpośrednio do get_dataset_schema lub add_data bez osobnego wywołania get_dashboard. Parametry: limit i offset do stronicowania, query do filtrowania po nazwie bez rozróżniania wielkości liter (wszystkie opcjonalne). Przykład:

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 - Dopisuje wpisy do zbioru danych istniejącego dashboardu; każdy dashboard korzystający z tego zbioru danych odświeża się automatycznie. Parametry:

dashboardId - dashboard, do którego mają zostać dopisane dane (wymagane)
entries - wiersze dopasowane pozycyjnie do nagłówków zbioru danych, do 50 000 na wywołanie (wymagane) - obowiązuje ta sama zasada surowych wpisów na poziomie wiersza, co w create_dashboard. Jeśli nie znasz jeszcze dokładnych nazw/kolejności kolumn dashboardu, wywołaj najpierw get_dataset_schema. Użyj tego narzędzia, aby wczytywać duże zbiory danych partiami lub aktualizować dashboardy na bieżąco.
run_id - opcjonalny klucz idempotencji dla tej konkretnej partii (opcjonalne). Jeśli wcześniejsze wywołanie add_data z tym samym dashboardId i run_id już się powiodło, kolejne wywołanie zwraca ten sam poprzedni wynik zamiast ponownie dopisywać wiersze, dzięki czemu partię można bezpiecznie ponowić po przekroczeniu limitu czasu lub zerwaniu połączenia - dla każdej odrębnej partii użyj nowego run_id (na przykład UUID lub skrótu jej zawartości).

Przykład:

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 - Zwraca nazwy i typy kolumn zbioru danych. Użyj go przed wywołaniem add_data (lub przed zbudowaniem nowego wykresu na tym samym zbiorze danych) za każdym razem, gdy dokładne nazwy/kolejność/typy kolumn nie są jeszcze znane, na przykład w nowej sesji lub gdy dashboard utworzył inny agent. Parametr: datasetId (wymagane). Przykład:

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 - Włącza lub wyłącza publiczny link dashboardu. Wyłączenie go cofa dostęp również do każdej wcześniejszej wersji dashboardu, więc link udostępniony w przeszłości przestaje działać. Parametry: dashboardId i shared (oba wymagane). Przykład:

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 - Zwraca link do podglądu dashboardu przeznaczony do udostępniania oraz fragment kodu iframe do jego osadzenia - ten sam link/kod osadzenia, który zwracają już create_dashboard i set_sharing, przydatny, gdy potrzebujesz ich ponownie, osobno. Link działa dla innych osób tylko wtedy, gdy dashboard jest udostępniony. Parametr: dashboardId (wymagane). Przykład:

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 - Zwraca informację o tym, ile pamięci wykorzystało konto i ile jej pozostało - przydatne przed wywołaniem create_dashboard lub add_data na tyle dużym, że mogłoby zbliżyć się do limitu pamięci Twojego planu. Brak parametrów. Przykład:

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
}

Limity i błędy

Punkt końcowy MCP przyjmuje 25 żądań na minutę na klienta oraz treści żądań o rozmiarze do 25 MB - większe zbiory danych wczytuj partiami za pomocą add_data.
Zbiory danych przyjmują do 100 kolumn i 50 000 wierszy na wywołanie, a dashboard przyjmuje do 40 widżetów na każdym poziomie zagnieżdżenia. Zapisane dashboardy wliczają się do limitu pamięci Twojego planu - wywołaj storage_status, aby sprawdzić dostępną jeszcze przestrzeń przed dużym wywołaniem create_dashboard lub add_data.
Używane są standardowe kody stanu HTTP: 401 przy brakujących lub nieprawidłowych poświadczeniach (z wyzwaniem WWW-Authenticate wskazującym na metadane zasobu), 403 przy unieważnionych lub niewystarczających poświadczeniach, 413 przy zbyt dużych żądaniach i 429 przy przekroczeniu limitu żądań.