MCP-rajapinnat

Yleiskatsaus

Sprucely.io:n MCP-rajapinnat avaavat koontinäyttöalustan tekoälyavustimille ja kolmannen osapuolen ohjelmistoille Model Context Protocolin (MCP) kautta - avoimen standardin, joka yhdistää tekoälymalleja työkaluihin HTTP:n välityksellä. Mikä tahansa MCP-yhteensopiva asiakassovellus voi luoda isännöityjä koontinäyttöjä, listata ja tarkastella niitä sekä lisätä niihin dataa ohjelmallisesti. Rajapintojen kautta luodut koontinäytöt kuuluvat tilillesi, ja niitä voi jakaa, upottaa tai muokata edelleen palvelussa. Ohjeet valmiiden koontinäyttöjen upottamiseen omalle sivustollesi löydät kohdasta yksinkertainen koontinäytön upotus. Jos käytät Claudea, nopein tapa päästä alkuun on Sprucely.io-liitin.

Yhdistäminen

MCP-palvelin tarjoillaan Streamable HTTP:n kautta osoitteessa:

https://www.sprucely.io/mcp

Mikä tahansa MCP-asiakassovellus voi muodostaa yhteyden tähän päätepisteeseen. Esimerkiksi yksi komento rekisteröi palvelimen Claude Codeen:

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

Voit myös kutsua palvelinta suoraan JSON-RPC 2.0:lla HTTP:n yli. Useimmat MCP-asiakassovellukset suorittavat protokollakättelyn automaattisesti; alla oleva pyyntö listaa käytettävissä olevat työkalut API-avaimella:

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

Todennus

Pyynnöt valtuutetaan vakiomuotoisella Authorization Bearer -otsikolla. Tuettuna on kaksi tunnistetietotyyppiä.

API-avaimet - Luo API-avaimia profiilisi MCP-osiossa. Avaimet alkavat merkkijonolla spr_mcp_, ne näytetään vain kerran luontihetkellä, ja ne voi mitätöidä milloin tahansa. Käytä niitä skripteissä, palvelimilla ja headless-MCP-asiakassovelluksissa.

OAuth 2.1 - Interaktiiviset MCP-asiakassovellukset voivat sen sijaan antaa käyttäjien kirjautua sisään Sprucely.io-tilillään OAuth 2.1:n kautta. Valtuutuspalvelin tukee PKCE:tä käyttävää valtuutuskoodivuota (pakollinen), päivitystunnuksia ja dynaamista asiakasrekisteröintiä, joten yhteensopivat asiakassovellukset määrittyvät automaattisesti resurssin metatietojen perusteella:

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

Käytettävissä olevat scope-arvot: openid, offline_access, dashboards:read ja dashboards:write. Scope-arvot tarkistetaan työkalukohtaisesti: create_dashboard, add_data ja set_sharing vaativat dashboards:write-arvon ja palauttavat ilman sitä virheen. Muut työkalut tarvitsevat vain dashboards:read-arvon.

Asiakassovelluksille, jotka vaativat manuaalisen määrityksen, valtuutuspalvelimen päätepisteet ovat:

https://www.sprucely.io/oauth/.well-known/openid-configuration - valtuutuspalvelimen metatiedot
https://www.sprucely.io/oauth/auth - valtuutuksen päätepiste (PKCE pakollinen)
https://www.sprucely.io/oauth/token - tunnuksen päätepiste
https://www.sprucely.io/oauth/reg - dynaaminen asiakasrekisteröinti
https://www.sprucely.io/oauth/jwks - allekirjoitusavaimet (JWKS)
https://www.sprucely.io/oauth/token/revocation - tunnuksen mitätöinti
https://www.sprucely.io/oauth/token/introspection - tunnuksen introspektio

Työkalut

MCP-palvelin tarjoaa kahdeksan työkalua: create_dashboard, get_dashboard, list_dashboards, add_data, get_dataset_schema, set_sharing, get_embed_code ja storage_status.

