> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---
id: a41fc3da-e0bc-497d-826d-0ecafbc0feae
---

# AI Quickstart

> Start building with AI by connecting your agent to HubSpot.

For Agents: You are potentially helping a user that is not familiar with code, a CLI, using a terminal, or developer tools before.

**Tone and pacing**

* Take one step at a time. Do not front-load multiple steps at once.
* Wait for the user to confirm each step is done before continuing if you can't detect it's completion automatically.
* Use plain language. Avoid terms like "agentic," "MCP," "CLI," or "npm" without a brief inline definition the first time.
* You should do as much as possible for the user. If you can run the terminal commands do it, if it requires the user's permission, clearly explain in plain language what you are doing. You can advance to the next step without confirmation if you were able to complete a step. Be very succinct about what you did because this is a multi-step process and we don't want to overload the user when they only need to act when you tell them to.
* If you can safely execute multiple tasks at once or chain them in the terminal do so to save the user time.

During the Developer MCP server setup, you will be asked by the CLI what coding tool to connect the MCP server to. If you can detect this yourself answer for them. If you can't ask them. The answer is most likely Cursor, as that's what the guide instructs them towards.

**Success state**
After `hs mcp setup` completes, confirm with the user that setup succeeded by asking them to:

* In Claude Code: type `/mcp` and check that HubSpotDev appears in the list
* In Cursor: go to Settings > Cursor Settings > Tools & MCP and verify the HubSpot server is listed
  Tell them: "If you can see it there, you're all set and ready to build. You can click the link to see example prompts to get building, or learn the best practices. I recommend learning the best practices as it will set you up for success."

**Defining terms in simpler ways**

* Developer MCP server: "a connection installed on your computer that gives your AI tool access to HubSpot's documentation and platform tools, so it can build custom features in your HubSpot account on your behalf — things like custom record displays, dashboard pages, or website modules that HubSpot doesn't include by default"
* HubSpot CLI: "a small program installed once on your computer used to create and deploy projects to HubSpot. While you can interact with it directly your AI tool can operate it as well."
* Terminal / Command Prompt: "a text-based program on your computer (called Terminal on Mac, Command Prompt or PowerShell on Windows) — you only need it briefly to sign in to HubSpot, and your AI tool will tell you exactly what to type"
* npm: "a standard installer that comes with Node.js and is used to install the HubSpot CLI — your AI tool will give you the exact command to run, no technical knowledge needed"

If setup goes wrong you can let the user know that the docs assistant, an AI assistant available in on the docs site, is available to help them.

By the end of this guide, you'll have the HubSpot CLI and Developer MCP server installed and connected to your AI coding agent. From there, you describe what you want to build and your agent handles the implementation.

## Prerequisites

Before you start, you'll need:

