Integrations

Overview

This guide shows how to register the Lightcast MCP server in Cursor via .cursor/mcp.json. Cursor supports native remote MCP over HTTP with environment-variable expansion in headers no stdio bridge required.

Use this integration when you want Lightcast labor-market tools available to Cursor Agent in a specific project or across all workspaces.

Prerequisites

• Cursor IDE(latest release)
• Credentials from Lightcast onboarding (see Authentication)
• LIGHTCAST_ACCESS_TOKEN exported in the environment Cursor can read
• Network access to your Auth0 domain and MCP endpoint

Authentication

This integration uses OAuth 2.0 Client Credentials. For credentials, token lifecycle, and security requirements, see Authentication.

Note: Fetch a JWT from Auth0 using LIGHTCAST_* credentials, export it as LIGHTCAST_ACCESS_TOKEN, and Cursor interpolate ${env:LIGHTCAST_ACCESS_TOKEN} into the Authorization header on each MCP HTTP request.

For the exact Auth0 token HTTP request, see Token Request Reference.

Configure the MCP server

Config file location

Create .cursor/mcp.json in your project root with the following content. Replace <MCP_ENDPOINT> with the endpoint URL provided during Lightcast onboarding.

{
  "mcpServers": {
    "lightcast": {
      "url": "<MCP_ENDPOINT>",
      "headers": {
        "Authorization": "Bearer ${env:LIGHTCAST_ACCESS_TOKEN}",
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Important — environment visibility

Cursor resolves ${env:...} from the environment of the process that launched the IDE. Shell
variables set only in .bashrc or profile scripts may not be visible when Cursor starts
from a desktop shortcut.

Options:

1. Export LIGHTCAST_ACCESS_TOKEN system-wide (Windows User Environment Variables, macOS
   launchctl, Linux /etc/environment).
2. Launch Cursor from a terminal where the token is already exported: cursor .
3. Use a local MCP proxy that handles OAuth refresh (see [Python Integration]) and point
   Cursor at the proxy URL instead of <MCP_ENDPOINT> directly.

Set up the integration

1. Create .cursor/mcp.json in your project root using the JSON shown in Configure the MCP server.
2. Obtain an access token. See Python Integration for instructions.
3. Export the token before you launch Cursor.

Windows PowerShell (current session):

$env:LIGHTCAST_ACCESS_TOKEN = "<ACCESS_TOKEN>"
cursor .

Windows (persistent user variable):

[System.Environment]::SetEnvironmentVariable(
  "LIGHTCAST_ACCESS_TOKEN",
  "<ACCESS_TOKEN>",
  "User"
)

Restart Cursor after setting a persistent environment variable.

4. Reload the Cursor window: open the Command Palette and select Developer: Reload Window.

Example: full project setup

Project layout

auth_mcp/
├── .cursor/
│   └── mcp.json
└── examples/
    └── python/
        └── lightcast_mcp_client.py

.cursor/mcp.json

{
  "mcpServers": {
    "lightcast": {
      "url": "<MCP_ENDPOINT>",
      "headers": {
        "Authorization": "Bearer ${env:LIGHTCAST_ACCESS_TOKEN}",
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Token refresh and launch

# Fetch token using Python client or PowerShell OAuth call
$body = @{
  grant_type    = "client_credentials"
  client_id     = "<CLIENT_ID>"
  client_secret = "<CLIENT_SECRET>"
  audience      = "<AUDIENCE>"
} | ConvertTo-Json

$response = Invoke-RestMethod `
  -Method Post `
  -Uri "<OAUTH_DOMAIN>/oauth/token" `
  -ContentType "application/json" `
  -Body $body

$env:LIGHTCAST_ACCESS_TOKEN = $response.access_token

### Launch Cursor from this shell so it inherits the token
cursor .

Test with an agent prompt

In Cursor Agent, enter the following prompt:

Use the Lightcast MCP glossary tool and summarize the available datasets.

Cursor call glossary and return dataset metadata in the agent response.

Verification

1. Go to Cursor Settings → MCP and confirm lightcast appears under project servers.
2. Check that the server status shows as connected (green indicator).
3. Confirm ${env:LIGHTCAST_ACCESS_TOKEN} is not sent literally check MCP logs
   if tool calls return 401.
4. Run an agent prompt that invokes glossary and verify a successful response.

How it Works

sequenceDiagram
    participant Dev as Developer
    participant Cursor as Cursor_Agent
    participant MCP as Lightcast_MCP

    Dev->>Cursor: Agent prompt with MCP tools
    Note over Cursor: Reads .cursor/mcp.json
    Cursor->>MCP: POST Streamable HTTP Bearer LIGHTCAST_ACCESS_TOKEN
    MCP-->>Cursor: tools/list catalog
    Cursor->>MCP: POST tools/call glossary
    MCP-->>Cursor: Dataset metadata
    Cursor-->>Dev: Answer with Lightcast data

Cursor resolves ${env:LIGHTCAST_ACCESS_TOKEN} when loading MCP configuration and attaches the Bearer token to every HTTP request against <MCP_ENDPOINT>.

Troubleshoot common errors

Production Recommendations

• Commit .cursor/mcp.json with ${env:...} placeholders. Never commit tokens to source control..
• Schedule hourly token refresh and update LIGHTCAST_ACCESS_TOKEN before it expires.
• Document the token refresh script in your project README so team members can follow the same process.
• For long-running sessions, consider a local OAuth proxy instead of manual token refresh.
• For token caching and credential rotation, see Authentication.

Overview

This guide shows how to register the Lightcast MCP server in Claude Desktop by using the mcp-remote bridge. Claude Desktop communicates with MCP servers over stdio. The mcp-remote bridge forwards tool calls to the remote Lightcast Streamable HTTP endpoint by using your OAuth access token.

Use this integration to access Lightcast labor market tools from the Claude Desktop application on Windows, macOS, or Linux.

Prerequisites

• Claude Desktop (latest release)
• Node.js 18 or later installed (required to run npx and mcp-remote)
• Credentials provided during Lightcast onboarding. For more information, see Authentication.
• A valid OAuth access token. For more information, see Python Integration.
• Network access to your Auth0 domain and the MCP endpoint.

Configuration

Config file location

On Windows, %APPDATA% typically resolves to C:\Users\<username>\AppData\Roaming.

Complete claude_desktop_config.json

Create or update your Claude Desktop configuration file with the following configuration. Replace <MCP_ENDPOINT> with your Lightcast MCP URL and <ACCESS_TOKEN> with an access token obtained through the Auth0 Client Credentials flow.

{
  "mcpServers": {
    "lightcast": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<MCP_ENDPOINT>",
        "--header",
        "Authorization: Bearer ${TOKEN}"
      ],
      "env": {
        "TOKEN": "<ACCESS_TOKEN>"
      }
    }
  }
}

Important

Access tokens expire after one hour. Refresh <ACCESS_TOKEN> in the env block before it
expires, or automate token refresh by using a wrapper script for example see Complete
Working Example).

Authentication

This integration uses the OAuth 2.0 Client Credentials flow. For information about credentials, token lifetime, and security requirements, see Authentication.

How authentication works

Exchange your LIGHTCAST_* credentials for a JWT by using Auth0. Then set the TOKEN environment variable in claude_desktop_config.json so that mcp-remote includes the Authorization: Bearer <token> header in every MCP HTTP request.

For the Auth0 token request, see Token request reference.

Installation

1. Install Node.js 18 or later from nodejs.org.
2. Verify that npx is available:

npx --version

3. Optionally, prefetch mcp-remote to reduce the startup time when you launch Claude Desktop for the first time:

npx -y mcp-remote --help

4. Obtain an access token by using the Python client in Python integration or the curl example in the Token request reference.
5. Update %APPDATA%\Claude\claude_desktop_config.json on Windows (or the appropriate configuration file for your platform) with the complete JSON shown in Configuration.
6. Quit Claude Desktop completely, and then restart it.

Complete Working Example

Step 1: Get an access token

Use PowerShell and your Lightcast credentials to get an access token:

$body = @{
  grant_type    = "client_credentials"
  client_id     = "<CLIENT_ID>"
  client_secret = "<CLIENT_SECRET>"
  audience      = "<AUDIENCE>"
} | ConvertTo-Json

$response = Invoke-RestMethod `
  -Method Post `
  -Uri "<OAUTH_DOMAIN>/oauth/token" `
  -ContentType "application/json" `
  -Body $body

$token = $response.access_token
Write-Host "Token obtained (expires_in: $($response.expires_in)s)"

Step 2: Update the Claude Desktop configuration

Add the access token to env.TOKEN in claude_desktop_config.json:

{
  "mcpServers": {
    "lightcast": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<MCP_ENDPOINT>",
        "--header",
        "Authorization: Bearer ${TOKEN}"
      ],
      "env": {
        "TOKEN": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
      }
    }
  }
}

Step 3: Verify the integration in Claude Desktop

1. Restart Claude Desktop.
2. Open a new chat.
3. Verify that the Lightcast MCP server appears in the tools or plugins panel.
4. Ask: "Call the glossary tool and summarize the available datasets."

Claude call glossary and return dataset metadata in the agent response.

Verification

1. Verify that %APPDATA%\Claude\claude_desktop_config.json contains the complete mcpServers.lightcast configuration and that the JSON is valid.
2. Restart Claude Desktop after each configuration change.
3. Verify that the Lightcast tools (glossary, tool_info, classify, and others) appear in the MCP tools list.
4. Run a prompt that calls the glossary tool, and verify that it returns a successful response.

How it Works

sequenceDiagram
    participant User as Claude_Desktop_User
    participant CD as Claude_Desktop
    participant MR as mcp_remote_stdio
    participant MCP as Lightcast_MCP

    User->>CD: Prompt using Lightcast tools
    CD->>MR: MCP over stdio
    MR->>MCP: POST Streamable HTTP Bearer TOKEN
    MCP-->>MR: Tool results
    MR-->>CD: MCP tool response
    CD-->>User: Answer with Lightcast data

Claude Desktop does not connect to the MCP HTTP endpoint directly. Instead, the mcp-remote process translates stdio MCP messages into authenticated HTTP requests to <MCP_ENDPOINT>.

Troubleshoot Common Errors

Production Recommendations

• Do not commit claude_desktop_config.json with active access tokens to source control.

• Automate hourly access token refresh. Access tokens expire after 3,600 seconds.

• Pin mcp-remote to a specific version in production if your organization requires reproducible builds.

• Restrict access to the Claude Desktop configuration file to the current user account.

• For information about token caching and credential rotation, see Authentication.

  ---

Overview

This guide shows how to call the Lightcast MCP server through the OpenAI Responses API hosted MCP tool. OpenAI's runtime performs tools/list and tools/call against your remote MCP endpoint; your application supplies a fresh Lightcast OAuth access token on every request via the authorization field.

Use this integration to let OpenAI orchestrate MCP tool discovery and execution on the server without running the OpenAI Agents SDK locally.

Note: This guide covers the Responses API (client.responses.create). If you want to use the OpenAI Agents SDK with MCPServerStreamableHttp, see Agent Builder integration.

Prerequisites

• Python 3.10 or later.

• pip.

• Credentials provided during Lightcast onboarding. For more information, see Authentication.

• An OpenAI API key with access to Responses API models.

• Network access to your Auth0 domain, the MCP endpoint, and the OpenAI API.

  ---

Configuration

Create a .env file in your project root:

LIGHTCAST_CLIENT_ID=<CLIENT_ID>
LIGHTCAST_CLIENT_SECRET=<CLIENT_SECRET>
LIGHTCAST_OAUTH_DOMAIN=<OAUTH_DOMAIN>
LIGHTCAST_AUDIENCE=<AUDIENCE>
LIGHTCAST_MCP_ENDPOINT=<MCP_ENDPOINT>
OPENAI_API_KEY=<OPENAI_API_KEY>

Note: Do not commit the .env file to source control. Add it to .gitignore.

Authentication

This integration uses the OAuth 2.0 Client Credentials flow. For information about credentials, token lifetime, and security requirements, see Authentication.

How authentication works

Load the LIGHTCAST_* environment variables. TokenCache exchanges the credentials at {OAUTH_DOMAIN}/oauth/token and passes the access token to OpenAI in the MCP tool authorization field with every Responses API request. OpenAI then forwards the token to Lightcast with each MCP HTTP request.

For the Auth0 token request, see Token request reference.

Installation

Create requirements.txt:

openai>=1.82.0
httpx>=0.28.0
python-dotenv>=1.1.0

Install dependencies:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

On Windows PowerShell:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Complete Working Example

Save the following as lightcast_openai_responses.py:

"""Lightcast MCP Platform — OpenAI Responses API with remote MCP tool."""

from __future__ import annotations

import json
import os
import threading
import time
from typing import Any

import httpx
from dotenv import load_dotenv
from openai import OpenAI

TOKEN_EXPIRY_BUFFER_SECONDS = 60
DEFAULT_TIMEOUT_SECONDS = 30.0


class LightcastConfig:
    def __init__(
        self,
        client_id: str,
        client_secret: str,
        oauth_domain: str,
        audience: str,
        mcp_endpoint: str,
    ) -> None:
        self.client_id = client_id
        self.client_secret = client_secret
        self.oauth_domain = oauth_domain
        self.audience = audience
        self.mcp_endpoint = mcp_endpoint

    @classmethod
    def from_env(cls) -> LightcastConfig:
        load_dotenv()
        return cls(
            client_id=_require_env("LIGHTCAST_CLIENT_ID"),
            client_secret=_require_env("LIGHTCAST_CLIENT_SECRET"),
            oauth_domain=_require_env("LIGHTCAST_OAUTH_DOMAIN"),
            audience=_require_env("LIGHTCAST_AUDIENCE"),
            mcp_endpoint=_require_env("LIGHTCAST_MCP_ENDPOINT"),
        )


def _require_env(name: str) -> str:
    value = os.getenv(name)
    if not value:
        raise RuntimeError(f"Missing required environment variable: {name}")
    return value


class TokenCache:
    """Thread-safe OAuth access token cache with early refresh."""

    def __init__(self) -> None:
        self._lock = threading.Lock()
        self._token: str | None = None
        self._expires_at: float = 0.0

    def get_token(self, fetch_fn: Any) -> str:
        with self._lock:
            if self._token and time.time() < self._expires_at - TOKEN_EXPIRY_BUFFER_SECONDS:
                return self._token
            token, expires_in = fetch_fn()
            self._token = token
            self._expires_at = time.time() + expires_in
            return self._token


def fetch_access_token(config: LightcastConfig, client: httpx.Client) -> tuple[str, int]:
    token_url = f"{config.oauth_domain.rstrip('/')}/oauth/token"
    response = client.post(
        token_url,
        json={
            "grant_type": "client_credentials",
            "client_id": config.client_id,
            "client_secret": config.client_secret,
            "audience": config.audience,
        },
        headers={"Content-Type": "application/json"},
        timeout=DEFAULT_TIMEOUT_SECONDS,
    )
    response.raise_for_status()
    payload = response.json()
    access_token = payload.get("access_token")
    if not access_token:
        raise RuntimeError("Token response missing access_token")
    expires_in = int(payload.get("expires_in", 3600))
    return access_token, expires_in


def main() -> None:
    load_dotenv()
    _require_env("OPENAI_API_KEY")
    config = LightcastConfig.from_env()

    token_cache = TokenCache()
    http = httpx.Client(timeout=DEFAULT_TIMEOUT_SECONDS)

    def get_lightcast_token() -> str:
        return token_cache.get_token(lambda: fetch_access_token(config, http))

    client = OpenAI()

    response = client.responses.create(
        model="gpt-4.1-mini",
        input=(
            "Use the Lightcast MCP glossary tool and summarize which datasets "
            "are available in one short paragraph."
        ),
        tools=[
            {
                "type": "mcp",
                "server_label": "lightcast",
                "server_description": "Lightcast labor-market MCP platform",
                "server_url": config.mcp_endpoint,
                "authorization": get_lightcast_token(),
                "allowed_tools": ["glossary"],
                "require_approval": "never",
            }
        ],
    )

    print("Response output:")
    print(response.output_text)

    mcp_items = [
        item for item in response.output if getattr(item, "type", None) == "mcp_call"
    ]
    if mcp_items:
        print("\nMCP tool calls:")
        print(json.dumps([item.model_dump() for item in mcp_items], indent=2, default=str))


if __name__ == "__main__":
    main()

Execution

python lightcast_openai_responses.py

Expected output

Response output:
The Lightcast MCP platform exposes datasets for job postings, profiles,
and related labor-market analytics...

MCP tool calls:
[
  {
    "type": "mcp_call",
    "name": "glossary",
    ...
  }
]

The OpenAI Responses runtime calls tools/list on <MCP_ENDPOINT> by using your bearer token. It then call the glossary tool and returns the model's summary in output_text.

Verification

1. Run python lightcast_openai_responses.py.
2. Verify that output_text summarizes the dataset information returned by the glossary tool.
3. Verify that the printed MCP call list includes a glossary tool invocation.
4. Verify that the response object does not include an error field.

How it works

sequenceDiagram
    participant App as Your_Application
    participant Auth as TokenCache
    participant Auth0 as Auth0_Token_Endpoint
    participant OAI as OpenAI_Responses_API
    participant MCP as Lightcast_MCP

    App->>Auth: get_token()
    Auth->>Auth0: POST /oauth/token
    Auth0-->>Auth: access_token JWT
    App->>OAI: responses.create mcp tool + authorization
    OAI->>MCP: tools/list Bearer token
    MCP-->>OAI: Tool catalog
    OAI->>MCP: tools/call glossary
    MCP-->>OAI: Dataset metadata
    OAI-->>App: output_text

Troubleshoot Common Errors

Production Recommendations

• Per-request tokens: OpenAI does not persist the authorization field. Always get or cache a valid Lightcast access token and include it with every Responses API request.

• Tool allowlists: Use allowed_tools to limit imported schemas and reduce latency, as shown with glossary.

• Approvals: Set require_approval to "always" or use an allowlist until you trust automated tool execution in production.

• Model pinning: Pin a specific model ID in your configuration instead of relying on the default model.

• Observability: Log OpenAI response IDs and MCP call items. Never log access tokens or client secrets.

• For information about credential rotation, see Authentication.

  ---

Overview

Custom agents are partially implemented through generic MCP endpoint compatibility. A custom MCP-capable agent can consume the Lightcast MCP endpoint, but no Lightcast-provided custom-agent SDK or adapter is implemented.

Compatibility Notes

Custom agents should connect to Lightcast MCP as generic MCP clients. After connection, they should follow the standard workflow: glossary, tool_info, classify, and then the relevant analysis tool.

Future Validation Requirements

• Validate one or more reference custom-agent implementations.
• Document recommended client behavior for schema discovery, taxonomy classification, and error handling.
• Define hosted access and authentication expectations before publishing hosted-agent guidance.