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/mcp

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 true). Nowe dashboardy są publiczne, dopóki nie ustawisz tej wartości na false 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 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.
Każdy problem z poświadczeniami - brakujące, wygasłe, unieważnione lub nieprawidłowe z innego powodu - zwraca kod 401 wraz z wyzwaniem WWW-Authenticate wskazującym metadane zasobu, dzięki czemu klient wie, że ma się ponownie uwierzytelnić, zamiast przerywać pracę. Pozostałe kody to 413 dla zbyt dużych żądań, 429 przy ograniczeniu liczby żądań (z nagłówkiem Retry-After), 405 dla żądania GET lub DELETE (transport jest bezstanowy: nie ma samodzielnego strumienia SSE do otwarcia ani sesji do zakończenia, więc wysyłaj każde żądanie metodą POST) oraz 503, gdy poświadczeń nie da się w danej chwili zweryfikować.
Błędy zwracane, zanim wywołanie dotrze do narzędzia, są obiektami błędu JSON-RPC 2.0. Narzędzie, które zostanie uruchomione i dopiero potem zakończy się niepowodzeniem - nieznany identyfikator dashboardu, brakujący zakres uprawnień, brak miejsca w magazynie - zwraca natomiast zwykły wynik z ustawionym isError i wyjaśnieniem w treści.