PredictHQ MCP server for AI agents and assistants

Securely connect your AI agents and chatbots (Claude, ChatGPT, Cursor, etc) with PredictHQ MCP or direct API to search events, forecast demand, analyze locations, and compare event impacts through natural language.

PredictHQ logoPredictHQ
Api Key

PredictHQ is an event intelligence platform with APIs for events, demand, and locations. It helps businesses anticipate demand changes and plan with real-world event data.

62 Tools

Try PredictHQ now

Type what you want done — sign in and watch it run live in the Tool Router playground.

TOOL ROUTER PLAYGROUND
PredictHQ
Try asking
TOOLS

Supported Tools

Every PredictHQ action and event your agent gets out of the box.

Calculate Event Features

Calculate one page of daily or weekly ML-ready event features for a required date range using either a Beam analysis or a manually configured location and feature set.

Count Broadcasts

Return the total number of PredictHQ broadcast records matching optional broadcast, schedule, date, viewership, location, and event filters, without returning result records.

Count Events

Get aggregate event counts by category, label, rank level, and the same date, location, rank, attendance, spend, and event filters supported by search.

Create Beam Analysis

Create a Beam analysis that correlates an owned location's events with uploaded demand data.

Create Beam Analysis Group

Create a Beam analysis group that aggregates feature importance across compatible analyses.

Create Forecast Model

Create a forecast model for a Saved Location.

Create Loop Link

Create a hosted Loop link for end users to submit missing events or event feedback, and return both shareable URLs.

Create Saved Location

Create a reusable PredictHQ Saved Location from an exact business point, a custom GeoJSON area, or Geonames place IDs.

Create Saved Location Closure

Create a closure period for a PredictHQ Saved Location.

Create Saved Location Opening Hours

Create opening hours for a Saved Location.

Delete Beam Analysis

Soft-delete a Beam Analysis.

Delete Beam Analysis Group

Delete an existing Beam Analysis Group without deleting the individual analyses in the group.

Delete Forecast Model

Permanently deletes a forecast model and all associated demand data and forecasts.

Delete Loop Link

Soft-delete a Loop link.

Delete Saved Location

Permanently delete a Saved Location and all of its associated insights data.

Delete Saved Location Closure

Delete a closure by ID from the specified PredictHQ Saved Location.

Delete Saved Location Opening Hours

Delete an opening hours record by ID from the specified PredictHQ Saved Location.

Get Beam Analysis

Return the full details of one Beam Analysis, including its location, demand type, rank, readiness status, and processing state.

Get Beam Analysis Feature Importance

Return the Beam feature groups whose statistical significance indicates how strongly they affect an analysis's demand, including the Features API fields recommended for forecasting models.

Get Beam Analysis Group

Return the full details of one Beam Analysis Group, including its member analyses, demand type, readiness status, and processing state.

Get Beam Analysis Group Feature Importance

Return feature-importance results aggregated across the analyses in an existing Beam Analysis Group, including each feature group's Features API fields and p-value.

Get Demand Surges

Return dates with at least the requested demand-surge intensity for a required date and location, including summed predicted attendance.

Get Forecast Model

Retrieves a forecast model by ID, including its readiness status, configuration, accuracy metrics, and location details.

Get Loop Link

Return one Loop Link, including its status, metadata, expiry, and hosted event-submission and event-feedback URLs.

Get Loop Settings

Return the organization name displayed in the hosted Loop interface.

Get Predicted Impact Area

Calculate a polygonal or radial Predicted Impact Area for a business location and industry, returned as GeoJSON.

Get Saved Location

Retrieve a Saved Location by ID, including its geometry, enrichment status, labels, resolved places, summary insights, opening hours, and closures.

Get Saved Location Closure

Return a single closure by ID for the specified Saved Location.

Get Saved Location Opening Hours

Return one opening hours record by its ID for a specified PredictHQ Saved Location.

List Beam Analyses

Return one page of Beam Analyses, with filters for lifecycle state, readiness, groups, demand type, location, labels, update date, and name.

List Beam Analysis Correlation Results

Return one page of results correlating PredictHQ event data with an analysis's transactional demand data for a required lower and upper date bound.

List Beam Analysis Groups

Return one page of Beam Analysis Groups, optionally filtered by update date, name, lifecycle state, readiness, demand interval, or industry.

List Forecast Algorithms

Returns the list of available forecasting algorithms.

List Forecast Model Demand

Return one page of demand data uploaded to a forecast model, optionally filtered by date, as JSON, CSV, or newline-delimited JSON.

List Forecast Models

Return one page of forecast models belonging to the authenticated organization, optionally filtered by text, Saved Location, or readiness status.

List Loop Event Submissions

Return one page of Loop-submitted events matching link, event, user, review, state, category, location, and date filters.

List Loop Feedback Conversations

Return one page of Loop feedback conversations matching record, link, user, feedback type, status, text, and date filters.

List Loop Links

Return one page of hosted Loop links matching text, link, user, and sort filters.

List Model Forecast Results

Return one page of generated forecast results for a trained model, optionally filtered by date and enriched with features or event explainability.

List Place Hierarchies

Return one page of administrative hierarchy chains resolved from either place IDs or coordinates.

List Saved Location Closures

Return one page of closure records for a PredictHQ Saved Location, optionally filtered by the dates on which the records are active.

List Saved Location Insight Events

Return one page of events that impact a specified PredictHQ Saved Location.

List Saved Location Opening Hours

Return one page of opening-hours records for a Saved Location, optionally filtered by the dates on which the records are active.

List Saved Locations

