MCP API

개요

Sprucely.io MCP API는 HTTP를 통해 AI 모델을 도구와 연결하는 개방형 표준인 Model Context Protocol(MCP)을 통해 대시보드 플랫폼을 AI 어시스턴트와 서드파티 소프트웨어에 노출합니다. 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

HTTP를 통해 JSON-RPC 2.0으로 서버를 직접 호출할 수도 있습니다. 대부분의 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 플로우, 리프레시 토큰, 동적 클라이언트 등록을 지원하므로, 호환되는 클라이언트는 리소스 메타데이터를 바탕으로 자동으로 설정됩니다:

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.

아래의 dataset 및 dashboard 파라미터는 MCP 전용 형식이 아니라, 데이터 형식 페이지에 문서화되어 있고 서비스 전반(독립형 임베드 런타임의 가져오기 API, AI가 생성한 레이아웃, 대시보드 편집기)에서 사용되는 것과 정확히 동일한 dataset/dashboard JSON입니다. 따라서 해당 레퍼런스에 적용되는 모든 내용은 여기에도 그대로 적용됩니다.

create_dashboard - 인라인 데이터셋과 위젯 트리로부터 호스팅형 대시보드를 생성하고, 보기 링크와 임베드 링크를 반환합니다. 파라미터:

name - 대시보드 제목입니다(필수).
dataset - 시각화할 데이터셋입니다: name, headers(컬럼 이름), types(헤더별로 하나씩 지정하는 데이터베이스 타입 - VARCHAR, BOOLEAN, INTEGER, BIGINT, FLOAT, DOUBLE, DATE 또는 TIMESTAMP), entries(행이며, 각 행은 헤더 순서에 따른 값의 배열)로 구성되며, 호출당 최대 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 컨테이너 중 하나입니다. 스태커는 재귀적으로 중첩될 수 있으며 - 스태커 자신의 자식 요소에 또 다른 스태커를 포함할 수 있습니다 - 이를 통해 위젯을 임의의 깊이로 행과 열로 배치할 수 있습니다. 각 차트 유형의 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 - 대시보드의 이름, 공유 상태, 데이터셋 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 - 데이터셋의 헤더 순서에 맞춰 위치별로 정렬된 행이며, 호출당 최대 50,000개까지 가능합니다(필수) - create_dashboard와 동일하게 원시 행 단위 규칙이 적용됩니다. 대시보드의 정확한 컬럼 이름/순서를 모른다면 먼저 get_dataset_schema를 호출하십시오. 대용량 데이터셋을 배치 단위로 적재하거나 대시보드를 최신 상태로 유지하는 데 사용합니다.
run_id - 이 배치에 대한 선택적 idempotency 키입니다(선택). 동일한 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 엔드포인트는 클라이언트당 분당 25개의 요청과 최대 25MB의 요청 본문을 허용합니다 - 더 큰 데이터셋은 add_data 배치로 나누어 적재하십시오.
데이터셋은 호출당 최대 100개 컬럼과 50,000개 행을, 대시보드는 중첩 단계마다 최대 40개의 위젯을 허용합니다. 저장된 대시보드는 요금제의 스토리지 할당량에 포함되므로, 대용량 create_dashboard나 add_data 호출 전에 storage_status를 호출해 남은 여유 용량을 확인하십시오.
표준 HTTP 상태 코드를 사용합니다: 자격 증명이 없거나 유효하지 않은 경우 401(리소스 메타데이터를 가리키는 WWW-Authenticate 챌린지 포함), 폐기되었거나 권한이 부족한 자격 증명인 경우 403, 요청이 너무 큰 경우 413, 속도 제한에 걸린 경우 429입니다.