MCP server
Connect AI agents to verified real-world event context on demand. On-demand grounding for LLMs via the Model Context Protocol - no data pipeline to maintain.
The PredictHQ MCP server connects AI assistants and agent-based systems directly to PredictHQ's APIs using the Model Context Protocol (MCP) - an open standard for giving AI systems access to external tools and data at inference time.
This is the on-demand grounding path of Grounding with PredictHQ: your agents retrieve verified real-world context at the moment they answer, and hold no copy of anything. Once connected, your AI assistant can search events, retrieve demand intelligence, and access PredictHQ's full API surface through natural language.
MCP is the grounding path, not the bulk path. For training-scale feature retrieval, use the Features API. To retrieve from a verified event store inside your own environment instead, see provisioned grounding.
How it works
Your agent decides per question whether it needs real-world context, writes its own query, and answers from what comes back:
Server details
MCP Server URL
https://mcp.predicthq.com/v1/mcp
Transport
Streamable HTTP
Authentication
OAuth or Bearer token (API key)
Authentication
The MCP server supports two authentication methods.
OAuth - when you connect using a supported client, the client redirects you to PredictHQ to authorize access. The client stores no credentials in its configuration. Best suited for interactive use and multi-user environments.
Bearer token - pass your PredictHQ API key in the Authorization: Bearer $API_TOKEN header. Well-suited for agent and automation workflows where interactive login is not practical, or for clients that do not support OAuth. You can create an API key in the PredictHQ WebApp.
Available tools
The MCP server exposes tools across the full PredictHQ API surface:
Events - search and count events
Broadcasts - search and count live TV broadcasts
Features - retrieve aggregated ML-ready demand intelligence features
Saved Locations - create and manage locations, retrieve insight events, opening hours, and closures
Beam - create and manage Analyses and Analysis Groups, upload demand data, and retrieve Feature Importance and correlation results
Forecasts - create and manage forecast models, upload demand data, train models, and retrieve forecasts with explainability
Predicted Impact Area - get Predicted Impact Area by location and industry
Places & Geocoding - search places, look up place hierarchies, and geocode addresses
Tech Docs - search PredictHQ's technical documentation and retrieve individual pages, covering API references, integration guides, tutorials, and conceptual content
Access & subscription
Access to the MCP server is subject to your PredictHQ subscription. The MCP also enforces the same data access controls as the REST API - if your plan covers a specific set of locations or event categories, those same limits apply when using MCP.
If you don't yet have access to the MCP server, contact your PredictHQ account manager.
Connect your AI client
Claude (claude.ai)
PredictHQ's MCP is listed in the Claude Connectors Directory. To set it up:
Open the PredictHQ connector listing link and select Connect.
To authenticate with your PredictHQ account, follow the OAuth flow.
Once connected, PredictHQ tools are available in any Claude conversation.
For more information, see Claude's connector directory documentation.
Claude Code
Claude Code supports MCP via the CLI.
To connect Claude Code to the PredictHQ MCP server:
Run the following command:
Inside a Claude Code session, run
/mcpand follow the OAuth flow.
To use a Bearer token instead:
For full instructions, see Claude Code MCP documentation.
ChatGPT
ChatGPT supports remote MCP servers via Connectors. There are two ways to set this up depending on your plan.
Individual setup
To set up the connector:
Under Settings > Advanced Settings, enable Developer Mode.
Under Settings > Connectors, click Create.
Workspace-wide setup
If you're a workspace admin:
In Workspace Settings > Permissions & Roles > Connected Data, enable Developer Mode.
In Workspace Settings > Connectors, create a connector.
Publish the connector for the whole organization. Once published, the connector is available to all users in the workspace without any individual setup.
Adding the PredictHQ connector:
In Settings or Workspace Settings, depending on your plan, go to Connectors > Create.
Enter a name (e.g.
PredictHQ) and optionally a description.Enter the MCP Server URL:
https://mcp.predicthq.com/v1/mcpSelect your authentication method:
OAuth - to authenticate with your PredictHQ account, follow the login flow.
Access token / API key - select Bearer as the scheme and enter your PredictHQ API key.
To use it in a conversation:
In the chat field:
Click +.
Click More.
Select PredictHQ.
Note: The exact steps may vary depending on your plan and workspace configuration. If the earlier steps don't match what you see, refer to OpenAI's connector documentation for the latest instructions.
Other clients
The PredictHQ MCP server works with any MCP-compatible client that supports Streamable HTTP transport, including Cursor, Windsurf, VS Code (GitHub Copilot), Zed, Postman, and others.
Use the following details when configuring your client:
Server URL:
https://mcp.predicthq.com/v1/mcpTransport: Streamable HTTP
Authentication: OAuth, or Bearer token via
Authorization: Bearer $API_TOKENheader
Refer to your client's documentation for specific configuration steps.
Next steps
Continue with these pages:
Grounding with PredictHQ - what grounding is and how PredictHQ fits into AI and agent workflows
PredictHQ MCP in agentic workflows - use the MCP in autonomous and multi-agent workflows, where agents call PredictHQ for real-world context and explainability at decision time
API quickstart - create an API key for Bearer token authentication
Last updated
Was this helpful?