MCP API

अवलोकन

Sprucely.io के MCP API, Model Context Protocol (MCP) के ज़रिए डैशबोर्ड प्लेटफ़ॉर्म को AI असिस्टेंट और थर्ड-पार्टी सॉफ़्टवेयर तक पहुंचाते हैं - यह AI मॉडल को HTTP पर टूल्स से जोड़ने का एक ओपन स्टैंडर्ड है। कोई भी MCP-संगत क्लाइंट होस्टेड डैशबोर्ड बना सकता है, उन्हें सूचीबद्ध और जांच सकता है, और प्रोग्रामेटिक रूप से उनमें डेटा जोड़ सकता है। API के ज़रिए बनाए गए डैशबोर्ड आपके खाते के होते हैं और सेवा में इन्हें आगे साझा, एम्बेड या एडिट किया जा सकता है। तैयार डैशबोर्ड को अपनी खुद की साइट में एम्बेड करने के लिए, सरल डैशबोर्ड इंटीग्रेशन नोट्स देखें। यदि आप Claude का उपयोग करते हैं, तो शुरू करने का सबसे तेज़ तरीका है Sprucely.io कनेक्टर।

कनेक्ट करना

MCP सर्वर Streamable HTTP पर यहां उपलब्ध है:

https://www.sprucely.io/mcp

कोई भी MCP क्लाइंट इस एंडपॉइंट से कनेक्ट हो सकता है। उदाहरण के लिए, एक ही कमांड से सर्वर Claude Code में रजिस्टर हो जाता है:

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

आप सर्वर को सीधे JSON-RPC 2.0 के ज़रिए 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 हेडर से प्रमाणित किया जाता है। दो तरह के क्रेडेंशियल समर्थित हैं।

API कुंजियां - अपनी प्रोफ़ाइल के MCP सेक्शन में API कुंजियां बनाएं। कुंजियां spr_mcp_ से शुरू होती हैं, बनते समय केवल एक बार दिखाई जाती हैं, और इन्हें किसी भी समय रद्द किया जा सकता है। इनका उपयोग स्क्रिप्ट, सर्वर और हेडलेस MCP क्लाइंट के लिए करें।

OAuth 2.1 - इंटरैक्टिव MCP क्लाइंट इसके बजाय उपयोगकर्ताओं को OAuth 2.1 के ज़रिए अपने Sprucely.io खाते से साइन इन करने दे सकते हैं। ऑथराइज़ेशन सर्वर PKCE (आवश्यक) के साथ authorization code फ़्लो, रिफ्रेश टोकन और डायनामिक क्लाइंट रजिस्ट्रेशन को सपोर्ट करता है, इसलिए संगत क्लाइंट resource metadata से खुद को अपने आप कॉन्फ़िगर कर लेते हैं:

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

उपलब्ध scopes: openid, offline_access, dashboards:read और dashboards:write। Scopes हर टूल पर अलग-अलग लागू होते हैं: 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।

नीचे दिए गए dataset और dashboard पैरामीटर कोई MCP-विशिष्ट फॉर्मेट नहीं हैं - ये बिल्कुल वही dataset/dashboard JSON हैं जो डेटा प्रारूप पेज पर दस्तावेज़ीकृत हैं और सेवा में हर जगह उपयोग होते हैं (स्टैंडअलोन एम्बेड करने योग्य रनटाइम का इम्पोर्ट API, AI-जनरेटेड लेआउट, और डैशबोर्ड एडिटर), इसलिए उस रेफरेंस के लिए लिखी गई हर बात यहां भी लागू होती है।

create_dashboard - एक इनलाइन dataset और विजेट ट्री से एक होस्टेड डैशबोर्ड बनाता है, और व्यू व एम्बेड लिंक लौटाता है। पैरामीटर:

