MCP API'er

Oversigt

Sprucely.ios MCP API’er eksponerer dashboardplatformen for AI-assistenter og tredjepartssoftware via Model Context Protocol (MCP), en åben standard til at forbinde AI-modeller med værktøjer over HTTP. Enhver MCP-kompatibel klient kan oprette hostede dashboards, liste og undersøge dem samt programmatisk tilføje data til dem. Dashboards oprettet via API’erne tilhører din konto og kan deles, indlejres eller redigeres yderligere i tjenesten. For at indlejre de færdige dashboards på din egen side, se noterne om enkel dashboard-integration. Bruger du Claude, er den hurtigste vej i gang Sprucely.io-konnektoren.

Forbindelse

MCP-serveren serveres over Streamable HTTP på:

https://www.sprucely.io/mcp

Enhver MCP-klient kan forbinde til dette endpoint. Eksempelvis registrerer én kommando serveren i Claude Code:

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

Du kan også kalde serveren direkte med JSON-RPC 2.0 over HTTP. De fleste MCP-klienter udfører protokol-håndtrykket automatisk; anmodningen nedenfor lister de tilgængelige værktøjer ved hjælp af en API-nøgle:

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"}'

Autentificering

Anmodninger godkendes med en standard Authorization Bearer-header. To typer af legitimationsoplysninger understøttes.

API-nøgler - Opret API-nøgler i MCP-sektionen af din profil. Nøgler starter med spr_mcp_, vises kun én gang ved oprettelse, og kan tilbagekaldes når som helst. Brug dem til scripts, servere og headless MCP-klienter.

OAuth 2.1 - Interaktive MCP-klienter kan i stedet lade brugere logge ind med deres Sprucely.io-konto via OAuth 2.1. Autorisationsserveren understøtter authorization code-flowet med PKCE (påkrævet), refresh tokens og dynamisk klientregistrering, så kompatible klienter selv konfigurerer sig automatisk ud fra ressourcemetadataene:

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

Tilgængelige scopes: openid, offline_access, dashboards:read og dashboards:write. Scopes håndhæves pr. værktøj: create_dashboard, add_data og set_sharing kræver dashboards:write og returnerer en fejl uden det. De øvrige værktøjer har kun brug for dashboards:read.

For klienter, der kræver manuel konfiguration, er autorisationsserverens endpoints:

https://www.sprucely.io/oauth/.well-known/openid-configuration - autorisationsserverens metadata
https://www.sprucely.io/oauth/auth - autorisationsendpoint (PKCE påkrævet)
https://www.sprucely.io/oauth/token - token-endpoint
https://www.sprucely.io/oauth/reg - dynamisk klientregistrering
https://www.sprucely.io/oauth/jwks - signeringsnøgler (JWKS)
https://www.sprucely.io/oauth/token/revocation - tilbagekaldelse af tokens
https://www.sprucely.io/oauth/token/introspection - token-introspektion

Værktøjer

MCP-serveren eksponerer otte værktøjer: create_dashboard, get_dashboard, list_dashboards, add_data, get_dataset_schema, set_sharing, get_embed_code og storage_status.

Dataset- og dashboard-parametrene nedenfor er ikke et MCP-specifikt format - det er nøjagtig den samme dataset-/dashboard-JSON, der er dokumenteret på Dataformat-siden og bruges alle andre steder i tjenesten (den selvstændige, indlejrbare runtimes import-API, AI-genererede layouts og dashboard-editoren), så alt, der er skrevet mod den reference, gælder også her.

create_dashboard - Opretter et hostet dashboard ud fra et integreret datasæt og et widget-træ, og returnerer visnings- og indlejringslinks. Parametre:

name - dashboardets titel (påkrævet)
dataset - det datasæt, der skal visualiseres: name, headers (kolonnenavne), types (én databasetype pr. header - VARCHAR, BOOLEAN, INTEGER, BIGINT, FLOAT, DOUBLE, DATE eller TIMESTAMP) og entries (rækker, hver et array af værdier i header-rækkefølge), op til 100 kolonner og 50.000 rå entries på rækkeniveau pr. kald (påkrævet). Entries må ikke være foraggregerede: send én række pr. underliggende post, og lad hvert diagrams dataFunction beregne optællinger, summer, gennemsnit og lignende ved gengivelsen.
dashboard - 1 til 40 widgets på øverste niveau, fra top til bund (påkrævet). Hver widget er en dash_chart (en diagramtype - area, bar, cell, dot, hexbin eller line - kolonnetilknytninger for x, y, d og r, en valgfri dataFunction og en valgfri titel), en dash_table, en dash_text-blok, en dash_spacer, eller en dash_stacker_hor/dash_stacker_ver-beholder. Stakke kan indlejres rekursivt - en staks egne underelementer kan indeholde yderligere stakke - for at arrangere widgets i rækker og kolonner af vilkårlig dybde. Hvilke kolonnetyper (kategoriske, kontinuerlige eller dato/tid) hver diagramtypes x/y/d/r-dimensioner accepterer, og hvordan tidsopdeling af en datokolonne med seasonX/seasonY gør den kategorisk, er dokumenteret for hvert felt via tools/list og på Dataformat-siden.
theme - valgfrie dashboard-brede farver (baggrund, tekst, primære/subtile/sekundære accenter); enhver widget kan stadig tilsidesætte sin egen farve eller baggrund
shared - om dashboardet kan ses af alle med linket (valgfri, standard false). Nye dashboards er private, indtil du sætter denne til true eller kalder set_sharing bagefter.

