> For the complete documentation index, see [llms.txt](https://docs.hockeystack.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hockeystack.com/marketing-intelligence/mcp.md). # MCP Bring your HockeyStack workspace into Claude, ChatGPT, and other AI tools via MCP — read dashboards, reports, and people, and create or update reports all scoped to what you can see in HockeyStack. **Server URL:** **Auth:** OAuth 2.0. Actions are performed on behalf of the authenticated user; access is scoped to the same data as in the HockeyStack dashboard. **Transport:** Streamable HTTP (stateless; no server-side sessions). ### How To Connect #### Claude 1. You must be a workspace Admin in the AI Tool you are using to add a connector. 2. Go to **Settings → Customize → Connectors**. 3. Click the **+** to add a custom connector. 4. Paste the URL: [`https://mcp.hockeystack.com/mcp`](https://mcp.hockeystack.com/mcp) 5. Once the Connector has been created you can do either of the following: 1. Press Connect on the newly created connector
2. Open a new prompt and ask to connect to the HockeyStack MCP 6. A browser tab will open — sign in with your HockeyStack account to complete authentication. #### ChatGPT / Codex 1. You must be a workspace Admin in the AI Tool you are using to add a connector. 2. Go to **Settings → Customize → Connectors**. 3. Click the **+** to add a custom connector. 4. Change the connection type from STDIO -> Streamable HTTP 5. Paste the URL: [`https://mcp.hockeystack.com/mcp`](https://mcp.hockeystack.com/mcp) 6. Once the Connector has been created you can do either of the following: 1. Press Connect on the newly created connector
2. Open a new prompt and ask to connect to the HockeyStack MCP 7. A browser tab will open — sign in with your HockeyStack account to complete authentication. Once connected, we recommend asking the assistant to list its available tools and confirm everything is accessible before running real queries.\ \ Note - You can only connect one HockeyStack instance via MCP at a time. ### What you can do with MCP today All tools below are available to users with MCP access enabled on their HockeyStack workspace. Access follows the same scoping as the HockeyStack dashboard — the MCP cannot return data that the authenticated user cannot already see, or perform writes that the authenticated user cannot already write in the UI. Rate limits apply per tool, elaborated below. **Workspace** | Tool | Description | Type | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | `check_connection` | Confirm that OAuth authentication and the MCP connection are working. | Read | | `get_workspace_settings` | Read reporting settings: timezone, currency, fiscal-year start month, default date range and default attribution options. | Read | | `update_workspace_settings` | Update reporting settings (timezone, currency, fiscal-year start, default date range, default attribution). Does not touch billing, users, roles, API keys or SSO. | Write | **Dashboards** | Tool | Description | Type | | -------------------------- | ---------------------------------------------------------------------------------------------------- | ----- | | `search_dashboards` | Search dashboards by name to find ordered groups of reports | Read | | `get_dashboard_definition` | Fetch a dashboard’s full definition including its list of reports as well as their configuration | Read | | `create_dashboard` | Create a new dashboard, optionally with reports, saved filters and a folder. | Write | | `add_reports_to_dashboard` | Add one or more existing reports to a dashboard | Write | | `delete_dashboard` | Delete a dashboard (the reports on it are kept). Needs confirmation and can be restored for 30 days. | Write | | `list_dashboard_folders` | List the dashboard folder tree and the dashboards in each folder. | Read | | `create_dashboard_folder` | Create a dashboard folder, optionally inside another folder. | Write | | `move_dashboard_to_folder` | Move a dashboard into a folder, or back to the root. | Write | | `delete_dashboard_folder` | Delete a dashboard folder. The dashboards inside move to the root. Never deletes dashboards. | Write | **Reports** | Tool | Description | Type | | ----------------------- | ----------------------------------------------------------------------------------------------------------- | ----- | | `search_reports` | Search saved reports by name or metadata | Read | | `get_report_definition` | Fetch a saved report’s full definition by ID | Read | | `preview_report` | Preview a report definition and return results without saving | Read | | `create_report` | Save a new report to the workspace | Write | | `update_report` | Update definitions to an existing report by ID | Write | | `delete_report` | Delete a report and take it off any dashboards it's on. Needs confirmation and can be restored for 30 days. | Write | | `list_report_folders` | List the report folder tree and the reports in each folder. | Read | | `create_report_folder` | Create a report folder, optionally inside another folder. | Write | | `move_report_to_folder` | Move a report into a folder, or back to the root. | Write | | `delete_report_folder` | Delete a report folder. The reports inside move up to the parent folder. Never deletes reports. | Write | **Deals** | Tool | Description | Type | | ------------------ | ------------------------------------------------------------------------------ | ---- | | `search_deals` | Search deals by name, stage, owner, account, or custom fields | Read | | `get_deal_details` | Fetch a single deal’s full details, including associated contacts and activity | Read | **Goals & Funnels** | Tool | Description | Type | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----- | | `list_goals` | List all configured goals in the workspace | Read | | `get_goal_definition` | Fetch a single goal’s full definition, including filters | Read | | `create_goal` | Create a new goal in the workspace. | Write | | `update_goal` | Update an existing goal’s definition by ID. | Write | | `validate_goal` | Validate a proposed goal definition before creating or updating. | Read | | `delete_goal` | Delete a goal definition. The underlying events are kept. Blocked if reports, funnels, views or scores still use the goal. | Write | | `list_funnel_stages` | List the source-of-truth funnel goal and its configured stages | Read | | `get_funnel_definition` | Fetch the full definition of the source-of-truth funnel. | Read | | `create_funnel_stage` | Add a new stage to the funnel. | Write | | `update_funnel_stage` | Update an existing funnel stage’s definition. | Write | | `validate_funnel_stage` | Validate a proposed funnel stage definition before creating or updating. | Read | | `delete_funnel_stage` | Remove a stage from the funnel. The stage's goal and its historical events are kept. | Write | **Properties** | Tool | Description | Type | | --------------------------- | ------------------------------------------------------------------------------------------- | ----- | | `list_properties` | List available properties (fields) in the workspace | Read | | `get_property_definition` | Fetch a single property’s definition, type, and configured breakdowns | Read | | `create_defined_property` | Create a new defined property in the workspace. | Write | | `update_defined_property` | Update an existing defined property’s definition. | Write | | `validate_defined_property` | Validate a proposed defined property before creating or updating. | Read | | `delete_defined_property` | Delete a defined property (mapped, bucket or drilldown). Blocked if anything still uses it. | Write | | `create_breakdown` | Create a new breakdown on a property. | Write | | `update_breakdown` | Update an existing breakdown’s configuration. | Write | | `validate_breakdown` | Validate a proposed breakdown before creating or updating. | Read | | `delete_breakdown` | Delete a standalone breakdown. Blocked if it's processing or something still depends on it. | Write | **Touchpoints** | Tool | Description | Type | | ----------------------------- | --------------------------------------------------------------------------------------------------------- | ----- | | `get_touchpoint_hierarchy` | Fetch the source-of-truth touchpoint hierarchy and its implied ancestors | Read | | `get_touchpoint_definition` | List or fetch individual touchpoint type and channel definitions, including their available data sources. | Read | | `create_touchpoint` | Create a new touchpoint in the workspace. | Write | | `update_touchpoint` | Update an existing touchpoint’s definition. | Write | | `update_touchpoint_hierarchy` | Update the source-of-truth touchpoint hierarchy. | Write | | `validate_touchpoint` | Validate a proposed touchpoint definition before creating or updating. | Read | | `delete_touchpoint` | Delete a touchpoint type or channel rule. Blocked if it's in use, or if it's the last one left. | Write | **Companies** | Tool | Description | Type | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ----- | | `search_companies` | Search workspace companies by name, domain, or filters. | Read | | `get_company` | Fetch full details for a single company by ID. | Read | | `get_company_score_history` | Fetch a company's score history and the latest stored reasoning behind its score. | Read | | `list_company_signals` | Fetch the latest AI-property outputs shown in a company's Signals tab. | Read | | `list_company_views` | List saved company views (segments) configured in the workspace. | Read | | `get_company_view` | Fetch the definition of a single company view. | Read | | `create_company_view` | Save a new company view from a set of filters. | Write | | `update_company_view` | Update a company view's name, filters or columns. | Write | | `delete_company_view` | Delete a saved company view (companies and people are not affected). Blocked if workflows, exports or scoring use the view. | Write | **People** | Tool | Description | Type | | ----------------------- | -------------------------------------------------------------------------------------------------------------------------- | ----- | | `search_people` | Search workspace people by name, email, or filters. | Read | | `get_person` | Fetch full details for a single person by ID. | Read | | `get_people_by_company` | List the people associated with a given company. | Read | | `resolve_contact` | Resolve a contact identifier (email or ID) to the matching workspace person. | Read | | `list_people_views` | List saved people views (segments) configured in the workspace. | Read | | `get_people_view` | Fetch the definition of a single people view. | Read | | `create_people_view` | Save a new people view from a set of filters. | Write | | `update_people_view` | Update a people view's name, filters or columns. | Write | | `delete_people_view` | Delete a saved people view (people and companies are not affected). Blocked if workflows, exports or scoring use the view. | Write | **Scoring** | Tool | Description | Type | | ------------------------------ | ------------------------------------------------------------------------------------------------------------ | ----- | | `get_scoring_configuration` | Read the workspace's scoring, summary and system-prompt configuration and its compilation status. | Read | | `update_scoring_configuration` | Edit the workspace's scoring, summary or system-prompt configuration. Does not trigger an immediate rescore. | Write | **Workflows** | Tool | Description | Type | | ---------------------- | ------------------------------------------------------------------------------------------------------------------ | ----- | | `list_workflows` | Search workflows by name, with enabled state and last-run status. | Read | | `get_workflow` | Fetch a workflow's nodes, edges, trigger, schedule and enabled state. Credentials are redacted. | Read | | `validate_workflow` | Validate a workflow before saving, without running it. | Read | | `create_workflow` | Create a new workflow. New workflows are always created disabled. | Write | | `update_workflow` | Edit a disabled workflow's name, nodes or edges. | Write | | `test_workflow` | Dry-run a disabled workflow on a single record. Webhooks are never delivered. | Write | | `get_workflow_run` | Check the status of a workflow run, node by node. | Read | | `set_workflow_enabled` | Turn a workflow on or off. Turning one on needs confirmation because it can run real integrations and use credits. | Write | | `delete_workflow` | Delete a disabled workflow. Its run history is kept, and it can be restored for 30 days. | Write | **Integrations & Data Syncs** | Tool | Description | Type | | ------------------- | ---------------------------------------------------------------------------------------------- | ----- | | `list_integrations` | List connected integrations and their connection and sync status. No credentials are returned. | Read | | `get_integration` | Fetch one integration's connection, expiry and sync status. | Read | | `list_data_syncs` | List active data-sync connections. | Read | | `get_data_sync` | Fetch one data sync's status, schedule and column mappings. | Read | | `update_data_sync` | Edit an import's column mappings, update method or row filters. Changes apply on the next run. | Write | **Product Journeys & Calls** | Tool | Description | Type | | ---------------- | ------------------------------------------------------ | ---- | | `get_journey` | Fetch a company’s configured product-journey timeline. | Read | | `get_gong_calls` | Fetch Gong call summaries | Read | **Version History & Recovery** | Tool | Description | Type | | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----- | | `list_resource_versions` | List the version history of a report, goal or defined property. | Read | | `get_resource_version` | View a past version of a report, goal or defined property. | Read | | `revert_resource_version` | Revert a report, goal or defined property to an earlier version. Needs confirmation. | Write | | `restore_deleted` | Restore an item deleted through the MCP within the last 30 days: workflows, dashboards, reports, views, folders, goals, breakdowns, properties, touchpoints and funnel stages. | Write | **Utilities** | Tool | Description | Type | | ------------ | ------------------------------------- | ---- | | `web_search` | Run a web search from within the MCP. | Read | ### Rate limits Rate limits are applied per tool and per organization to keep the MCP server healthy under bursty AI traffic. In addition, no more than 5 tool calls should be issued concurrently per authenticated credential — larger batches must be run sequentially. Clients receive a standard 429 response when limits are hit. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.hockeystack.com/marketing-intelligence/mcp.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.