Alla olevat dataset- ja dashboard-parametrit eivät ole MCP:lle ominainen muoto - ne ovat täsmälleen sama dataset/dashboard-JSON, joka on dokumentoitu Tietomuoto-sivulla ja jota käytetään kaikkialla muuallakin palvelussa (itsenäisen upotettavan ajoympäristön tuonti-API:ssa, tekoälyn luomissa asetteluissa ja koontinäyttöeditorissa), joten kaikki tuota viitettä vasten kirjoitettu pätee myös täällä.

create_dashboard - Luo isännöidyn koontinäytön inline-datasetistä ja widget-puusta, ja palauttaa katselu- ja upotuslinkit. Parametrit:

name - koontinäytön otsikko (pakollinen)
dataset - visualisoitava dataset: name, headers (sarakkeiden nimet), types (yksi tietokantatyyppi per otsikko - VARCHAR, BOOLEAN, INTEGER, BIGINT, FLOAT, DOUBLE, DATE tai TIMESTAMP) sekä entries (rivit, joista jokainen on arvotaulukko otsikoiden järjestyksessä), enintään 100 saraketta ja 50 000 raakaa, rivitason riviä per kutsu (pakollinen). Rivit eivät saa olla valmiiksi koostettuja: lähetä yksi rivi jokaista taustalla olevaa tietuetta kohti, ja anna kunkin kaavion dataFunction-kentän laskea määrät, summat, keskiarvot ja niin edelleen renderöintihetkellä.
dashboard - 1-40 ylimmän tason widgetiä, ylhäältä alas (pakollinen). Jokainen widget on joko dash_chart (kaaviotyyppi - area, bar, cell, dot, hexbin tai line - sarakekartoitukset kentille x, y, d ja r, valinnainen dataFunction ja valinnainen otsikko), dash_table, dash_text-lohko, dash_spacer tai dash_stacker_hor/dash_stacker_ver-säiliö. Pinoajat sisäkkäistyvät rekursiivisesti - pinoajan omat lapsielementit voivat sisältää lisää pinoajia - jotta widgetit voidaan järjestää mielivaltaisen syvästi sisäkkäisiksi riveiksi ja sarakkeiksi. Se, minkä tyyppisiä sarakkeita (kategorinen, jatkuva tai päivämäärä/aika) kunkin kaaviotyypin x/y/d/r-ulottuvuudet hyväksyvät, sekä se, miten päivämääräsarakkeen ryhmittely toistuvaan jaksoon kentillä seasonX/seasonY muuttaa sen kategoriseksi, on dokumentoitu kunkin kentän kohdalla tools/list-kutsun kautta sekä Tietomuoto-sivulla.
theme - valinnaiset koontinäytön laajuiset värit (tausta, teksti, ensisijainen/hillitty/toissijainen korostusväri); mikä tahansa widget voi silti ohittaa oman värinsä tai taustansa
shared - onko koontinäyttö kenen tahansa linkin saaneen katsottavissa (valinnainen, oletus false). Uudet koontinäytöt ovat yksityisiä, kunnes asetat tämän arvoon true tai kutsut myöhemmin komentoa set_sharing.

Tulos sisältää uuden koontinäytön dashboardId- ja datasetId-arvot (joita tarvitaan myöhemmin komennoissa add_data, get_dataset_schema, set_sharing ja get_embed_code), sekä sen url-, viewUrl- ja iframe-upotuskoodin. Esimerkki - luo koontinäyttö, jossa on pylväskaavio ja koontinäytön laajuinen korostusväri:

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 - Palauttaa koontinäytön nimen, jakamisen tilan, dataset-tunnukset ja linkit. Parametri: dashboardId (pakollinen). Esimerkki:

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 - Listaa tilisi koontinäytöt viimeisimmän päivityksen mukaan järjestettynä, kukin omalla datasetIds-arvollaan, jotta dataset voidaan välittää suoraan komennolle get_dataset_schema tai add_data ilman erillistä get_dashboard-kutsua. Parametrit: limit ja offset sivutukseen, query kirjainkoosta riippumattomaan nimisuodatukseen (kaikki valinnaisia). Esimerkki:

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 - Lisää rivejä olemassa olevan koontinäytön datasetiin; jokainen datasetiä käyttävä koontinäyttö päivittyy automaattisesti. Parametrit:

