MCP API

概要

Sprucely.ioのMCP APIは、AIモデルをツールとHTTP経由で接続するためのオープンスタンダードであるModel Context Protocol（MCP）を通じて、ダッシュボードプラットフォームをAIアシスタントやサードパーティソフトウェアに公開します。MCP対応のクライアントであれば、ホスト型ダッシュボードの作成、一覧表示・参照、そしてプログラムによるデータの追加が可能です。APIを通じて作成されたダッシュボードはお客様のアカウントに属し、サービス内でさらに共有、埋め込み、編集ができます。作成したダッシュボードを自社サイトに埋め込む方法については、シンプルなダッシュボード統合の説明を参照してください。Claudeをお使いの場合、最も手早く始める方法はSprucely.ioコネクターです。

接続

MCPサーバーは、Streamable HTTPを介して次のURLで提供されています。

https://www.sprucely.io/mcp

どのMCPクライアントもこのエンドポイントに接続できます。例えば、次の1つのコマンドでClaude Codeにサーバーを登録できます。

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

サーバーをJSON-RPC 2.0 over HTTPで直接呼び出すこともできます。ほとんどのMCPクライアントはプロトコルのハンドシェイクを自動的に行いますが、以下のリクエストは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"}'

認証

リクエストは標準的なAuthorization Bearerヘッダーで認可されます。2種類の認証情報がサポートされています。

APIキー - プロフィールのMCPセクションでAPIキーを作成できます。キーはspr_mcp_で始まり、作成時に一度だけ表示され、いつでも失効させることができます。スクリプトやサーバー、ヘッドレスなMCPクライアントに使用してください。

OAuth 2.1 - インタラクティブなMCPクライアントの場合は、代わりにOAuth 2.1を通じてユーザーにSprucely.ioアカウントでサインインさせることができます。認可サーバーは、PKCE（必須）を伴う認可コードフロー、リフレッシュトークン、動的クライアント登録に対応しており、対応クライアントはリソースメタデータから自動的に設定を行います。

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

利用可能なスコープ: openid、offline_access、dashboards:read、dashboards:write。スコープはツールごとに適用されます。create_dashboard、add_data、set_sharing には dashboards:write が必要で、指定がない場合はエラーを返します。その他のツールは dashboards:read のみで利用できます。

手動での設定が必要なクライアントの場合、認可サーバーのエンドポイントは次のとおりです。

https://www.sprucely.io/oauth/.well-known/openid-configuration - 認可サーバーのメタデータ
https://www.sprucely.io/oauth/auth - 認可エンドポイント（PKCE必須）
https://www.sprucely.io/oauth/token - トークンエンドポイント
https://www.sprucely.io/oauth/reg - 動的クライアント登録
https://www.sprucely.io/oauth/jwks - 署名鍵（JWKS）
https://www.sprucely.io/oauth/token/revocation - トークン失効
https://www.sprucely.io/oauth/token/introspection - トークンイントロスペクション

ツール

MCPサーバーは、create_dashboard、get_dashboard、list_dashboards、add_data、get_dataset_schema、set_sharing、get_embed_code、storage_statusの8つのツールを公開しています。

以下のdatasetおよびdashboardパラメータは、MCP独自の形式ではありません。データ形式ページで解説されているdataset/dashboard JSONそのものであり、サービス内の他の箇所（スタンドアロンの埋め込み可能なランタイムのインポートAPI、AIが生成するレイアウト、ダッシュボードエディター）でも同じ形式が使用されています。そのため、同リファレンスに記載されている内容はここにもそのまま当てはまります。

create_dashboard - インラインのデータセットとウィジェットツリーからホスト型ダッシュボードを作成し、閲覧用リンクと埋め込みリンクを返します。パラメータ:

name - ダッシュボードのタイトルです（必須）
dataset - 可視化するデータセットです。name、headers（列名）、types（各ヘッダーに対応するデータベース型を1つずつ指定 - VARCHAR、BOOLEAN、INTEGER、BIGINT、FLOAT、DOUBLE、DATEまたはTIMESTAMP）、entries（行データ。各行はヘッダーの順序に沿った値の配列）で構成され、1回の呼び出しにつき最大100列、50,000件の生の行単位エントリまで指定できます（必須）。entriesは事前集計してはいけません。基となるレコードごとに1行を送信し、件数や合計、平均などの計算は各チャートのdataFunctionに描画時点で行わせてください。
dashboard - 上から下へ並ぶ1から40個のトップレベルウィジェットです（必須）。各ウィジェットは、dash_chart（チャートタイプ - area、bar、cell、dot、hexbinまたはline - x、y、d、rへの列マッピング、任意のdataFunction、任意のタイトルを持つ）、dash_table、dash_textブロック、dash_spacer、またはdash_stacker_hor/dash_stacker_verコンテナのいずれかです。スタッカーは再帰的にネストでき——スタッカー自身の子要素にさらにスタッカーを含めることができ——ウィジェットを任意の深さの行・列に配置できます。各チャートタイプのx/y/d/rの各次元がどの列の種類（カテゴリ型、連続型、日付/時間型）を受け付けるか、またseasonX/seasonYで日付列を時間単位にグループ化するとどのようにカテゴリ型として扱われるかは、tools/listの各フィールド、およびデータ形式ページに記載されています。
theme - ダッシュボード全体の任意の配色です（背景、文字色、プライマリ/サトル/セカンダリのアクセントカラー）。どのウィジェットも、自身の色や背景を個別にオーバーライドできます。
shared - リンクを知っている人なら誰でもダッシュボードを閲覧できるかどうかです（任意、デフォルトはfalse）。新しいダッシュボードは、これをtrueに設定するか、後からset_sharingを呼び出すまでは非公開です。

