MCP-API:er

Översikt

Sprucely.ios MCP-API:er exponerar dashboardplattformen för AI-assistenter och tredjepartsprogram via Model Context Protocol (MCP), en öppen standard för att koppla AI-modeller till verktyg över HTTP. Vilken MCP-kompatibel klient som helst kan skapa hostade dashboards, lista och inspektera dem, samt lägga till data i dem programmatiskt. Dashboards som skapas via API:erna tillhör ditt konto och kan delas, bäddas in eller redigeras vidare i tjänsten. För att bädda in de dashboards du skapar på din egen webbplats, se anteckningarna om enkel dashboard-integration. Om du använder Claude är det snabbaste sättet att komma igång Sprucely.io-kopplingen.

Anslutning

MCP-servern serveras över Streamable HTTP på:

https://www.sprucely.io/mcp

Vilken MCP-klient som helst kan ansluta till den här slutpunkten. Till exempel registrerar ett enda kommando servern i Claude Code:

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

Du kan även anropa servern direkt med JSON-RPC 2.0 över HTTP. De flesta MCP-klienter utför protokollhandskakningen automatiskt; begäran nedan listar de tillgängliga verktygen med en API-nyckel:

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

Begäranden auktoriseras med en vanlig Authorization Bearer-header. Två typer av autentiseringsuppgifter stöds.

API-nycklar - Skapa API-nycklar i MCP-avsnittet i din profil. Nycklar börjar med spr_mcp_, visas bara en gång vid skapandet, och kan återkallas när som helst. Använd dem för skript, servrar och headless MCP-klienter.

OAuth 2.1 - Interaktiva MCP-klienter kan i stället låta användare logga in med sitt Sprucely.io-konto via OAuth 2.1. Auktoriseringsservern stöder authorization code-flödet med PKCE (obligatoriskt), refresh-tokens och dynamisk klientregistrering, så kompatibla klienter konfigurerar sig själva automatiskt utifrån resursmetadatan:

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

Tillgängliga scopes: openid, offline_access, dashboards:read och dashboards:write. Scopes tillämpas per verktyg: create_dashboard, add_data och set_sharing kräver dashboards:write och returnerar ett fel utan det. Övriga verktyg behöver bara dashboards:read.

För klienter som kräver manuell konfiguration är auktoriseringsserverns slutpunkter:

https://www.sprucely.io/oauth/.well-known/openid-configuration - auktoriseringsserverns metadata
https://www.sprucely.io/oauth/auth - auktoriseringsslutpunkt (PKCE krävs)
https://www.sprucely.io/oauth/token - token-slutpunkt
https://www.sprucely.io/oauth/reg - dynamisk klientregistrering
https://www.sprucely.io/oauth/jwks - signeringsnycklar (JWKS)
https://www.sprucely.io/oauth/token/revocation - token-återkallning
https://www.sprucely.io/oauth/token/introspection - token-introspektion

Verktyg

MCP-servern exponerar åtta verktyg: create_dashboard, get_dashboard, list_dashboards, add_data, get_dataset_schema, set_sharing, get_embed_code och storage_status.

Dataset- och dashboard-parametrarna nedan är inte ett MCP-specifikt format - det är exakt samma dataset-/dashboard-JSON som dokumenteras på sidan Dataformat och som används överallt annars i tjänsten (den fristående inbäddningsbara runtimens import-API, AI-genererade layouter och dashboard-editorn), så allt som skrivits mot den referensen gäller även här.

create_dashboard - Skapar en hostad dashboard från ett inline-dataset och ett widgetträd, och returnerar länkar för visning och inbäddning. Parametrar:

name - dashboardens titel (obligatoriskt)
dataset - datasetet som ska visualiseras: name, headers (kolumnnamn), types (en databastyp per header - VARCHAR, BOOLEAN, INTEGER, BIGINT, FLOAT, DOUBLE, DATE eller TIMESTAMP) och entries (rader, var och en en array av värden i header-ordning), upp till 100 kolumner och 50 000 råa poster på radnivå per anrop (obligatoriskt). Entries får inte vara förberäknade: skicka en rad per underliggande post, och låt varje diagrams dataFunction beräkna antal, summor, genomsnitt och så vidare vid rendering.
dashboard - 1 till 40 widgetar på toppnivå, uppifrån och ned (obligatoriskt). Varje widget är ett dash_chart (en diagramtyp - area, bar, cell, dot, hexbin eller line - kolumnmappningar för x, y, d och r, en valfri dataFunction och en valfri titel), en dash_table, ett dash_text-block, ett dash_spacer, eller en dash_stacker_hor/dash_stacker_ver-container. Staplare nästlas rekursivt - en staplares egna children kan innehålla ytterligare staplare - för att ordna widgetar i rader och kolumner med godtyckligt djup. Vilka kolumntyper (kategoriska, kontinuerliga eller datum/tid) varje diagramtyps x/y/d/r-dimensioner accepterar, och hur tidsindelning av en datumkolumn med seasonX/seasonY gör den kategorisk, dokumenteras för varje fält via tools/list och på sidan Dataformat.
theme - valfria dashboardövergripande färger (bakgrund, text, primär/subtil/sekundär accent); vilken widget som helst kan ändå skriva över sin egen färg eller bakgrund
shared - om dashboarden kan visas av vem som helst med länken (valfritt, standard false). Nya dashboards är privata tills du sätter detta till true eller anropar set_sharing i efterhand.