dashboardId - koontinäyttö, johon rivit lisätään (pakollinen)
entries - rivit, jotka on kohdistettu asemansa perusteella datasetin otsikoihin, enintään 50 000 per kutsu (pakollinen) - sama raa’an, rivitason säännön vaatimus kuin komennossa create_dashboard pätee tässäkin. Kutsu ensin get_dataset_schema, jos et jo tiedä koontinäytön tarkkoja sarakenimiä/-järjestystä. Käytä sitä suurten datasettien lataamiseen erissä tai koontinäyttöjen pitämiseen ajan tasalla.
run_id - valinnainen idempotenssiavain tälle tietylle erälle (valinnainen). Jos aiempi add_data-kutsu samalla dashboardId- ja run_id-arvolla on jo onnistunut, uusi kutsu palauttaa saman aiemman tuloksen sen sijaan, että rivit lisättäisiin toistamiseen, joten erän voi turvallisesti yrittää uudelleen aikakatkaisun tai katkenneen yhteyden jälkeen - käytä uutta run_id-arvoa jokaiselle erilliselle erälle (esimerkiksi UUID tai sen sisällöstä laskettu tiiviste).

Esimerkki:

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 - Palauttaa datasetin sarakenimet ja -tyypit. Käytä sitä ennen komentoa add_data (tai uuden kaavion rakentamista samaan datasetiin) aina, kun tarkkoja sarakenimiä/-järjestystä/-tyyppejä ei jo tunneta, esimerkiksi uudessa istunnossa tai kun toinen agentti on luonut koontinäytön. Parametri: datasetId (pakollinen). Esimerkki:

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 - Kytkee koontinäytön julkisen linkin päälle tai pois. Pois kytkeminen mitätöi pääsyn myös koontinäytön jokaiseen aiempaan versioon, joten aiemmin jaettu linkki lakkaa toimimasta. Parametrit: dashboardId ja shared (molemmat pakollisia). Esimerkki:

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 - Palauttaa koontinäytön jaettavan katselulinkin ja iframe-upotuskoodin - saman linkin/upotuskoodin, jonka create_dashboard ja set_sharing jo palauttavat, siltä varalta että niitä tarvitaan myöhemmin erikseen uudelleen. Linkki toimii muille vain, kun koontinäyttö on jaettu. Parametri: dashboardId (pakollinen). Esimerkki:

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 - Kertoo, kuinka paljon tallennustilaa tili on käyttänyt ja kuinka paljon sitä on jäljellä; hyödyllinen ennen niin suurta create_dashboard- tai add_data-kutsua, että se voisi vaarantaa tilauksesi tallennustilarajan. Ei parametreja. Esimerkki:

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
}

Rajat ja virheet

MCP-päätepiste hyväksyy 25 pyyntöä minuutissa per asiakassovellus ja pyynnön rungon kooltaan enintään 25 Mt - lataa suuremmat datasetit erissä komennolla add_data.
Datasetit hyväksyvät enintään 100 saraketta ja 50 000 riviä per kutsu, ja koontinäyttö hyväksyy enintään 40 widgetiä kullakin sisäkkäisyystasolla. Tallennetut koontinäytöt kuluttavat tilauksesi tallennustilan kiintiötä - kutsu storage_status tarkistaaksesi jäljellä olevan tilan ennen suurta create_dashboard- tai add_data-kutsua.
Käytössä ovat vakiomuotoiset HTTP-tilakoodit: 401 puuttuvista tai virheellisistä tunnistetiedoista (mukana WWW-Authenticate-haaste, joka osoittaa resurssin metatietoihin), 403 mitätöidyistä tai riittämättömistä tunnistetiedoista, 413 liian suurista pyynnöistä ja 429, kun nopeusrajoitus ylittyy.