@superblocksteam/mcp-server

Implements the Model Context Protocol (MCP) server specification, enabling Superblocks to expose its capabilities as a standardized MCP server that can be discovered and invoked by MCP clients (Claude, other LLMs, and AI agents). Uses the MCP transport layer to handle request/response serialization, resource discovery, and capability advertisement through the protocol's standard mechanisms.

Exposes Superblocks workflows, queries, and actions as discoverable MCP tools with schema-based function signatures. The server introspects Superblocks' workflow definitions and generates MCP tool definitions that include parameter schemas, descriptions, and execution handlers, allowing MCP clients to understand and invoke Superblocks capabilities with type safety.

Implements MCP resource protocol to expose Superblocks data sources, saved queries, and workflow outputs as queryable resources. Uses the MCP resources/list and resources/read mechanisms to allow clients to browse available data resources and retrieve their contents, enabling AI clients to access Superblocks data without direct API calls.

Manages Superblocks API credentials and authentication tokens, handling secure credential storage and passing them to Superblocks API calls made by the MCP server. Uses environment variables or secure configuration to store credentials and implements credential refresh logic if needed, ensuring the MCP server can authenticate with Superblocks on behalf of MCP clients.

Implements the MCP transport layer, handling JSON-RPC 2.0 message serialization, deserialization, and protocol state management. Manages bidirectional communication between MCP clients and the Superblocks server, including request routing, response correlation, and error handling according to the MCP specification.

Validates and coerces parameters passed to Superblocks workflows through MCP tool calls, using workflow parameter schemas to ensure type safety and provide helpful error messages. Implements JSON schema validation against Superblocks workflow definitions and performs type coercion where appropriate (e.g., string to number conversion), preventing invalid workflow executions.

Transforms Superblocks workflow execution results into MCP-compatible response formats, handling different result types (JSON objects, arrays, scalars, errors) and mapping them to MCP tool response structures. Implements result formatting logic that ensures Superblocks outputs are serializable and fit within MCP message constraints, with optional result truncation or summarization for large outputs.

Manages the MCP server lifecycle including startup, configuration loading, Superblocks connection establishment, and graceful shutdown. Implements initialization logic that loads environment variables, validates Superblocks connectivity, discovers available workflows, and registers them as MCP tools before accepting client connections.