Resultatet innehåller den nya dashboardens dashboardId och datasetId (behövs senare av add_data, get_dataset_schema, set_sharing och get_embed_code), samt dess url, viewUrl och iframe-inbäddningskod. Exempel - skapa en dashboard med ett stapeldiagram och en dashboardövergripande accentfärg:

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 - Returnerar en dashboards namn, delningsstatus, dataset-ID:n och länkar. Parameter: dashboardId (obligatoriskt). Exempel:

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 - Listar dashboards i ditt konto, sorterade efter senaste uppdatering, var och en med sina egna datasetIds så att ett dataset kan skickas direkt till get_dataset_schema eller add_data utan ett separat get_dashboard-anrop. Parametrar: limit och offset för sidnumrering, query för ett skiftlägesokänsligt namnfilter (alla valfria). Exempel:

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 - Lägger till entries i en befintlig dashboards dataset; varje dashboard som använder datasetet uppdateras automatiskt. Parametrar:

dashboardId - dashboarden att lägga till i (obligatoriskt)
entries - rader som är positionellt justerade mot datasetets headers, upp till 50 000 per anrop (obligatoriskt) - samma regel om råa poster på radnivå som för create_dashboard gäller. Anropa get_dataset_schema först om du inte redan känner till dashboardens exakta kolumnnamn/ordning. Använd det för att läsa in stora dataset i omgångar eller för att hålla dashboards uppdaterade.
run_id - en valfri idempotensnyckel för just den här omgången (valfritt). Om ett tidigare add_data-anrop med samma dashboardId och run_id redan lyckades, returnerar ett nytt anrop det tidigare resultatet i stället för att lägga till raderna en andra gång, så att en omgång kan göras om säkert efter en timeout eller en avbruten anslutning - använd ett nytt run_id per unik omgång (till exempel ett UUID eller en hash av dess innehåll).

Exempel:

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 - Returnerar ett datasets kolumnnamn och typer. Använd det innan du anropar add_data (eller bygger ett nytt diagram mot samma dataset) närhelst de exakta kolumnnamnen/ordningen/typerna inte redan är kända, till exempel i en ny session eller när en annan agent skapade dashboarden. Parameter: datasetId (obligatoriskt). Exempel:

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 på eller av en dashboards publika länk. Att slå av den återkallar även åtkomsten för varje tidigare version av dashboarden, så en länk som delades tidigare slutar fungera. Parametrar: dashboardId och shared (båda obligatoriska). Exempel:

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 - Returnerar den delbara visningslänken och en iframe-inbäddningskod för en dashboard - samma länk/inbäddningskod som create_dashboard och set_sharing redan returnerar, för de fall de behövs igen på egen hand. Länken fungerar bara för andra medan dashboarden delas. Parameter: dashboardId (obligatoriskt). Exempel:

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 - Rapporterar hur mycket lagring kontot har använt och hur mycket som återstår, användbart innan ett create_dashboard- eller add_data-anrop som är stort nog att riskera planens lagringsgräns. Inga parametrar. Exempel:

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 och fel

MCP-slutpunkten accepterar 25 begäranden per minut och klient, med en begärandestorlek på upp till 25 MB - läs in större dataset i omgångar med add_data.
Dataset accepterar upp till 100 kolumner och 50 000 rader per anrop, och en dashboard accepterar upp till 40 widgetar på varje nästlingsnivå. Sparade dashboards räknas mot din plans lagringskvot - anropa storage_status för att kontrollera återstående utrymme innan ett stort create_dashboard- eller add_data-anrop.
Vanliga HTTP-statuskoder används: 401 för saknade eller ogiltiga autentiseringsuppgifter (med en WWW-Authenticate-utmaning som pekar mot resursmetadatan), 403 för återkallade eller otillräckliga autentiseringsuppgifter, 413 för för stora begäranden och 429 vid hastighetsbegränsning.