MCP API-er

Oversikt

Sprucely.io MCP API-ene eksponerer dashbordplattformen for AI-assistenter og tredjepartsprogramvare gjennom Model Context Protocol (MCP), en åpen standard for å koble AI-modeller til verktøy over HTTP. Enhver MCP-kompatibel klient kan opprette hostede dashboard, liste dem opp og se detaljene deres, og legge til data i dem programmatisk. Dashboard opprettet via API-ene tilhører kontoen din og kan deles, bygges inn eller redigeres videre i tjenesten. For å bygge de resulterende dashboardene inn på ditt eget nettsted, se notatene om enkel dashboard-integrasjon. Hvis du bruker Claude, kommer du raskest i gang med Sprucely.io-koblingen.

Tilkobling

MCP-serveren tilbys over Streamable HTTP på:

https://www.sprucely.io/mcp

Enhver MCP-klient kan koble til dette endepunktet. Ett eksempel: én kommando registrerer serveren i Claude Code:

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

Du kan også kalle serveren direkte med JSON-RPC 2.0 over HTTP. De fleste MCP-klienter utfører protokollhåndtrykket automatisk; forespørselen nedenfor lister de tilgjengelige verktøyene ved hjelp av en API-nøkkel:

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

Autentisering

Forespørsler autoriseres med en standard Authorization Bearer-header. To typer legitimasjon støttes.

API-nøkler - Opprett API-nøkler i MCP-delen av profilen din. Nøkler starter med spr_mcp_, vises kun én gang ved opprettelse, og kan tilbakekalles når som helst. Bruk dem for skript, servere og skjermløse MCP-klienter.

OAuth 2.1 - Interaktive MCP-klienter kan i stedet la brukere logge inn med Sprucely.io-kontoen sin gjennom OAuth 2.1. Autorisasjonsserveren støtter autorisasjonskode-flyten med PKCE (påkrevd), oppdateringstoken og dynamisk klientregistrering, slik at kompatible klienter konfigurerer seg selv automatisk ut fra ressursmetadataene:

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

Tilgjengelige scopes: openid, offline_access, dashboards:read og dashboards:write. Scopes håndheves per verktøy: create_dashboard, add_data og set_sharing krever dashboards:write og returnerer en feil uten det. De øvrige verktøyene trenger bare dashboards:read.

For klienter som krever manuell konfigurasjon, er autorisasjonsserverens endepunkter:

https://www.sprucely.io/oauth/.well-known/openid-configuration - metadata for autorisasjonsserveren
https://www.sprucely.io/oauth/auth - autorisasjonsendepunkt (PKCE påkrevd)
https://www.sprucely.io/oauth/token - token-endepunkt
https://www.sprucely.io/oauth/reg - dynamisk klientregistrering
https://www.sprucely.io/oauth/jwks - signeringsnøkler (JWKS)
https://www.sprucely.io/oauth/token/revocation - tilbakekalling av token
https://www.sprucely.io/oauth/token/introspection - token-introspeksjon

Verktøy

MCP-serveren eksponerer åtte verktøy: create_dashboard, get_dashboard, list_dashboards, add_data, get_dataset_schema, set_sharing, get_embed_code og storage_status.

Datasett- og dashboard-parametrene nedenfor er ikke et MCP-spesifikt format - de er nøyaktig den samme datasett-/dashboard-JSON-en som er dokumentert på siden for Dataformat og brukt overalt ellers i tjenesten (den frittstående, innbyggbare runtimens import-API, AI-genererte oppsett, og dashboard-editoren), så alt som er skrevet mot den referansen, gjelder også her.

create_dashboard - Oppretter et hostet dashboard fra et innebygd datasett og et widget-tre, og returnerer visnings- og innbyggingslenker. Parametre:

