MCP API'leri

Genel Bakış

Sprucely.io MCP API’leri, dashboard platformunu Model Context Protocol (MCP) - yapay zekâ modellerini HTTP üzerinden araçlara bağlamak için açık bir standart - aracılığıyla yapay zekâ asistanlarına ve üçüncü taraf yazılımlara açar. MCP uyumlu herhangi bir istemci, barındırılan dashboard’lar oluşturabilir, bunları listeleyip inceleyebilir ve onlara programatik olarak veri ekleyebilir. API’ler aracılığıyla oluşturulan dashboard’lar hesabınıza aittir ve hizmet içinde paylaşılabilir, yerleştirilebilir veya daha fazla düzenlenebilir. Ortaya çıkan dashboard’ları kendi sitenize yerleştirmek için basit dashboard entegrasyonu notlarına bakın. Claude kullanıyorsanız başlamanın en hızlı yolu Sprucely.io bağlayıcısıdır.

Bağlantı

MCP sunucusu, Streamable HTTP üzerinden şu adreste sunulur:

https://www.sprucely.io/mcp

Herhangi bir MCP istemcisi bu uç noktaya bağlanabilir. Örneğin, tek bir komut sunucuyu Claude Code’a kaydeder:

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

Sunucuyu HTTP üzerinden JSON-RPC 2.0 ile doğrudan da çağırabilirsiniz. Çoğu MCP istemcisi protokol el sıkışmasını otomatik olarak gerçekleştirir; aşağıdaki istek, bir API anahtarı kullanarak kullanılabilir araçları listeler:

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

Kimlik Doğrulama

İstekler standart bir Authorization Bearer başlığıyla yetkilendirilir. İki kimlik bilgisi türü desteklenir.

API anahtarları - API anahtarlarını profilinizin MCP bölümünde oluşturun. Anahtarlar spr_mcp_ ile başlar, yalnızca oluşturulduğu anda gösterilir ve istediğiniz zaman iptal edilebilir. Bunları betikler, sunucular ve headless MCP istemcileri için kullanın.

OAuth 2.1 - Etkileşimli MCP istemcileri bunun yerine kullanıcıların Sprucely.io hesaplarıyla OAuth 2.1 üzerinden oturum açmasına izin verebilir. Yetkilendirme sunucusu, PKCE ile yetkilendirme kodu akışını (zorunlu), yenileme tokenlerini ve dinamik istemci kaydını destekler; böylece uyumlu istemciler kaynak meta verilerinden kendilerini otomatik olarak yapılandırır:

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

Kullanılabilir kapsamlar: openid, offline_access, dashboards:read ve dashboards:write. Kapsamlar araç bazında uygulanır: create_dashboard, add_data ve set_sharing dashboards:write kapsamını gerektirir ve bu kapsam olmadan hata döndürür. Diğer araçlar yalnızca dashboards:read kapsamına ihtiyaç duyar.

Manuel yapılandırma gerektiren istemciler için yetkilendirme sunucusu uç noktaları şunlardır:

https://www.sprucely.io/oauth/.well-known/openid-configuration - yetkilendirme sunucusu meta verileri
https://www.sprucely.io/oauth/auth - yetkilendirme uç noktası (PKCE zorunlu)
https://www.sprucely.io/oauth/token - token uç noktası
https://www.sprucely.io/oauth/reg - dinamik istemci kaydı
https://www.sprucely.io/oauth/jwks - imzalama anahtarları (JWKS)
https://www.sprucely.io/oauth/token/revocation - token iptali
https://www.sprucely.io/oauth/token/introspection - token içgözlemi

Araçlar

MCP sunucusu sekiz araç sunar: create_dashboard, get_dashboard, list_dashboards, add_data, get_dataset_schema, set_sharing, get_embed_code ve storage_status.

Aşağıdaki veri kümesi ve dashboard parametreleri MCP’ye özgü bir biçim değildir - bunlar tam olarak Veri Formatı sayfasında belgelenen ve hizmetin başka her yerinde kullanılan (bağımsız yerleştirilebilir çalışma zamanının içe aktarma API’si, yapay zekâ tarafından oluşturulan düzenler ve dashboard düzenleyicisi) aynı veri kümesi/dashboard JSON’udur; bu nedenle o referansa göre yazılmış her şey burada da geçerlidir.

create_dashboard - Satır içi bir veri kümesinden ve bir widget ağacından barındırılan bir dashboard oluşturur, ardından görüntüleme ve yerleştirme bağlantılarını döndürür. Parametreler:

name - dashboard’un başlığı (zorunlu)
dataset - görselleştirilecek veri kümesi: name, headers (sütun adları), types (her başlık için bir veritabanı türü - VARCHAR, BOOLEAN, INTEGER, BIGINT, FLOAT, DOUBLE, DATE veya TIMESTAMP) ve entries (satırlar; her biri başlık sırasına göre değerlerden oluşan bir dizidir), çağrı başına en fazla 100 sütun ve 50.000 ham, satır düzeyinde kayıt (zorunlu). Kayıtlar önceden toplulaştırılmış olmamalıdır: temeldeki her kayıt için tek bir satır gönderin ve sayım, toplam, ortalama gibi hesaplamaları render anında her grafiğin dataFunction alanına bırakın.
dashboard - yukarıdan aşağıya 1 ile 40 arasında üst düzey widget (zorunlu). Her widget; bir dash_chart (bir grafik türü - area, bar, cell, dot, hexbin veya line - x, y, d ve r için sütun eşlemeleri, isteğe bağlı bir dataFunction ve isteğe bağlı bir başlık), bir dash_table, bir dash_text bloğu, bir dash_spacer ya da bir dash_stacker_hor/dash_stacker_ver konteyneridir. Yığıcılar özyinelemeli olarak iç içe geçer - bir yığıcının kendi alt öğeleri de başka yığıcılar içerebilir - böylece widget’lar keyfi derinlikte satır ve sütunlar halinde düzenlenebilir. Her grafik türünün x/y/d/r boyutlarının hangi sütun türlerini (kategorik, sürekli veya tarih/zaman) kabul ettiği ve seasonX/seasonY ile bir tarih sütununu zaman dilimlerine ayırmanın onu nasıl kategorik hale getirdiği, her alan için tools/list üzerinden ve Veri Formatı sayfasında belgelenmiştir.
theme - isteğe bağlı, dashboard geneli renkler (arka plan, metin, birincil/ince/ikincil vurgular); her widget yine de kendi rengini veya arka planını geçersiz kılabilir
shared - dashboard’un bağlantıya sahip herkes tarafından görüntülenip görüntülenemeyeceği (isteğe bağlı, varsayılan false). Yeni dashboard’lar, bunu true olarak ayarlayana veya daha sonra set_sharing çağrısı yapana kadar özeldir.

