Architecture

Overview

Lightcast MCP provides a single MCP endpoint that exposes selected Lightcast labor market capabilities through Streamable HTTP.

Instead of interacting with multiple APIs or services directly, MCP-compatible clients discover available capabilities through MCP tools, validate requests against published schemas, and retrieve analytical results through a consistent tool-based interface.

All communication between the client and server uses the MCP tool model, providing a consistent experience across supported datasets and analysis workflows.

Architecture Layers

Lightcast MCP is organized into five customer-visible layers. Each layer has a distinct responsibility within the request lifecycle.

Layer	Role
MCP-compatible Client	An AI assistant, agent, or MCP-compatible client that connects to Lightcast MCP.
Lightcast MCP Endpoint	Receives tool requests, validates inputs, and returns standardized responses.
Tool Layer	Metadata and analysis tools that expose discovery, schema validation, classification, aggregation, ranking, distribution, time series, and listing behavior.
Dataset Layer	Product-level datasets: `job_postings` or `profiles` that define the logical data surface each tool operates on.
Lightcast Data Services	Provides the labor market data used to generate analytical results. Clients do not interact with this layer directly.

Dataset Abstraction

A dataset is the logical data surface a tool operates on. Datasets are not physical data stores or raw backend APIs. They are customer-facing abstractions that define the type of labor market questions being asked.

Datasets define the type of labor market question being analyzed.

Selecting the appropriate dataset is the first step in every analytical workflow.

Dataset	Primary Analytical Lens
`job_postings`	Labor demand signals derived from deduplicated online job advertisements
`profiles`	Labor supply signals derived from professional profile records
`core_lmi`	Government-sourced labor market data

To identify which dataset fits a user's question, call glossary first. For full dataset specifications, see Datasets.

Tool Abstraction

Lightcast MCP tools are grouped into metadata and analysis capabilities.

Tool Group	Tools	Purpose
Metadata Tools	`glossary`, `tool_info`, `classify`	Discover available datasets, retrieve Schemas, and resolve taxonomy identifiers.
Analysis Tools	`count`, `distribution`, `estimate`, `list`, `timeseries`, `top`	Retrieve analytical results from a supported dataset.

Analysis tools are dataset-aware. The same tool produces different results depending on the dataset it is called with. For example, estimate returns advertised salary estimates when called with job_postings, estimated wages when called with profiles, and employment or earnings metrics when called with government_occupations.

Interaction Model

Lightcast MCP uses MCP tools as the primary interaction model. An agent does not need to know the request shape for every dataset in advance. Instead, it can discover and validate its path through the following sequence:

Useglossary to understand available datasets and tools.
Usetool_info to retrieve the exact JSON Schema for the selected dataset and analysis tool pair.
Useclassify when a classifiable dimension requires canonical taxonomy IDs.
Call the selected analysis tool with validated inputs.

Following this sequence ensures that the tool contract is explicit before execution, reducing invalid calls and surfacing errors early. For more information, see Tool contracts.

Deployment Model

Lightcast MCP can be deployed behind a secure HTTPS endpoint, allowing MCP-compatible clients to connect using the standard MCP protocol.

The MCP server acts as the orchestration layer between client applications and the Lightcast data platform, providing a consistent interface for all supported tools and datasets.

Security Model

Lightcast MCP validates tool requests before execution to help ensure supported datasets, tools, dimensions, metrics, and request schemas are used correctly.

Communication between clients and the Lightcast platform follows the deployment's configured security model, while downstream data access is managed by the Lightcast platform.

For the current security model and its known limitations, see Security.