name - dashboardets tittel (påkrevd)
dataset - datasettet som skal visualiseres: name, headers (kolonnenavn), types (én databasetype per kolonneoverskrift - VARCHAR, BOOLEAN, INTEGER, BIGINT, FLOAT, DOUBLE, DATE eller TIMESTAMP) og entries (rader, hver et array av verdier i kolonneoverskriftenes rekkefølge), opptil 100 kolonner og 50 000 rå oppføringer på radnivå per kall (påkrevd). Oppføringene må ikke være forhåndsaggregerte: send én rad per underliggende post, og la hvert diagrams dataFunction beregne antall, summer, gjennomsnitt og så videre ved rendring.
dashboard - 1 til 40 widgets på øverste nivå, ovenfra og ned (påkrevd). Hver widget er enten en dash_chart (en diagramtype - area, bar, cell, dot, hexbin eller line - kolonnetilordninger for x, y, d og r, en valgfri dataFunction og en valgfri tittel), en dash_table, en dash_text-blokk, en dash_spacer, eller en dash_stacker_hor/dash_stacker_ver-beholder. Stablere nøstes rekursivt - en stablers egne children kan inneholde ytterligere stablere - for å ordne widgets i rader og kolonner med vilkårlig dybde. Hvilke kolonnetyper (kategorisk, kontinuerlig eller dato/tid) hver diagramtypes x/y/d/r-dimensjoner godtar, og hvordan tidsgruppering av en datokolonne med seasonX/seasonY gjør den kategorisk, er dokumentert på hvert felt via tools/list og på siden for Dataformat.
theme - valgfrie farger for hele dashboardet (bakgrunn, tekst, primær-/subtil-/sekundær-aksenter); enhver widget kan likevel overstyre sin egen farge eller bakgrunn
shared - om dashboardet kan vises av alle med lenken (valgfritt, standard false). Nye dashboard er private helt til du setter denne til true eller kaller set_sharing i etterkant.

Resultatet inneholder det nye dashboardets dashboardId og datasetId (som trengs av add_data, get_dataset_schema, set_sharing og get_embed_code i etterkant), samt dets url, viewUrl og iframe-innbyggingskode. Eksempel - opprett et dashboard med et stolpediagram og en aksentfarge for hele dashboardet:

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, datasett-IDer og lenker. Parameter: dashboardId (påkrevd). 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 dashboardene i kontoen din, sortert etter sist oppdatert, hver med sin egen datasetIds slik at et datasett kan sendes direkte til get_dataset_schema eller add_data uten et separat get_dashboard-kall. Parametre: limit og offset for paginering, query for et navnefilter uten skille mellom store og små bokstaver (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 - Legger til oppføringer i datasettet til et eksisterende dashboard; hvert dashboard som bruker datasettet, oppdateres automatisk. Parametre:

dashboardId - dashboardet det skal legges til i (påkrevd)
entries - rader plassert i samme rekkefølge som datasettets kolonneoverskrifter, opptil 50 000 per kall (påkrevd) - samme regel om rå oppføringer på radnivå som for create_dashboard gjelder. Kall get_dataset_schema først hvis du ikke allerede kjenner dashboardets eksakte kolonnenavn/-rekkefølge. Bruk den til å laste inn store datasett i batcher eller til å holde dashboard oppdatert.
run_id - en valgfri idempotensnøkkel for denne spesifikke batchen (valgfritt). Hvis et tidligere add_data-kall med samme dashboardId og run_id allerede lyktes, returnerer et nytt kall det tidligere resultatet i stedet for å legge til radene en gang til, slik at en batch trygt kan gjøres på nytt etter en tidsavbrudd eller mistet tilkobling - bruk en ny run_id per distinkte batch (for eksempel en UUID eller en hash av innholdet).

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 datasetts kolonnenavn og -typer. Bruk den før du kaller add_data (eller bygger et nytt diagram mot samme datasett) når de eksakte kolonnenavnene/-rekkefølgen/-typene ikke allerede er kjent, for eksempel i en ny økt eller når en annen agent opprettet dashboardet. Parameter: datasetId (påkrevd). 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 lenke av eller på. Å slå den av opphever også tilgangen for hver tidligere revisjon av dashboardet, slik at en lenke som ble delt tidligere, slutter å fungere. Parametre: dashboardId og shared (begge påkrevd). 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 den delbare visningslenken og en iframe-innbyggingskode for et dashboard - samme lenke/innbyggingskode som create_dashboard og set_sharing allerede returnerer, for når de trengs igjen på egen hånd. Lenken fungerer bare for andre så lenge dashboardet er delt. Parameter: dashboardId (påkrevd). 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 mye lagringsplass kontoen har brukt og hvor mye som gjenstår, nyttig før et create_dashboard- eller add_data-kall som er stort nok til å risikere å nå abonnementets lagringsgrense. 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
}

Grenser og feil

MCP-endepunktet godtar 25 forespørsler per minutt per klient og forespørselskropper på opptil 25 MB - last inn større datasett i add_data-batcher.
Datasett godtar opptil 100 kolonner og 50 000 rader per kall, og et dashboard godtar opptil 40 widgets på hvert nestingsnivå. Lagrede dashboard telles mot abonnementets lagringskvote - kall storage_status for å sjekke gjenværende kapasitet før et stort create_dashboard- eller add_data-kall.
Standard HTTP-statuskoder brukes: 401 for manglende eller ugyldig legitimasjon (med en WWW-Authenticate-utfordring som peker til ressursmetadataene), 403 for tilbakekalt eller utilstrekkelig legitimasjon, 413 for forespørsler som er for store, og 429 ved hastighetsbegrensning.