groundlight

The Groundlight MCP server provides a suite of tools to manage detectors, submit images for evaluation, and handle alerts within Groundlight’s computer vision workflow. It exposes detectors creation and retrieval (create_detector, get_detector, list_detectors), image query submission and retrieval (submit_image_query, get_image_query, list_image_queries, get_image), and alert management (create_alert, list_alerts, delete_alert). You can also enrich results with labels (add_label) and fetch detector evaluation metrics (get_detector_evaluation_metrics), along with controls to update detector behavior such as confidence thresholds (update_detector_confidence_threshold) and escalation policy (update_detector_escalation_type). Detectors can operate in binary, multiclass, or counting modes, and results carry confidence scores suitable for human review escalation when necessary.

To use the tools, connect your MCP client (e.g., Claude Desktop or Zed) to the Groundlight MCP server endpoint and authenticate with your Groundlight API token. You can create detectors by providing a DetectorConfig (name, query, threshold, mode, and mode-specific settings), submit images for evaluation by a given detector, then retrieve results and per-image details. You can also create alerts that trigger actions (webhook, email, or text) when detector conditions are met, and you can annotate results with labels to improve model performance over time.

Typical workflows include: creating a detector configured for a specific object or scene, submitting representative images to obtain labels and confidence scores, reviewing borderline results with the escalation system, and iterating on detector configuration and labeled feedback to improve accuracy over time.

Prerequisites:\n- Docker must be installed and running on your machine or server.\n- Access to a Groundlight API token to authorize API requests.\n\nInstallation steps:\n1) Obtain Groundlight API token from your Groundlight account.\n2) Install Docker if it is not already installed (see docker.com for instructions).\n3) Pull/run the Groundlight MCP server container as described in the README:\n\nExample run (from the repository root or any suitable directory):\n\nbash\n# Set your API token (replace with your actual token)\nexport GROUNDLIGHT_API_TOKEN=YOUR_API_TOKEN_HERE\n\n# Run the MCP server container (docker)\ndocker run --rm -i -e GROUNDLIGHT_API_TOKEN groundlight/groundlight-mcp-server\n\n\nIf you are integrating with Claude Desktop or Zed, configure your client to point to the Groundlight MCP server as shown in the README: the server runs under the name "groundlight" with the appropriate docker args and environment variable.\n\nOptional: build or pull a specific image if you are modifying the server or using a custom build pipeline, then run the container with the same environment variable to connect to Groundlight.\n\nNotes:\n- Ensure your environment variable GROUNDLIGHT_API_TOKEN is kept secret and not checked into version control.\n- If you encounter network or token errors, verify token permissions and that the container has network access to Groundlight services.

Tips and considerations:\n- The server supports multiple detector modes (binary, multiclass, counting). When creating detectors, specify the mode and the mode-specific configuration to tailor behavior to your use case.\n- Each image query returns a confidence score; set a suitable confidence_threshold to control escalation to human review.\n- Use list_alerts and delete_alert to manage alerting rules; alerts can trigger webhooks, emails, or texts.\n- When using Claude Desktop or Zed, you can provide the mcpServers configuration under mcpServers (Groundlight) with docker run arguments and an environment block for GROUNDLIGHT_API_TOKEN.\n- To experiment safely, start with a simple detector (e.g., a binary detector for a basic object) and gradually add complexity (multiclass or counting) as you validate results.\n- Remember that large lists of image queries can be returned by list_image_queries; implement pagination using page and page_size if supported by your client.\n- If you are scripting against the MCP server, refer to the available inputs and outputs of each tool (DetectorConfig, Detector, ImageQuery, Rule, etc.) to align your data structures with your application.