MCP API'leri

Connecting

The MCP server is served over Streamable HTTP at:

https://www.sprucely.io/mcp

Any MCP client can connect to this endpoint. For example, one command registers the server in Claude Code:

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

You can also call the server directly with JSON-RPC 2.0 over HTTP. Most MCP clients perform the protocol handshake automatically; the request below lists the available tools using an API key:

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

Authentication

Requests are authorized with a standard Authorization Bearer header. Two credential types are supported.

API keys - Create API keys in the MCP section of your profile. Keys start with spr_mcp_, are shown only once at creation, and can be revoked at any time. Use them for scripts, servers and headless MCP clients.

OAuth 2.1 - Interactive MCP clients can instead let users sign in with their Sprucely.io account through OAuth 2.1. The authorization server supports the authorization code flow with PKCE (required), refresh tokens and dynamic client registration, so compatible clients configure themselves automatically from the resource metadata:

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

Available scopes: openid, offline_access, dashboards:read and dashboards:write.

For clients that require manual configuration, the authorization server endpoints are:

• https://www.sprucely.io/oauth/.well-known/openid-configuration - authorization server metadata
• https://www.sprucely.io/oauth/auth - authorization endpoint (PKCE required)
• https://www.sprucely.io/oauth/token - token endpoint
• https://www.sprucely.io/oauth/reg - dynamic client registration
• https://www.sprucely.io/oauth/jwks - signing keys (JWKS)
• https://www.sprucely.io/oauth/token/revocation - token revocation
• https://www.sprucely.io/oauth/token/introspection - token introspection

Tools

The MCP server exposes four tools.

create_dashboard - Creates a hosted dashboard from an inline dataset and a set of charts, and returns view and embed links. Parameters:

• name - the dashboard title (required)
• dataset - the dataset to visualize - a name, up to 100 typed columns (string, integer, number, boolean, date or timestamp) and up to 50,000 rows per call, aligned positionally to the columns (required)
• charts - 1 to 40 chart definitions - a chart type (area, bar, cell, dot, hexbin or line), column mappings for x, y, data and radius, an optional aggregate function (count, sum, average, median, min, max or stddev) and an optional title (required)
• direction - stack charts vertically (default) or horizontally (optional)
• shared - whether the dashboard is shared for embedding (optional, default true)

Example - create a dashboard with a single bar chart:

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",
          "columns": [
            { "name": "region", "type": "string" },
            { "name": "revenue", "type": "number" }
          ],
          "rows": [
            ["North", 1250.5],
            ["South", 980.25],
            ["East", 1420.0]
          ]
        },
        "charts": [
          { "chartType": "bar", "x": "region", "y": "revenue", "aggregate": "sum", "title": "Revenue by region" }
        ]
      }
    }
  }'

get_dashboard - Returns a dashboard’s name, sharing status, datasets and links. Parameters: dashboardId (required).

list_dashboards - Lists the dashboards in your account, ordered by last update. Parameters: limit and offset for paging, query for a case-insensitive name filter (all optional).

add_data - Appends rows to an existing dashboard’s dataset; every dashboard using the dataset refreshes automatically. Parameters: dashboardId and rows, aligned positionally to the dataset’s columns (both required). Use it to load large datasets in batches or to keep dashboards up to date.

Limits and Errors

The MCP endpoint accepts 25 requests per minute per client and request bodies up to 25 MB - load larger datasets in add_data batches.

Datasets accept up to 100 columns and 50,000 rows per call, and dashboards between 1 and 40 charts. Stored dashboards count toward your plan’s storage quota.

Standard HTTP status codes are used: 401 for missing or invalid credentials (with a WWW-Authenticate challenge pointing at the resource metadata), 403 for revoked or insufficient credentials, 413 for oversized requests and 429 when rate limited.