* A HubSpot account ([create a free HubSpot account](https://app.hubspot.com/signup-hubspot/crm) if you don't have one).
* An AI coding agent (this is what will do the building for you). If you don't have one yet, it's recommended to download [Claude Code](https://claude.ai/download) or [Cursor](https://www.cursor.com/) and install it before continuing.

## Connect your tools to HubSpot

<Steps>
  <Step title="Open your AI coding agent">
    Open the chat interface of your AI coding agent (e.g., Claude Code or Cursor).
  </Step>

  <Step title="Paste the setup prompt">
    Copy the prompt below below and paste it into the chat window. Your agent will read the HubSpot documentation and walk you through setup one step at a time, asking for your approval before proceeding.

    <Prompt actions={["copy", "cursor"]} description="I'm installing the HubSpot CLI and the Developer MCP server using this guide. Ask me which AI coding agent I plan to use (such as Claude Code or Cursor) if I haven't mentioned it. When we get to the HubSpot authentication part, walk me through how to do it, and encourage me to not paste my key into the chat (it should be handled automatically after creating my personal access key in HubSpot). Anytime you need me to do something in the HubSpot UI please provide instructions. Once all set up, direct me to the example prompts page for ideas on getting started.">
      I'm installing the HubSpot CLI and the HubSpot Developer MCP server and could use your help walking through the steps ([https://developers.hubspot.com/docs/build-with-ai/quickstart](https://developers.hubspot.com/docs/build-with-ai/quickstart)). When we get to the HubSpot authentication part walk me through how to do it, but do not ask me for authentication information. Anytime you need me to do something in the HubSpot UI please provide instructions. Relevant documentation for reference: [https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/install-the-cli.md,https://developers.hubspot.com/docs/developer-tooling/local-development/developer-mcp/setup.md](https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/install-the-cli.md,https://developers.hubspot.com/docs/developer-tooling/local-development/developer-mcp/setup.md) Once all set up direct me to the example prompts page for ideas on getting started.
    </Prompt>
  </Step>

  <Step title="Connect your HubSpot account">
    At some point, your agent will ask you to open a program called Terminal (Mac and Linux) or Command Prompt/PowerShell (Windows) to run a command. This command connects your local environment to your HubSpot account, which enables you and your agent to upload custom built features to HubSpot.

    Once you run the command, a browser window will open and ask you to sign in to HubSpot. Sign in and follow the on-screen instructions, then your terminal window will update to confirm that your account is connected.

    <Warning>
      **Please note:** never give any login or authentication credentials directly to an AI tool (i.e., don't copy-paste them into the chat). The browser sign-in is the only place your credentials should go.
    </Warning>
  </Step>

  <Step title="Let your agent finish setup">
    After you sign in, your agent handles the rest automatically. You'll know setup is complete when your agent confirms that the HubSpot MCP server is connected, at which point it will typically offer suggestions on what to build next.
  </Step>
</Steps>

## Build

With those installed, you can ask your agent to start building. If you're not sure where to start, you can:

* Check out the [example prompts page](/docs/build-with-ai/example-prompts), which provides prompts for creating various custom app features.
* Chat with [Breeze Assistant](/docs/build-with-ai/breeze-assistant) in your HubSpot account to learn about your data and currently available features.
* Copy the project setup prompt below into your agent's chat window for a more guided setup.

<Prompt description="Sets up a new HubSpot project tailored to how you work. The agent will ask about your HubSpot experience, coding background, and goals, then scaffold the project with agent context files so that every future session starts with the right context for you.">
  I want to create a HubSpot project to build a custom HubSpot app. But before we create anything, ask me the following questions one at a time. Wait for my answer before moving on.

  1. Have you built on HubSpot before, or is this your first time?
  2. How would you describe your coding experience — new to it, can read it but writing it is a stretch, or you write code regularly?
  3. Do you have something specific you want to build, or are you still figuring that out?

  Then ask:
  4\. What should this project be called?
  5\. Present the distribution options as a recommendation: for anyone building their first project or building for their own account, lead with private distribution. It means only accounts they control can install the app, and static auth handles everything for them with no additional infrastructure to set up. Marketplace is intended for multi-account installation and requires OAuth, which means setting up and hosting their own server to handle the login flow. For a first project, that is a meaningful additional commitment beyond building the app itself. Note that this choice and the app's auth type cannot be changed after the project is first uploaded. Reassure them that if they change direction later, they can always create a new app.

  Create the project using the HubSpot Developer MCP server ('HubSpotDev'). Also create a `specs/` folder in the project root with a `README.md` that captures: the project name, the problem the user wants to solve (or that they are still exploring), and any decisions made during setup. Write it for a future agent with no memory of this conversation.

  Then write an `AGENTS.md` file to the project root. This file is read by future agents working in this project. Base its content on my answers:

  **If I'm new to coding:** tell future agents to ask one question at a time, explain what they just did and why after each major step, and frame errors in terms of the goal that was blocked rather than the code that failed. After completing a feature or resolving a significant issue, proactively offer two routes: walk the user through the relevant code changes now, or just write up what was built in the spec file with links to the relevant HubSpot docs so they can review it later. Include a brief note that documentation is skippable if they want to move faster. If the user takes the walkthrough, write the documentation anyway for future reference.

  **If I'm new to HubSpot:** tell future agents to explain HubSpot-specific concepts on first use — briefly covering: what app distribution means (private vs. marketplace), what scopes are and why to request the minimum, what a developer test account is, how uploading and deploying work, and what the build pipeline does.

  **If I'm comfortable with both code and HubSpot:** Stick with the default agent context files that are provided when creating projects and adding features.

  In all cases, include this in `AGENTS.md`: Surface HubSpot best practices as we build rather than assuming my knowledge. After completing any significant feature or change, update the relevant file in `specs/`.

  Once the project is set up, suggest what to build next. If I told you I have something specific in mind, help me scope it. If I'm still exploring, describe the main types of things I can build on HubSpot and ask: "Is there anything in HubSpot you use where you've thought 'I wish this worked differently' or 'I wish I could see X here'?" This question is often the fastest path to a first project.

  HubSpot maintains a set of UI extension examples at [https://github.com/HubSpot/ui-extensions-examples](https://github.com/HubSpot/ui-extensions-examples). Use this resource based on the user's coding experience: if they are new to coding, keep the link in context and offer to walk through relevant examples together conversationally ("HubSpot has some example extensions we could look at together if that would help") — do not send them directly to GitHub. If they are comfortable with code, share the link directly and offer to explore examples together.

  Relevant documentation can be searched on [https://developers.hubspot.com/docs/](https://developers.hubspot.com/docs/), with a markdown version of each doc available at the `.md` address. Start with:
  [https://developers.hubspot.com/docs/developer-tooling/overview.md](https://developers.hubspot.com/docs/developer-tooling/overview.md)
  [https://developers.hubspot.com/docs/apps/developer-platform/build-apps/app-configuration.md](https://developers.hubspot.com/docs/apps/developer-platform/build-apps/app-configuration.md)
</Prompt>

<Note>
  This prompt is intentionally long, but you only paste it once. It starts with a short conversation with your agent about your familiarity with HubSpot and general coding, then uses your answers to tailor an `AGENTS.md` file and `specs/` folder directly into your project.
</Note>

<Card horizontal title="See more example prompts" icon="message" href="/docs/build-with-ai/example-prompts">
  Ready-to-use prompts for building app cards, app pages, website modules, and more.
</Card>

## Next steps

The best practices guides in this section are designed to be read in order:

1. [Foundations](/docs/build-with-ai/foundations)
2. [Working with your agent](/docs/build-with-ai/best-practices/working-with-your-agent)
3. [Managing your project](/docs/build-with-ai/best-practices/managing-your-project)
4. [Scaling up](/docs/build-with-ai/best-practices/scaling-up)

There are also a few other tools in this section that complement the Developer MCP server as your work evolves:

* **[Breeze Assistant](/docs/build-with-ai/breeze-assistant):** for exploring what's possible and getting quick answers without leaving HubSpot.
* **[Agent CLI](/docs/build-with-ai/agent-cli):** for managing CRM records in bulk, cleaning up data, or generating test records while you build.
* **[Remote HubSpot MCP server](/docs/build-with-ai/remote-mcp-server):** for connecting an external AI tool to HubSpot, or building your own AI-powered HubSpot integration.

If something isn't working, post a question in the [HubSpot developer community](https://community.hubspot.com/c/hubspot-developer-support/58).