> ## 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: a16b2f5c-a9ae-4611-b6b8-b4eb0bae9c35
---

# Connect external MCP servers to Breeze agents (BETA)

> Add an MCP server component to your app to connect external MCP servers to Breeze agents.

export const Parameter = ({name, type, required, className, children}) => {
  return <>
      <dt className={`parameter-element element-title${className ? ` ${className}` : ''}`}>
        <div className="parameter-header">
          <code className="parameter-name">{name}</code>
          {type && <span className="parameter-type code-style">{type}</span>}
          {required && <span className="required-indicator">required</span>}
        </div>
      </dt>
      {children && <dd className="parameter-element parameter-description">
          {children}
        </dd>}
    </>;
};

export const ParameterList = ({className, children}) => {
  return <dl className={`parameter-list${className ? ` ${className}` : ''}`}>
      {children}
    </dl>;
};

By adding a Model Context Protocol (MCP) server component to your app, you can connect external MCP servers to Breeze agents. Once defined and installed in a customer account, these servers become available as agent tools within Breeze Agent Studio, allowing Breeze agents to interface with external data and functionality provided by your MCP server.

<Warning>
  **Please note:** this functionality is currently in public beta. By participating in this beta, you agree to HubSpot's [Developer Terms](https://legal.hubspot.com/hs-developer-terms) and [Developer Beta Terms](https://legal.hubspot.com/hubspot-beta-terms). The functionality is still under active development and is subject to change based on testing and feedback.
</Warning>

## Prerequisites

To get started with MCP server components, you'll need:

* A HubSpot account with access to the MCP server public beta.
* The HubSpot CLI installed and authenticated with your HubSpot account.
* A HubSpot app that's configured for private or marketplace distribution.
  * The project's `hsproject.json` file must be configured to use the latest beta platform version (`2026.09-beta` or newer).
  * The app's scopes must include `oauth` at a minimum, even if your MCP server does not read HubSpot data.
* A functioning MCP server that's deployed and accessible via a public URL. Note that HubSpot's authorization flow does not support Dynamic Client Registration (DCR). You will need to generate a valid client ID for customers to connect to your MCP server, and this is a required field in the component schema.

