API MCP

Aperçu

Les API MCP de Sprucely.io exposent la plateforme de tableaux de bord aux assistants IA et aux logiciels tiers via le Model Context Protocol (MCP), un standard ouvert pour connecter des modèles d’IA à des outils via HTTP. Tout client compatible MCP peut créer des tableaux de bord hébergés, les lister et les consulter, et y ajouter des données par programmation. Les tableaux de bord créés via les API appartiennent à votre compte et peuvent être partagés, intégrés ou modifiés davantage dans le service. Pour intégrer les tableaux de bord obtenus dans votre propre site, consultez les notes sur l’intégration simple d’un tableau de bord. Si vous utilisez Claude, le moyen le plus rapide de démarrer est le connecteur Sprucely.io.

Connexion

Le serveur MCP est exposé via Streamable HTTP à l’adresse suivante :

https://www.sprucely.io/mcp

Tout client MCP peut se connecter à ce point de terminaison. Par exemple, une seule commande enregistre le serveur dans Claude Code :

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

Vous pouvez également appeler le serveur directement en JSON-RPC 2.0 via HTTP. La plupart des clients MCP effectuent automatiquement la négociation du protocole ; la requête ci-dessous liste les outils disponibles à l’aide d’une clé 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"}'

Authentification

Les requêtes sont autorisées à l’aide d’un en-tête Authorization Bearer standard. Deux types d’identifiants sont pris en charge.

Clés API - Créez des clés API dans la section MCP de votre profil. Les clés commencent par spr_mcp_, ne sont affichées qu’une seule fois à leur création, et peuvent être révoquées à tout moment. Utilisez-les pour les scripts, les serveurs et les clients MCP sans interface.

OAuth 2.1 - Les clients MCP interactifs peuvent au contraire permettre aux utilisateurs de se connecter avec leur compte Sprucely.io via OAuth 2.1. Le serveur d’autorisation prend en charge le flux d’autorisation par code avec PKCE (obligatoire), les jetons de rafraîchissement et l’enregistrement dynamique de client, de sorte que les clients compatibles se configurent automatiquement à partir des métadonnées de ressource :

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

Portées disponibles : openid, offline_access, dashboards:read et dashboards:write. Les portées sont appliquées par outil : create_dashboard, add_data et set_sharing exigent dashboards:write et renvoient une erreur sans elle. Les autres outils ne nécessitent que dashboards:read.

Pour les clients nécessitant une configuration manuelle, les points de terminaison du serveur d’autorisation sont :

https://www.sprucely.io/oauth/.well-known/openid-configuration - métadonnées du serveur d’autorisation
https://www.sprucely.io/oauth/auth - point de terminaison d’autorisation (PKCE obligatoire)
https://www.sprucely.io/oauth/token - point de terminaison de jeton
https://www.sprucely.io/oauth/reg - enregistrement dynamique de client
https://www.sprucely.io/oauth/jwks - clés de signature (JWKS)
https://www.sprucely.io/oauth/token/revocation - révocation de jeton
https://www.sprucely.io/oauth/token/introspection - introspection de jeton

Outils

Le serveur MCP expose huit outils : create_dashboard, get_dashboard, list_dashboards, add_data, get_dataset_schema, set_sharing, get_embed_code et storage_status.

Les paramètres dataset et dashboard ci-dessous ne constituent pas un format propre à MCP - il s’agit exactement du même JSON de jeu de données/tableau de bord documenté sur la page format de données et utilisé partout ailleurs dans le service (l’API d’import du runtime autonome intégrable, les mises en page générées par IA, et l’éditeur de tableau de bord) ; tout ce qui est décrit dans cette référence s’applique donc également ici.

create_dashboard - Crée un tableau de bord hébergé à partir d’un jeu de données en ligne et d’une arborescence de widgets, et renvoie les liens de consultation et d’intégration. Paramètres :

name - le titre du tableau de bord (obligatoire)
dataset - le jeu de données à visualiser : name, headers (noms des colonnes), types (un type de base de données par en-tête - VARCHAR, BOOLEAN, INTEGER, BIGINT, FLOAT, DOUBLE, DATE ou TIMESTAMP) et entries (les lignes, chacune un tableau de valeurs dans l’ordre des en-têtes), jusqu’à 100 colonnes et 50 000 lignes brutes, au niveau de l’enregistrement, par appel (obligatoire). Les lignes ne doivent pas être pré-agrégées : envoyez une ligne par enregistrement source, et laissez la dataFunction de chaque graphique calculer les comptages, sommes, moyennes, etc. au moment du rendu.
dashboard - de 1 à 40 widgets de premier niveau, de haut en bas (obligatoire). Chaque widget est un dash_chart (un type de graphique - area, bar, cell, dot, hexbin ou line - des correspondances de colonnes pour x, y, d et r, une dataFunction facultative et un titre facultatif), un dash_table, un bloc dash_text, un dash_spacer, ou un conteneur dash_stacker_hor/dash_stacker_ver. Les empileurs s’imbriquent de façon récursive - les enfants d’un empileur peuvent eux-mêmes inclure d’autres empileurs - pour organiser les widgets en lignes et colonnes d’une profondeur arbitraire. Les types de colonnes (catégorielle, continue ou temporelle) acceptés par les dimensions x/y/d/r de chaque type de graphique, ainsi que la façon dont le regroupement temporel d’une colonne de date avec seasonX/seasonY la rend catégorielle, sont documentés sur chaque champ via tools/list et sur la page format de données.
theme - couleurs facultatives applicables à l’ensemble du tableau de bord (arrière-plan, texte, accents primaire/subtil/secondaire) ; chaque widget peut néanmoins surcharger sa propre couleur ou son propre arrière-plan
shared - indique si le tableau de bord est consultable par toute personne disposant du lien (facultatif, false par défaut). Les nouveaux tableaux de bord sont privés tant que vous ne définissez pas ce paramètre sur true, ou que vous n’appelez pas set_sharing par la suite.

