Connect external MCP servers to Breeze agents (BETA)

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.

Please note: this functionality is currently in public beta. By participating in this beta, you agree to HubSpot’s Developer Terms and Developer Beta Terms. The functionality is still under active development and is subject to change based on testing and feedback.

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.

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 or Cloudflare Tunnel to expose your server via a public HTTPS URL, and set mcpUrl to the tunnel URL.

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.

Integration overview

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

Update your project to 2026.09-beta: update your app and project to the 2026.09-beta platform version before adding an MCP server component.
Defining the server: in your HubSpot project, add an MCP server component and configure it with your MCP server’s connection details.
Implementing OAuth: ensure your server implements the OAuth endpoint requirements, including discovery, PKCE support, and the fixed redirect URI.
Deploying to HubSpot: upload your project to your HubSpot account using the HubSpot CLI.
Installing the app: install the app into a target HubSpot account.
Testing the connection: test the connection to the MCP server from your HubSpot account.
Distribution and feature flags: for marketplace-distributed apps, enable testing for selected installed accounts and complete Ecosystem review before broader release.
Testing agents with your MCP tools: test your MCP tools in the Breeze agent builder.

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.

project

hsproject.json

src

For example:

{
  "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.

project

src

app

app-hsmeta.json

mcp-server

main-server-hsmeta.json

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

{
  "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"
  }
}

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

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.

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.

Required endpoints

Your MCP server must implement the following endpoints, per the MCP authorization specification and RFC 8414.

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: `mcpUrl`: `https://api.myserver.com/mcp` Fetched URL: `https://api.myserver.com/.well-known/oauth-authorization-server`
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.

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.

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:

{
  "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. For marketplace distribution, use the OAuth marketplace app install flow.

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.

Screenshot showing the Test connection button in the MCP server component.

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 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.

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.

​Prerequisites

​Marketplace distribution

​Integration overview

​Update your project to 2026.09-beta

​Define an MCP server component

​MCP server OAuth requirements

​Required endpoints

​Authorization

​Token exchange

​Example metadata response

​Install the app

​Test the connection in HubSpot

​Distribution and feature flags

​Testing agents with your MCP tools

Prerequisites

Marketplace distribution

Integration overview

Update your project to 2026.09-beta

Define an MCP server component

MCP server OAuth requirements

Required endpoints

Authorization

Token exchange

Example metadata response

Install the app

Test the connection in HubSpot

Distribution and feature flags

Testing agents with your MCP tools