MCP API

Ikhtisar

MCP API Sprucely.io membuka platform dasbor ini untuk asisten AI dan perangkat lunak pihak ketiga melalui Model Context Protocol (MCP), sebuah standar terbuka untuk menghubungkan model AI ke tool lewat HTTP. Klien mana pun yang kompatibel dengan MCP dapat membuat dasbor yang dihosting, menampilkan daftarnya, memeriksanya, dan menambahkan data ke dalamnya secara programatik. Dasbor yang dibuat melalui API ini menjadi milik akun Anda dan dapat dibagikan, disematkan, atau diedit lebih lanjut di layanan ini. Untuk menyematkan dasbor hasilnya ke situs Anda sendiri, lihat catatan integrasi dasbor sederhana. Jika Anda menggunakan Claude, cara tercepat untuk memulai adalah konektor Sprucely.io.

Menghubungkan

Server MCP ini disajikan melalui Streamable HTTP di:

https://www.sprucely.io/mcp

Klien MCP mana pun dapat terhubung ke endpoint ini. Misalnya, satu perintah saja sudah cukup untuk mendaftarkan server ini di Claude Code:

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

Anda juga dapat memanggil server ini langsung dengan JSON-RPC 2.0 lewat HTTP. Sebagian besar klien MCP menjalankan handshake protokol secara otomatis; permintaan di bawah ini menampilkan daftar tool yang tersedia menggunakan sebuah kunci 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"}'

Autentikasi

Permintaan diotorisasi dengan header Authorization Bearer standar. Dua jenis kredensial didukung.

Kunci API - Buat kunci API di bagian MCP pada profil Anda. Kunci dimulai dengan spr_mcp_, hanya ditampilkan satu kali saat dibuat, dan dapat dicabut kapan saja. Gunakan untuk skrip, server, dan klien MCP headless.

OAuth 2.1 - Sebagai alternatif, klien MCP interaktif dapat membiarkan pengguna masuk dengan akun Sprucely.io mereka melalui OAuth 2.1. Server otorisasi ini mendukung authorization code flow dengan PKCE (wajib), refresh token, dan pendaftaran klien dinamis, sehingga klien yang kompatibel dapat mengonfigurasi dirinya sendiri secara otomatis dari metadata sumber daya:

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

Scope yang tersedia: openid, offline_access, dashboards:read dan dashboards:write. Scope diterapkan per alat: create_dashboard, add_data, dan set_sharing memerlukan dashboards:write dan akan mengembalikan error tanpa scope tersebut. Alat lainnya hanya memerlukan dashboards:read.

Untuk klien yang memerlukan konfigurasi manual, endpoint server otorisasi adalah:

https://www.sprucely.io/oauth/.well-known/openid-configuration - metadata server otorisasi
https://www.sprucely.io/oauth/auth - endpoint otorisasi (PKCE wajib)
https://www.sprucely.io/oauth/token - endpoint token
https://www.sprucely.io/oauth/reg - pendaftaran klien dinamis
https://www.sprucely.io/oauth/jwks - kunci penandatanganan (JWKS)
https://www.sprucely.io/oauth/token/revocation - pencabutan token
https://www.sprucely.io/oauth/token/introspection - introspeksi token

Alat

Server MCP ini menyediakan delapan tool: create_dashboard, get_dashboard, list_dashboards, add_data, get_dataset_schema, set_sharing, get_embed_code and storage_status.

Parameter dataset dan dasbor di bawah ini bukan format khusus MCP - keduanya persis sama dengan JSON dataset/dasbor yang didokumentasikan di halaman Format Data dan digunakan di seluruh bagian lain layanan ini (API impor pada runtime mandiri yang dapat disematkan, tata letak yang dihasilkan AI, dan editor dasbor), sehingga apa pun yang ditulis berdasarkan referensi tersebut juga berlaku di sini.

create_dashboard - Membuat dasbor yang dihosting dari sebuah dataset inline dan sebuah pohon widget, lalu mengembalikan tautan tampilan dan tautan sematan. Parameter:

name - judul dasbor (wajib)
dataset - dataset yang akan divisualisasikan: name, headers (nama kolom), types (satu tipe database untuk setiap header - VARCHAR, BOOLEAN, INTEGER, BIGINT, FLOAT, DOUBLE, DATE or TIMESTAMP) dan entries (baris, masing-masing berupa array nilai sesuai urutan header), hingga 100 kolom dan 50.000 baris data mentah per panggilan (wajib). Baris tidak boleh sudah teragregasi sebelumnya: kirim satu baris per catatan yang mendasarinya, dan biarkan dataFunction pada setiap chart menghitung jumlah, total, rata-rata, dan sebagainya saat dirender.
dashboard - 1 hingga 40 widget tingkat atas, dari atas ke bawah (wajib). Setiap widget berupa dash_chart (sebuah jenis chart - area, bar, cell, dot, hexbin or line - pemetaan kolom untuk x, y, d and r, sebuah dataFunction opsional dan judul opsional), sebuah dash_table, sebuah blok dash_text, sebuah dash_spacer, atau sebuah container dash_stacker_hor/dash_stacker_ver. Stacker bersarang secara rekursif - anak-anak dari sebuah stacker dapat mencakup stacker lain lagi - untuk menata widget ke dalam baris dan kolom dengan kedalaman berapa pun. Jenis kolom mana (kategorikal, kontinu, atau tanggal/waktu) yang diterima oleh dimensi x/y/d/r pada masing-masing jenis chart, serta bagaimana pengelompokan waktu pada kolom tanggal dengan seasonX/seasonY mengubahnya menjadi kategorikal, didokumentasikan pada setiap field lewat tools/list dan pada halaman Format Data.
theme - warna opsional untuk seluruh dasbor (latar belakang, teks, aksen primer/halus/sekunder); widget mana pun tetap dapat meng-override warna atau latar belakangnya sendiri
shared - apakah dasbor dapat dilihat oleh siapa pun yang memiliki tautannya (opsional, default false). Dasbor baru bersifat privat sampai Anda mengatur ini ke true atau memanggil set_sharing setelahnya.