Le résultat contient le dashboardId et le datasetId du nouveau tableau de bord (nécessaires ensuite pour add_data, get_dataset_schema, set_sharing et get_embed_code), ainsi que son url, son viewUrl et l’extrait d’intégration iframe. Exemple - créer un tableau de bord avec un graphique en barres et une couleur d’accent commune à l’ensemble du tableau de bord :

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 - Renvoie le nom d’un tableau de bord, son statut de partage, les identifiants de ses jeux de données et ses liens. Paramètre : dashboardId (obligatoire). Exemple :

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 - Liste les tableaux de bord de votre compte, triés par date de dernière mise à jour, chacun avec ses propres datasetIds, afin qu’un jeu de données puisse être transmis directement à get_dataset_schema ou add_data sans appel séparé à get_dashboard. Paramètres : limit et offset pour la pagination, query pour un filtre de nom insensible à la casse (tous facultatifs). Exemple :

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 - Ajoute des lignes au jeu de données d’un tableau de bord existant ; chaque tableau de bord utilisant ce jeu de données se met à jour automatiquement. Paramètres :

dashboardId - le tableau de bord auquel ajouter les données (obligatoire)
entries - les lignes alignées positionnellement sur les en-têtes du jeu de données, jusqu’à 50 000 par appel (obligatoire) - la même règle de lignes brutes, au niveau de l’enregistrement, que pour create_dashboard s’applique. Appelez d’abord get_dataset_schema si vous ne connaissez pas déjà les noms/l’ordre exacts des colonnes du tableau de bord. Utilisez-le pour charger de grands jeux de données par lots ou pour maintenir des tableaux de bord à jour.
run_id - une clé d’idempotence facultative pour ce lot précis (facultatif). Si un appel add_data précédent portant le même dashboardId et le même run_id a déjà réussi, un nouvel appel renvoie ce résultat antérieur au lieu d’ajouter les lignes une seconde fois, ce qui permet de réessayer un lot en toute sécurité après un délai d’expiration ou une connexion interrompue - utilisez un nouveau run_id pour chaque lot distinct (par exemple un UUID ou un hachage de son contenu).

Exemple :

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 - Renvoie les noms et types de colonnes d’un jeu de données. Utilisez-le avant d’appeler add_data (ou de construire un nouveau graphique sur le même jeu de données) chaque fois que les noms/l’ordre/les types exacts des colonnes ne sont pas déjà connus, par exemple dans une nouvelle session ou lorsqu’un autre agent a créé le tableau de bord. Paramètre : datasetId (obligatoire). Exemple :

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 - Active ou désactive le lien public d’un tableau de bord. Le désactiver révoque également l’accès à toutes les révisions antérieures du tableau de bord, de sorte qu’un lien partagé par le passé cesse de fonctionner. Paramètres : dashboardId et shared (tous deux obligatoires). Exemple :

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 - Renvoie le lien de consultation partageable et un extrait d’intégration iframe pour un tableau de bord - le même lien/code d’intégration que create_dashboard et set_sharing renvoient déjà, pour le cas où vous en auriez de nouveau besoin séparément. Le lien ne fonctionne pour les autres que tant que le tableau de bord est partagé. Paramètre : dashboardId (obligatoire). Exemple :

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 - Indique la quantité de stockage utilisée par le compte et celle qui reste disponible, utile avant un appel create_dashboard ou add_data suffisamment volumineux pour risquer d’atteindre la limite de stockage du forfait. Aucun paramètre. Exemple :

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
}

Limites et erreurs

Le point de terminaison MCP accepte 25 requêtes par minute et par client, et des corps de requête allant jusqu’à 25 Mo - chargez les jeux de données plus volumineux par lots avec add_data.
Les jeux de données acceptent jusqu’à 100 colonnes et 50 000 lignes par appel, et un tableau de bord accepte jusqu’à 40 widgets à chaque niveau d’imbrication. Les tableaux de bord enregistrés comptent dans le quota de stockage de votre forfait - appelez storage_status pour vérifier la marge restante avant un appel create_dashboard ou add_data de grande taille.
Des codes de statut HTTP standard sont utilisés : 401 pour des identifiants manquants ou invalides (avec un challenge WWW-Authenticate pointant vers les métadonnées de ressource), 403 pour des identifiants révoqués ou insuffisants, 413 pour des requêtes trop volumineuses et 429 en cas de limitation de débit.