Resultatet indeholder det nye dashboards dashboardId og datasetId (nødvendige for add_data, get_dataset_schema, set_sharing og get_embed_code bagefter), samt dets url, viewUrl og iframe-indlejringssnippet. Eksempel - opret et dashboard med et søjlediagram og en dashboard-bred accentfarve:

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 - Returnerer et dashboards navn, delingsstatus, datasæt-id’er og links. Parameter: dashboardId (påkrævet). Eksempel:

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 - Lister dashboards i din konto, sorteret efter seneste opdatering, hver med sine egne datasetIds, så et datasæt kan sendes direkte til get_dataset_schema eller add_data uden et separat get_dashboard-kald. Parametre: limit og offset til paginering, query til et navnefilter, der ikke skelner mellem store og små bogstaver (alle valgfrie). Eksempel:

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 - Tilføjer entries til et eksisterende dashboards datasæt; alle dashboards, der bruger datasættet, opdateres automatisk. Parametre:

dashboardId - dashboardet, der skal tilføjes til (påkrævet)
entries - rækker justeret positionsmæssigt til datasættets headers, op til 50.000 pr. kald (påkrævet) - den samme regel om rå entries på rækkeniveau, som gælder for create_dashboard. Kald get_dataset_schema først, hvis du ikke allerede kender dashboardets nøjagtige kolonnenavne/-rækkefølge. Brug det til at indlæse store datasæt i batches eller til at holde dashboards opdaterede.
run_id - en valgfri idempotensnøgle for denne specifikke batch (valgfri). Hvis et tidligere add_data-kald med samme dashboardId og run_id allerede lykkedes, returnerer et gentaget kald det tidligere resultat i stedet for at tilføje rækkerne endnu en gang, så en batch trygt kan forsøges igen efter en timeout eller afbrudt forbindelse - brug en ny run_id pr. forskellig batch (f.eks. et UUID eller en hash af dens indhold).

Eksempel:

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 - Returnerer et datasæts kolonnenavne og -typer. Brug det, før du kalder add_data (eller bygger et nyt diagram mod det samme datasæt), når de nøjagtige kolonnenavne/rækkefølge/typer ikke allerede kendes, f.eks. i en ny session eller når en anden agent har oprettet dashboardet. Parameter: datasetId (påkrævet). Eksempel:

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 - Slår et dashboards offentlige link til eller fra. At slå det fra tilbagekalder også adgangen for enhver tidligere revision af dashboardet, så et link, der tidligere er blevet delt, holder op med at virke. Parametre: dashboardId og shared (begge påkrævet). Eksempel:

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 - Returnerer det delbare visningslink og en iframe-indlejringssnippet for et dashboard - det samme link/den samme indlejringskode, som create_dashboard og set_sharing allerede returnerer, til når de skal bruges igen for sig selv. Linket virker kun for andre, så længe dashboardet er delt. Parameter: dashboardId (påkrævet). Eksempel:

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 - Rapporterer, hvor meget lagerplads kontoen har brugt, og hvor meget der er tilbage, nyttigt før et create_dashboard- eller add_data-kald, der er stort nok til at risikere at overskride abonnementets lagergrænse. Ingen parametre. Eksempel:

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
}

Grænser og fejl

MCP-endpointet accepterer 25 anmodninger pr. minut pr. klient og anmodningsindhold på op til 25 MB - indlæs større datasæt i add_data-batches.
Datasæt accepterer op til 100 kolonner og 50.000 rækker pr. kald, og et dashboard accepterer op til 40 widgets på hvert indlejringsniveau. Gemte dashboards tæller med i abonnementets lagerkvote - kald storage_status for at tjekke resterende plads før et stort create_dashboard- eller add_data-kald.
Der bruges standard HTTP-statuskoder: 401 for manglende eller ugyldige legitimationsoplysninger (med en WWW-Authenticate-udfordring, der peger på ressourcemetadataene), 403 for tilbagekaldte eller utilstrækkelige legitimationsoplysninger, 413 for for store anmodninger og 429 ved rate limiting.