Hasilnya membawa dashboardId dan datasetId dari dasbor baru tersebut (diperlukan oleh add_data, get_dataset_schema, set_sharing dan get_embed_code setelahnya), beserta url, viewUrl, dan cuplikan sematan iframe-nya. Contoh - membuat dasbor dengan sebuah chart batang dan warna aksen untuk seluruh dasbor:

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 - Mengembalikan nama dasbor, status berbagi, ID dataset, dan tautannya. Parameter: dashboardId (wajib). Contoh:

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 - Menampilkan daftar dasbor di akun Anda, diurutkan berdasarkan pembaruan terakhir, masing-masing dengan datasetIds-nya sendiri sehingga sebuah dataset dapat langsung diteruskan ke get_dataset_schema atau add_data tanpa panggilan get_dashboard terpisah. Parameter: limit dan offset untuk paging, query untuk filter nama yang tidak peka huruf besar/kecil (semuanya opsional). Contoh:

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 - Menambahkan entri ke dataset dari sebuah dasbor yang sudah ada; setiap dasbor yang menggunakan dataset tersebut akan diperbarui secara otomatis. Parameter:

dashboardId - dasbor yang akan ditambahkan datanya (wajib)
entries - baris yang selaras secara posisi dengan header dataset, hingga 50.000 per panggilan (wajib) - aturan baris mentah yang sama seperti pada create_dashboard berlaku di sini. Panggil get_dataset_schema terlebih dahulu jika Anda belum mengetahui nama/urutan kolom pasti dari dasbor tersebut. Gunakan ini untuk memuat dataset besar secara bertahap atau untuk menjaga dasbor tetap terkini.
run_id - kunci idempotensi opsional untuk batch tertentu ini (opsional). Jika panggilan add_data sebelumnya dengan dashboardId dan run_id yang sama sudah berhasil, memanggilnya lagi akan mengembalikan hasil sebelumnya, bukan menambahkan baris tersebut untuk kedua kalinya, sehingga sebuah batch dapat dicoba ulang dengan aman setelah timeout atau koneksi terputus - gunakan run_id baru untuk setiap batch yang berbeda (misalnya UUID atau hash dari isinya).

Contoh:

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 - Mengembalikan nama dan tipe kolom sebuah dataset. Gunakan sebelum memanggil add_data (atau membangun chart baru terhadap dataset yang sama) kapan pun nama/urutan/tipe kolom pastinya belum diketahui, misalnya pada sesi baru atau ketika dasbor dibuat oleh agen lain. Parameter: datasetId (wajib). Contoh:

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 - Mengaktifkan atau menonaktifkan tautan publik sebuah dasbor. Menonaktifkannya juga mencabut akses untuk setiap revisi dasbor sebelumnya, sehingga tautan yang pernah dibagikan di masa lalu pun berhenti berfungsi. Parameter: dashboardId dan shared (keduanya wajib). Contoh:

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 - Mengembalikan tautan tampilan yang dapat dibagikan beserta cuplikan sematan iframe untuk sebuah dasbor - tautan/kode sematan yang sama yang sudah dikembalikan oleh create_dashboard dan set_sharing, untuk saat keduanya dibutuhkan lagi secara terpisah. Tautan ini hanya berfungsi untuk orang lain selama dasbor dibagikan. Parameter: dashboardId (wajib). Contoh:

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 - Melaporkan berapa banyak penyimpanan yang telah digunakan akun dan berapa sisanya, berguna sebelum panggilan create_dashboard atau add_data yang cukup besar untuk berisiko melewati batas penyimpanan paket. Tanpa parameter. Contoh:

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
}

Batas dan Kesalahan

Endpoint MCP menerima 25 permintaan per menit per klien dan isi permintaan hingga 25 MB - muat dataset yang lebih besar dalam batch add_data.
Dataset menerima hingga 100 kolom dan 50.000 baris per panggilan, dan sebuah dasbor menerima hingga 40 widget di setiap tingkat nesting. Dasbor yang tersimpan diperhitungkan dalam kuota penyimpanan paket Anda - panggil storage_status untuk memeriksa sisa ruang sebelum panggilan create_dashboard atau add_data yang besar.
Kode status HTTP standar digunakan: 401 untuk kredensial yang hilang atau tidak valid (dengan tantangan WWW-Authenticate yang menunjuk ke metadata sumber daya), 403 untuk kredensial yang dicabut atau tidak mencukupi, 413 untuk permintaan yang berukuran terlalu besar, dan 429 saat dibatasi laju.