Search and return one page of Saved Locations, including reusable location IDs, geographic definitions, enrichment state, and summary insights.

Refresh Beam Analysis

Rerun correlation and analysis processing for an existing Beam Analysis.

Refresh Beam Analysis Group

Rerun aggregation for an existing Beam Analysis Group.

Replace Beam Analysis

Fully replace an existing Beam analysis using PUT.

Replace Beam Analysis Group

Fully replace an existing Beam analysis group using PUT.

Replace Forecast Model

Fully replace an existing forecast model's mutable configuration.

Replace Loop Link

Fully replace the mutable name, expiry, and metadata of an existing PredictHQ Loop Link using PUT.

Replace Saved Location

Fully replace an existing PredictHQ Saved Location using PUT.

Replace Saved Location Opening Hours

Fully replace one PredictHQ Saved Location opening-hours record.

Search Broadcasts

Return one page of US county-level live-TV broadcast records matching event, geography, status, and date filters.

Search Events

Search for events happening in a location and date range using PredictHQ's event, location, rank, label, attendance, spend, and lifecycle filters.

Search Places

Return one page of places matching text, country, coordinates, place IDs, or administrative type filters.

Train Forecast Model

Triggers asynchronous training for a forecast model that has uploaded demand data and is in an eligible readiness state.

Update Beam Analysis

Partially update one or more fields on an existing Beam analysis without replacing fields that are omitted.

Update Beam Analysis Group

Partially update an existing Beam analysis group using PATCH.

Update Forecast Model

Partially update a forecast model.

Upload Beam Analysis Demand

Upload daily or weekly demand data to an existing Beam analysis.

Upload Forecast Model Demand

Upload historical demand data to an existing forecast model as typed JSON, CSV, or newline-delimited JSON.

Upsert Loop Settings

Create or replace the organization-wide display name used by the hosted Loop interface.

SETUP GUIDE

Connect PredictHQ MCP Tool with your Agent

1

Install Composio

typescript
npm install @composio/core ai @ai-sdk/mcp @ai-sdk/openai
Install the Composio SDK and your agent framework
2

Create a session with MCP enabled

typescript
import { Composio } from "@composio/core";

const composio = new Composio();
const { mcp } = await composio.create("your-user-id", {
  toolkits: ["predicthq"],
  mcp: true,
});
Create a session scoped to PredictHQ and read its MCP URL and headers
3

Connect your agent to the MCP server

typescript
import { createMCPClient } from "@ai-sdk/mcp";
import { openai } from "@ai-sdk/openai";
import { generateText, stepCountIs } from "ai";

const client = await createMCPClient({
  transport: { type: "http", url: mcp.url, headers: mcp.headers },
});

const { text } = await generateText({
  model: openai("gpt-5.6-sol"),
  tools: await client.tools(),
  prompt: "Find major events near San Francisco in the next 30 days and summarize their likely impact on local demand.",
  stopWhen: stepCountIs(10),
});

console.log(text);
await client.close();
Pass the session's MCP URL and headers to your agent and run a PredictHQ request
SETUP GUIDE

Connect PredictHQ API Tool with your Agent

1

Install Composio

typescript
npm install @composio/core @composio/openai openai
Install the Composio SDK, the OpenAI provider, and the OpenAI SDK
2

Create a Composio session

typescript
import OpenAI from "openai";
import { Composio } from "@composio/core";
import { OpenAIResponsesProvider } from "@composio/openai";

const composio = new Composio({ provider: new OpenAIResponsesProvider() });
const client = new OpenAI();

const session = await composio.create("your-user-id", { toolkits: ["predicthq"] });
const tools = await session.tools();
Initialize Composio with the OpenAI Responses provider and create a session scoped to PredictHQ
3

Run PredictHQ tools with your agent

typescript
let response = await client.responses.create({
  model: "gpt-5.6-sol",
  tools,
  input: [{ role: "user", content: "Find major events near San Francisco in the next 30 days and summarize their likely impact on local demand." }],
});

while (response.output.some((o) => o.type === "function_call")) {
  const outputs = await composio.provider.handleToolCalls(session, response.output);
  response = await client.responses.create({
    model: "gpt-5.6-sol",
    tools,
    previous_response_id: response.id,
    input: outputs,
  });
}

console.log(response.output_text);
Send a request, execute the PredictHQ tool calls through the session, and print the final answer

Why Use Composio?

AI Native PredictHQ Integration

  • Supports both PredictHQ MCP and direct API based integrations
  • Structured, LLM-friendly schemas for reliable event and demand analysis
  • Rich coverage for searching events, forecasting demand, and querying location data

Secure API Key Handling

  • Connect your own PredictHQ API key without embedding it in agent prompts or application code
  • Central place to store, scope, and revoke PredictHQ access
  • Per user and per environment credentials for safer deployments

Agent Optimized Design

  • Tools are tuned using real error and success rates to improve reliability over time
  • Comprehensive execution logs so you always know what ran, when, and on whose behalf

Enterprise Grade Security

  • Fine-grained RBAC so you control which agents and users can access PredictHQ
  • Scoped, least privilege access to PredictHQ resources
  • Full audit trail of agent actions to support review and compliance
FRAMEWORKS

Use PredictHQ with any AI Agent Framework

Choose a Framework you want to connect PredictHQ with

Rolling this out across your team?

Give your team centralized access control across every framework with Composio’s MCP Gateway.

EXPLORE MCP GATEWAY
FAQ

Frequently asked questions

Start with PredictHQ.It takes 30 seconds.

Managed auth, hosted MCP servers, and every PredictHQ tool your agent needs.Free to start.

Start building