<Warning>
  **Please note:** your MCP server must be reachable from the public internet, not just your local machine. During the connection flow, HubSpot's backend performs OAuth metadata discovery and token exchange server-side. URLs pointing to `localhost` or private networks will fail with a generic "Authentication failed" error, even if the server is running locally.

  For local development, use a tunneling service such as [ngrok](https://ngrok.com/) or [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/do-more-with-tunnels/local-management/create-local-tunnel/) to expose your server via a public HTTPS URL, and set `mcpUrl` to the tunnel URL.
</Warning>

## Marketplace distribution

Marketplace-distributed apps with MCP server components must complete Ecosystem review and approval before installed customers can access the server. You can use feature flags to test the component with up to five installed accounts before approval. Learn more about [distribution and feature flags](#distribution-and-feature-flags).

## Integration overview

At a high level, integrating with MCP server components involves:

1. **[Update your project to 2026.09-beta](#update-your-project-to-202609-beta):** update your app and project to the `2026.09-beta` platform version before adding an MCP server component.
2. **[Defining the server](#define-an-mcp-server-component):** in your HubSpot project, add an MCP server component and configure it with your MCP server's connection details.
3. **[Implementing OAuth](#mcp-server-oauth-requirements):** ensure your server implements the OAuth endpoint requirements, including discovery, PKCE support, and the fixed redirect URI.
4. **Deploying to HubSpot:** upload your project to your HubSpot account using the HubSpot CLI.
5. **[Installing the app](#install-the-app):** install the app into a target HubSpot account.
6. **[Testing the connection](#test-the-connection-in-hubspot):** test the connection to the MCP server from your HubSpot account.
7. **[Distribution and feature flags](#distribution-and-feature-flags):** for marketplace-distributed apps, enable testing for selected installed accounts and complete Ecosystem review before broader release.
8. **[Testing agents with your MCP tools](#testing-agents-with-your-mcp-tools):** test your MCP tools in the Breeze agent builder.

<span id="update-your-project-to-202609-beta" />

## Update your project to 2026.09-beta

Before adding an MCP server component, update your project's `platformVersion` to `2026.09-beta`. This setting is defined in the `hsproject.json` file in the project directory. The `hsproject.json` file is located at the project root.

<Card>
  <Tree.Folder name="project" defaultOpen>
    <Tree.File name="hsproject.json" />

    <Tree.Folder name="src" defaultOpen />
  </Tree.Folder>
</Card>

For example:

```json theme={null}
{
  "name": "mcp-server-project",
  "platformVersion": "2026.09-beta",
  "srcDir": "src"
}
```

## Define an MCP server component

To define an MCP server component, you must create a `*-hsmeta.json` file within the `mcp-server` directory within `app/`. This file will contain your MCP server configuration options.

<Card>
  <Tree.Folder name="project" defaultOpen>
    <Tree.Folder name="src" defaultOpen>
      <Tree.Folder name="app" defaultOpen>
        <Tree.File name="app-hsmeta.json" />

        <Tree.Folder name="mcp-server" defaultOpen>
          <Tree.File name="main-server-hsmeta.json" />
        </Tree.Folder>
      </Tree.Folder>
    </Tree.Folder>
  </Tree.Folder>
</Card>

Below are the configuration options available for MCP server type schemas (`*-hsmeta.json`).

```json theme={null}
{
  "uid": "my-mcp-server",
  "type": "mcp-server",
  "config": {
    "name": "My MCP Server",
    "description": "Provides context and tools for specific external data.",
    "mcpUrl": "https://api.myserver.com/mcp",
    "mcpClientId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "version": "1.0.0",
    "requiredScopes": ["data:read", "data:write"],
    "logoUrl": "https://image.com/image",
    "enabled": true,
    "websiteUrl": "https://www.mysite.com",
    "privacyPolicyUrl": "https://www.mysite.com/privacy"
  }
}
```

<ParameterList>
  <Parameter name="uid" type="string" required={true}>
    A unique identifier for this component within your project.
  </Parameter>

  <Parameter name="type" type="string" required={true}>
    The type of component. Must be set to `mcp-server`.
  </Parameter>

  <Parameter name="name" type="string" required={true}>
    The human-readable name of the server, which will appear in the agent tool selector.
  </Parameter>

  <Parameter name="description" type="string" required={true}>
    A brief description of the server's capabilities, used by customers to understand when to use your MCP server.
  </Parameter>

  <Parameter name="mcpUrl" type="string" required={true}>
    The full HTTPS URL to your MCP server's endpoint. This URL must be publicly accessible from HubSpot's servers. See the [reachability warning above](#prerequisites) for details.
  </Parameter>

  <Parameter name="mcpClientId" type="string" required={true}>
    The client ID registered to your MCP OAuth server to be used with the HubSpot app this component belongs to. This ID will be used to identify all requests being made by agents to your MCP server. For more control and visibility into underlying customer requests, you can use multiple apps and client IDs to monitor this traffic in more detail.
  </Parameter>

  <Parameter name="version" type="string" required={true}>
    The version of the MCP server definition. Default is `1.0.0`.
  </Parameter>

  <Parameter name="requiredScopes" type="array">
    A list of OAuth scopes defined by your MCP server's authorization system, which correspond to a permission boundary enforced by your MCP server (e.g., `["data:read", "data:write"]`). These are not HubSpot scopes, but rather the scopes advertised in your server's [OAuth authorization server metadata](#mcp-server-oauth-requirements). These scopes will be presented during the connection flow and determine which tools and data are accessible to authenticated clients. Set to an empty array (`[]`) to connect without requesting specific scopes, which allows access to all tools the server exposes.
  </Parameter>

  <Parameter name="logoUrl" type="string">
    URL to a public image file for the server logo, which will be displayed in the agent tool selector.
  </Parameter>

  <Parameter name="enabled" type="boolean">
    Whether the MCP server is enabled. Default is `true`.
  </Parameter>

  <Parameter name="websiteUrl" type="string">
    URL of your server's website or external documentation.
  </Parameter>

  <Parameter name="privacyPolicyUrl" type="string">
    URL of your server's privacy policy.
  </Parameter>
</ParameterList>

Once you've defined your MCP server component, upload your project to HubSpot using the `hs project upload` command.

<Tip>
  If you receive an error of `unsupported type: mcp-server`, ensure the `platformVersion` in your project's `hsproject.json` file is configured to `2026.09-beta` or newer.
</Tip>

## MCP server OAuth requirements

HubSpot connects to your MCP server using an OAuth 2.1 authorization code flow with PKCE. HubSpot's backend initiates and coordinates this flow: it fetches OAuth metadata and exchanges the authorization code for tokens server-side. However, the authorization step where the user grants access happens through their browser, which is redirected to your MCP server's authorization endpoint.

```mermaid actions={false} theme={null}
sequenceDiagram
    participant B as User's Browser
    participant H as HubSpot Backend
    participant M as Your MCP Server

    B->>H: User clicks "Connect and add"
    H->>M: GET /.well-known/oauth-authorization-server
    M->>H: Authorization Server Metadata (JSON)
    H->>B: Redirect to MCP server's authorization endpoint
    Note over H: Includes client_id, code_challenge (S256),<br/>redirect_uri, and state parameters
    B->>M: GET /authorize?response_type=code&client_id=...&code_challenge=...
    Note over M: User authorizes the connection
    M->>B: Redirect to HubSpot callback with auth code
    B->>H: Authorization code delivered
    H->>M: POST /token (code + code_verifier)
    M->>H: Access token (+ refresh token)
    Note over H: Connection established
```

### Required endpoints

Your MCP server must implement the following endpoints, per the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) and [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414).

| Endpoint                                  | Description                                                                                                                                                                                                                                                                                                                         |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/.well-known/oauth-authorization-server` | Returns OAuth 2.0 authorization server metadata, including `authorization_endpoint` and `token_endpoint`. HubSpot fetches this from the domain root of your `mcpUrl`. For example:<ul><li>`mcpUrl`: `https://api.myserver.com/mcp`</li><li>Fetched URL: `https://api.myserver.com/.well-known/oauth-authorization-server`</li></ul> |
| Authorization endpoint                    | Accepts `response_type=code` requests with PKCE parameters (`code_challenge` and `code_challenge_method=S256`). Must redirect the user back to HubSpot's fixed callback URL with an authorization code.                                                                                                                             |
| Token endpoint                            | Exchanges authorization codes for access tokens. Must validate the PKCE `code_verifier` against the original `code_challenge`.                                                                                                                                                                                                      |

### Authorization

HubSpot redirects to your server's authorization endpoint using PKCE with the S256 challenge method. Your authorization endpoint must support the following:

* **Client ID:** HubSpot passes the `mcpClientId` from your component schema as the `client_id` parameter throughout the flow. Your server must recognize this value.
* **PKCE (S256):** HubSpot includes `code_challenge` and `code_challenge_method=S256` parameters in the authorization request.
* **Fixed redirect URI:** HubSpot always uses `https://oauth-redirect.hubspot.com/callback/mcp_server` as the redirect URI. Your OAuth server must be configured to accept this URI.
* **Scopes:** if your configuration includes `requiredScopes`, these scopes will be associated with the connection. Your authorization endpoint should grant the requested scopes and your token endpoint should include them in the access token response.

<Warning>
  **Please note:** the redirect URI `https://oauth-redirect.hubspot.com/callback/mcp_server` is fixed and cannot be customized. You must register this URI in your MCP server's OAuth configuration, or the authorization flow will fail.
</Warning>

### Token exchange

After the user authorizes, HubSpot's backend exchanges the authorization code for an access token by sending a `POST` request to your token endpoint. This request includes the PKCE `code_verifier` for validation. Because this exchange happens server-side, your token endpoint must be publicly reachable.

### Example metadata response

Below is an example of the JSON your `/.well-known/oauth-authorization-server` endpoint should return:

```json theme={null}
{
  "issuer": "https://api.myserver.com",
  "authorization_endpoint": "https://api.myserver.com/authorize",
  "token_endpoint": "https://api.myserver.com/token",
  "scopes_supported": ["data:read", "data:write"],
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"]
}
```

## Install the app

With your project deployed, you can install the app into a target HubSpot account. To do this, you'll navigate into HubSpot to get the install URL, along with the app's client ID and secret for your OAuth server. For private distribution, use the [privately distributed OAuth app install flow](/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot#install-a-privately-distributed-oauth-app). For marketplace distribution, use the [OAuth marketplace app install flow](/docs/apps/developer-platform/build-apps/manage-apps-in-hubspot#install-an-oauth-marketplace-app).

* To open the project in HubSpot from the terminal, run `hs project open` from within the project directory.
* From the project page, navigate to the **App** in the left sidebar.
* Click the **Distribution** tab.
* Click **Copy install link**, then paste it into your browser to install the app into the desired target account.
* To get your app's client ID and secret for your OAuth server, click the **Auth** tab, then copy the *Client ID* and *Client secret* values.

## Test the connection in HubSpot

Once the app is installed, test the connection to the MCP server from your HubSpot account:

* In the account where you uploaded the project, navigate to **Development** > **Projects**, then click the **name** of the project where the app is installed.
* In the left sidebar, navigate to the **MCP server component**.
* Click **Test connection**.

<Frame>
  <img src="https://developers.hubspot.com/hubfs/Knowledge_Base_2023-24-25/developer-projects/mcp-registry-test-connection.png" alt="Screenshot showing the Test connection button in the MCP server component." />
</Frame>

* In the dialog box, click **Connect**.
* A pop-out window will appear as the OAuth handshake is attempted using the details defined in your MCP server component's `*-hsmeta.json` file. If successful, you'll see a message indicating the server is reachable and responding as expected.

## Distribution and feature flags

MCP server components are available in public beta for privately distributed apps and marketplace-distributed apps. For apps that are or will be distributed through the HubSpot Marketplace, HubSpot automatically creates the `hs-release-mcp-server` feature flag in an `OFF` state when you add the `mcp-server` component. This keeps the server hidden from installed customers until your app completes Ecosystem review and approval.

While you develop and prepare for review, use the [feature flags API](/docs/api-reference/latest/app-management/feature-flags/guide) to set the `hs-release-mcp-server` flag to `ON` for up to five installed accounts for testing. After approval, you can set the app-level `defaultState` to `ON` for broader customer access.

The following limits apply to marketplace-distributed apps with MCP server components:

* Portal-level flag writes require the app to be installed in the target account.
* Apps that haven't completed Ecosystem approval can set `ON` portal overrides for up to five installed accounts.
* After Ecosystem approval, you can set the app-level `defaultState` to `ON` for broader release.

MCP server marketplace distribution follows the same Ecosystem review and approval path as App Cards. Learn more about [submitting App Cards to the HubSpot Marketplace](https://developers.hubspot.com/docs/apps/developer-platform/add-features/ui-extensions/extension-points/app-cards/create-an-app-card#submitting-app-cards-to-the-hubspot-marketplace).

## Testing agents with your MCP tools

To test your MCP tools in the agent builder:

* In the account where your app is installed, navigate to **Agent Hub** > **Agent Builder**.
* Click the **name** of an existing agent, or create a new one. It's recommended to start by testing with the Developer Tool Testing Agent.
* In the agent builder, click **Configure**.
* Click **Add tool**.
* In the left sidebar, locate the *MCP Servers* category tab, and locate your MCP server. Then, click **Connect and add** to add it to the agent.