Sonuç; yeni dashboard’un (daha sonra add_data, get_dataset_schema, set_sharing ve get_embed_code için gereken) dashboardId ve datasetId değerlerini, ayrıca url, viewUrl değerlerini ve iframe yerleştirme kod parçacığını taşır. Örnek - çubuk grafikli ve dashboard geneli bir vurgu rengine sahip bir dashboard oluşturma:

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 - Bir dashboard’un adını, paylaşım durumunu, veri kümesi kimliklerini ve bağlantılarını döndürür. Parametre: dashboardId (zorunlu). Örnek:

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 - Hesabınızdaki dashboard’ları, son güncellemeye göre sıralı olarak listeler; her biri kendi datasetIds değerine sahiptir, böylece ayrı bir get_dashboard çağrısı yapmadan bir veri kümesi doğrudan get_dataset_schema veya add_data’ya iletilebilir. Parametreler: sayfalama için limit ve offset, büyük/küçük harfe duyarsız bir ad filtresi için query (tümü isteğe bağlı). Örnek:

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 - Mevcut bir dashboard’un veri kümesine satır ekler; veri kümesini kullanan her dashboard otomatik olarak yenilenir. Parametreler:

dashboardId - eklemenin yapılacağı dashboard (zorunlu)
entries - veri kümesinin başlıklarıyla konumsal olarak hizalanmış satırlar, çağrı başına en fazla 50.000 (zorunlu) - create_dashboard ile aynı ham, satır düzeyinde kural geçerlidir. Dashboard’un tam sütun adlarını/sırasını henüz bilmiyorsanız önce get_dataset_schema çağrısı yapın. Büyük veri kümelerini gruplar halinde yüklemek veya dashboard’ları güncel tutmak için kullanın.
run_id - bu belirli grup için isteğe bağlı bir idempotency anahtarı (isteğe bağlı). Aynı dashboardId ve run_id ile yapılan önceki bir add_data çağrısı zaten başarılı olduysa, yeniden çağırmak satırları ikinci kez eklemek yerine önceki sonucu döndürür; böylece bir zaman aşımı veya bağlantı kopması sonrasında bir grup güvenle yeniden denenebilir - her ayrı grup için yeni bir run_id kullanın (örneğin bir UUID veya içeriğinin bir hash’i).

Örnek:

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 - Bir veri kümesinin sütun adlarını ve türlerini döndürür. Tam sütun adları/sırası/türleri henüz bilinmediğinde - örneğin yeni bir oturumda veya dashboard’u başka bir ajan oluşturduğunda - add_data çağrısından önce (veya aynı veri kümesine karşı yeni bir grafik oluştururken) kullanın. Parametre: datasetId (zorunlu). Örnek:

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 - Bir dashboard’un herkese açık bağlantısını açar veya kapatır. Kapatmak, dashboard’un önceki her sürümüne erişimi de iptal eder; bu nedenle geçmişte paylaşılmış bir bağlantı çalışmaz hale gelir. Parametreler: dashboardId ve shared (ikisi de zorunlu). Örnek:

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 - Bir dashboard için paylaşılabilir görüntüleme bağlantısını ve bir iframe yerleştirme kod parçacığını döndürür - bunlar tekrar tek başlarına gerektiğinde, create_dashboard ve set_sharing’in zaten döndürdüğü aynı bağlantı/yerleştirme koduyla aynıdır. Bağlantı, yalnızca dashboard paylaşılırken başkaları için çalışır. Parametre: dashboardId (zorunlu). Örnek:

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 - Hesabın ne kadar depolama alanı kullandığını ve ne kadarının kaldığını bildirir; planın depolama sınırını zorlayacak kadar büyük bir create_dashboard veya add_data çağrısından önce yararlıdır. Parametre yoktur. Örnek:

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
}

Limitler ve Hatalar

MCP uç noktası, istemci başına dakikada 25 istek ve 25 MB’a kadar istek gövdesi kabul eder - daha büyük veri kümelerini add_data gruplarıyla yükleyin.
Veri kümeleri çağrı başına en fazla 100 sütun ve 50.000 satır kabul eder, bir dashboard ise her iç içe geçme düzeyinde en fazla 40 widget kabul eder. Saklanan dashboard’lar planınızın depolama kotasına dahildir - büyük bir create_dashboard veya add_data çağrısından önce kalan alanı kontrol etmek için storage_status çağrısı yapın.
Standart HTTP durum kodları kullanılır: eksik veya geçersiz kimlik bilgileri için 401 (kaynak meta verilerine işaret eden bir WWW-Authenticate zorlaması ile), iptal edilmiş veya yetersiz kimlik bilgileri için 403, aşırı büyük istekler için 413 ve hız sınırlamasına takıldığında 429.