name - डैशबोर्ड का टाइटल (आवश्यक)
dataset - विज़ुअलाइज़ किया जाने वाला dataset: name, headers (कॉलम के नाम), types (हर header के लिए एक डेटाबेस टाइप - VARCHAR, BOOLEAN, INTEGER, BIGINT, FLOAT, DOUBLE, DATE या TIMESTAMP) और entries (पंक्तियां, हर एक header क्रम में वैल्यू की एक ऐरे), प्रति कॉल अधिकतम 100 कॉलम और 50,000 कच्ची, पंक्ति-स्तरीय entries (आवश्यक)। Entries पहले से एग्रीगेट नहीं होनी चाहिए: हर अंतर्निहित रिकॉर्ड के लिए एक पंक्ति भेजें, और गिनती, योग, और औसत जैसी गणनाएं रेंडर के समय हर चार्ट के 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 कंटेनर। स्टैकर्स रिकर्सिवली नेस्ट होते हैं - किसी स्टैकर के अपने children में आगे और स्टैकर्स भी शामिल हो सकते हैं - ताकि विजेट्स को मनमाने गहराई की पंक्तियों और कॉलम में व्यवस्थित किया जा सके। हर चार्ट टाइप के 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 एम्बेड स्निपेट। उदाहरण - एक bar चार्ट और डैशबोर्ड-व्यापी accent रंग के साथ एक डैशबोर्ड बनाएं:

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 - किसी डैशबोर्ड का नाम, शेयरिंग स्टेटस, dataset 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 होता है ताकि किसी dataset को अलग से 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 - किसी मौजूदा डैशबोर्ड के dataset में entries जोड़ता है; उस dataset का उपयोग करने वाला हर डैशबोर्ड अपने आप रिफ्रेश हो जाता है। पैरामीटर:

dashboardId - जिस डैशबोर्ड में जोड़ना है (आवश्यक)
entries - dataset के headers के क्रम से मेल खाती पंक्तियां, प्रति कॉल अधिकतम 50,000 (आवश्यक) - create_dashboard जैसा ही कच्ची, पंक्ति-स्तरीय नियम यहां भी लागू होता है। अगर आपको डैशबोर्ड के सटीक कॉलम नाम/क्रम पहले से नहीं पता, तो पहले get_dataset_schema को कॉल करें। बड़े dataset को बैचों में लोड करने के लिए, या डैशबोर्ड को अप टू डेट रखने के लिए इसका उपयोग करें।
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 - किसी dataset के कॉलम नाम और टाइप लौटाता है। जब भी सटीक कॉलम नाम/क्रम/टाइप पहले से मालूम न हों - जैसे किसी नए सेशन में, या जब डैशबोर्ड किसी दूसरे एजेंट ने बनाया हो - तो add_data कॉल करने से पहले (या उसी dataset पर कोई नया चार्ट बनाने से पहले) इसका उपयोग करें। पैरामीटर: 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 एंडपॉइंट प्रति क्लाइंट प्रति मिनट 25 अनुरोध और 25 MB तक के रिक्वेस्ट बॉडी स्वीकार करता है - बड़े dataset को add_data बैचों में लोड करें।
Dataset प्रति कॉल अधिकतम 100 कॉलम और 50,000 पंक्तियां स्वीकार करते हैं, और एक डैशबोर्ड नेस्टिंग के हर स्तर पर अधिकतम 40 विजेट स्वीकार करता है। सेव किए गए डैशबोर्ड आपके प्लान के स्टोरेज कोटा में गिने जाते हैं - किसी बड़े create_dashboard या add_data कॉल से पहले बची हुई जगह जांचने के लिए storage_status को कॉल करें।
मानक HTTP स्टेटस कोड इस्तेमाल होते हैं: 401 गुम या अमान्य क्रेडेंशियल के लिए (resource metadata की ओर इशारा करने वाली WWW-Authenticate चुनौती के साथ), 403 रद्द किए गए या अपर्याप्त क्रेडेंशियल के लिए, 413 अत्यधिक बड़े अनुरोध के लिए, और 429 रेट लिमिट होने पर।