結果には、新しいダッシュボードのdashboardIdとdatasetId（この後add_data、get_dataset_schema、set_sharing、get_embed_codeで必要になります）に加えて、url、viewUrl、埋め込み用のiframeスニペットが含まれます。例 - 棒グラフとダッシュボード全体のアクセントカラーを指定してダッシュボードを作成する:

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 - ダッシュボードのname、共有状態、データセットID、リンクを返します。パラメータ: dashboardId（必須）。例:

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 - アカウント内のダッシュボードを最終更新順に一覧表示します。それぞれにdatasetIdsが含まれているため、個別にget_dashboardを呼び出さなくても、データセットをそのままget_dataset_schemaやadd_dataに渡せます。パラメータ: ページングのためのlimitとoffset、大文字小文字を区別しない名前フィルタのためのquery（すべて任意）。例:

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 - 既存のダッシュボードのデータセットにentriesを追加します。そのデータセットを使用しているすべてのダッシュボードが自動的に更新されます。パラメータ:

dashboardId - 追加先のダッシュボードです（必須）
entries - データセットのヘッダーに位置的に対応した行データで、1回の呼び出しにつき最大50,000件です（必須）- create_dashboardと同じ、生の行単位データであるというルールが適用されます。ダッシュボードの正確な列名や順序がわからない場合は、先にget_dataset_schemaを呼び出してください。大きなデータセットをバッチに分けて読み込んだり、ダッシュボードを最新の状態に保ったりする際に使用します。
run_id - このバッチ専用の冪等性キーです（任意）。同じdashboardIdとrun_idを使った以前のadd_data呼び出しがすでに成功している場合、再度呼び出すと行を二重に追加する代わりに、その前回の結果が返されます。そのため、タイムアウトや接続切断の後でもバッチを安全に再試行できます - バッチごとに異なるrun_id（例えばUUIDや内容のハッシュ値）を使用してください。

例:

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 - データセットの列名と型を返します。正確な列名・順序・型がわからない場合、例えば新しいセッションを開始したときや、別のエージェントがダッシュボードを作成した場合などは、add_dataを呼び出す前（あるいは同じデータセットに対して新しいチャートを組み立てる前）にこれを使用してください。パラメータ: datasetId（必須）。例:

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 - ダッシュボードの公開リンクのオン・オフを切り替えます。オフにすると、そのダッシュボードの過去のすべてのリビジョンへのアクセスも取り消されるため、以前に共有したリンクは使用できなくなります。パラメータ: dashboardIdとshared（いずれも必須）。例:

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 - ダッシュボードの共有可能な閲覧用リンクと、iframe埋め込みスニペットを返します。これらはcreate_dashboardやset_sharingがすでに返しているリンク・埋め込みコードと同じもので、単体で改めて必要になった場合に使用します。このリンクが他のユーザーに対して機能するのは、ダッシュボードが共有されている間だけです。パラメータ: dashboardId（必須）。例:

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 - アカウントが使用しているストレージ容量と、残りの容量を報告します。プランのストレージ上限に達する恐れがあるほど大きなcreate_dashboardやadd_dataを呼び出す前に確認すると便利です。パラメータはありません。例:

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
}

制限とエラー

MCPエンドポイントは、クライアントごとに1分あたり25リクエスト、リクエストボディは最大25 MBまでを受け付けます - より大きなデータセットはadd_dataのバッチに分けて読み込んでください。
データセットは1回の呼び出しにつき最大100列、50,000行までを受け付け、ダッシュボードはネストの各階層で最大40個のウィジェットを受け付けます。保存されたダッシュボードはプランのストレージクォータに算入されます - 大きなcreate_dashboardやadd_dataを呼び出す前に、storage_statusで残り容量を確認してください。
標準的なHTTPステータスコードが使用されます: 認証情報が欠落または無効な場合は401（リソースメタデータを指すWWW-Authenticateチャレンジを伴う）、認証情報が失効または権限不足の場合は403、リクエストが大きすぎる場合は413、レート制限にかかった場合は429です。