Implementing MCP Remote Server for CRM Agent Integration

hubspot · Tech · 2025 · source Agentic: yes · promotional bias: med · source-backed · extracted with prompt 0.5.6 (schema v2)

Generated from extraction.json — do not edit by hand. Every claim cites verbatim source evidence; stated means the quote directly asserts the claim, implied means it supports it indirectly.

Problem

Domain: Remote MCP server for CRM agent integration

HubSpot needed a secure, low-friction way for AI agents such as ChatGPT to query CRM data across contacts, companies, and deals for non-technical users, while working within HubSpot's Java/RPC/microservices stack, honoring OAuth scopes and seat permissions, and navigating an emerging MCP ecosystem with incomplete auth and transport standards.

Constraints:

• 75% of HubSpot customers already used ChatGPT
• the connector targeted ChatGPT's 500 million weekly users, many of whom are not developers
• off-the-shelf MCP products did not satisfy speed, enterprise RPC, auth, and customization needs
• the Java MCP SDK needed streamable HTTP support for HubSpot's remote server use case
• the MCP specification was still evolving and missing complete auth and agent-to-agent patterns
• OAuth versions differed between Anthropic's MCP spec and OpenAI's connector spec
• CRM data access had to respect HubSpot seats, tiers, and user permissions
• write operations were deferred because CRM data quality and permission checks create higher risk

Architecture

HubSpot built a remote MCP server as a stateless Dropwizard microservice in its Java stack. The service extends the Java MCP SDK for streamable HTTP transport, exposes HubSpot CRM search APIs and RPC methods as MCP tools through annotations, maps OAuth 2.0 scopes to HubSpot seat tiers and user permissions, and provides read-only CRM search/fetch capabilities to OpenAI's ChatGPT connector. HubSpot also built an MCP gateway that auto-discovers tools across services and used Claude Code to generate schemas and templated tool descriptions from the emerging spec. The initial product path emphasizes instant connection for non-technical ChatGPT users rather than local desktop/NPM setup.

Diagram confidence: explicit (topology described by the source).

flowchart LR
  ChatGPT_connector["ChatGPT connector"] --> OAuth_2_0_flow["OAuth 2.0 flow"]
  ChatGPT_connector --> Remote_MCP_server["Remote MCP server"]
  OAuth_2_0_flow --> Permission_mapper["Permission mapper"]
  Permission_mapper --> CRM_search_API["CRM search API"]
  Remote_MCP_server --> Java_MCP_SDK_extension["Java MCP SDK extension"]
  Remote_MCP_server --> Dropwizard_microservice["Dropwizard microservice"]
  Remote_MCP_server --> Streamable_HTTP_transport["Streamable HTTP transport"]
  Remote_MCP_server --> CRM_search_API
  Remote_MCP_server --> MCP_gateway["MCP gateway"]
  Dropwizard_microservice --> Existing_RPC_system["Existing RPC system"]
  Existing_RPC_system --> Annotation_system["Annotation system"]
  Annotation_system --> MCP_gateway
  Annotation_system --> Claude_Code_schema_generation["Claude Code schema generation"]
  Java_MCP_SDK_extension --> Open_source_Java_MCP_SDK["Open source Java MCP SDK"]
  Java_MCP_SDK_extension --> Claude_Code_schema_generation
  CRM_search_API --> CRM_data["CRM data"]
  MCP_gateway --> MCP_clients["MCP clients"]
  MCP_clients --> Breeze_Assistant["Breeze Assistant"]
  MCP_clients --> Discovery_and_registry_service["Discovery and registry service"]
  Breeze_Assistant --> Project_management_tools["Project management tools"]

Components

Data flow

A ChatGPT user connects the HubSpot connector through OAuth 2.0. The remote MCP server receives search/fetch style MCP requests over streamable HTTP, checks the user's HubSpot scopes, seats, tiers, and permissions, and maps requests onto existing CRM search APIs and Java RPC methods exposed through the annotation system. Read-only results for contacts, companies, deals, and related CRM objects return to the AI agent for analysis. Internally, developers use Claude Code and the Java MCP SDK extensions to generate schemas/tool descriptions, while HubSpot contributes the SDK work back to open source.

Why this architecture

HubSpot built instead of buying because the connector had to move at AI speed, integrate with existing enterprise RPC and Java infrastructure, support OAuth permissions, and offer instant connection to non-technical ChatGPT users. Stateless short-lived HTTP requests reduced scaling risk for the first read-only version, while read-only scope lowered the danger of agents corrupting CRM data.

Models used: ChatGPT · Claude Code · Breeze Assistant · Lovable · V0

Scale

• HubSpot says 75% of its customers use ChatGPT.
  “75% of our customers use ChatGPT today. How can we think about the use cases that need to be there?”article, stated
• The connector was built with OpenAI in less than four weeks.
  “we built this connector with OpenAI in four weeks. Or in less than four weeks. And, to move kind of AI speed”article, stated
• ChatGPT was described as having 500 million weekly customers/users.
  “we were offering this connector for... ChatGPT will say it has 500 million weekly customers. Those customers aren't necessarily developers or technical”article, stated
• Internal AI coding tool adoption among engineers is described as upwards of 70-80%.
  “Adoption is, I don't know the exact number, but I think it's upwards in the 70-80% of adoption.”article, stated
• HubSpot observed over 100 HubSpot MCP implementations made by others.
  “We had a bunch of prototypes and POCs. We have over 100 HubSpot MCP, like, made by other people that came online.”article, stated
• Customers query CRM activity over windows such as the last 90 days.
  “over the last 90 days, of all the new contacts and companies that you've seen, give me an analysis”article, stated

Alternatives considered (roads not taken)

Buy an off-the-shelf MCP server product

Rejected because: HubSpot judged that vendor approval, RPC integration, auth requirements, and custom HTTP streaming needs made building faster and easier.

Use local desktop MCP setup

Rejected because: Local MCP servers require NPM/package installation and desktop client configuration, which would not work for non-technical ChatGPT users at consumer scale.

Long-running server-sent event connections

Rejected because: HubSpot chose short-lived HTTP requests because long-lived connections were harder to manage at scale and less aligned with their stack.

Initial read-write CRM agent

Rejected because: HubSpot kept the first version read-only because write access requires permissions, user intent, validation, and data-quality safeguards.

Treat MCP as fully mature and uniform

Rejected because: HubSpot encountered incomplete auth, evolving specs, OpenAI-specific search/fetch behavior, and implementation inconsistencies such as casing conventions.

Patterns

tool-use-orchestration (agent-architecture)

The remote MCP server exposes CRM search/fetch tools and CRM objects to agents through a standardized protocol.

safety-policy-enforcement (governance)

HubSpot maps OAuth scopes to seats and permissions and starts with read-only access to reduce risk from agents modifying CRM data.

structured-output-contract (quality)

HubSpot generated schemas, tool descriptions, and annotation-backed MCP tool specifications so Java RPC methods could be exposed consistently.

model-routing (serving)

HubSpot runs multiple MCP server variants for different connector and API surfaces, including OpenAI-specific search/fetch and core raw CRM APIs.

human-in-the-loop-gate (governance)

HubSpot frames AI tools as augmenting domain experts and engineers rather than replacing human judgment, especially when debugging or specifying complex behavior.

eval-driven-development (quality)

HubSpot evaluated build-vs-buy options, protocol specs, auth capabilities, and production scaling constraints before choosing the remote-server design.

Tradeoffs

Build remote MCP server in-house

Chose custom Java/Dropwizard implementation extending the Java MCP SDK over off-the-shelf MCP server products.

Rationale: HubSpot needed speed, enterprise RPC integration, custom auth, and streamable HTTP support, and judged building faster than vendor approval/customization.

Remote connector UX

Chose instant ChatGPT connector for non-technical users over local MCP server setup requiring NPM and desktop configuration.

Rationale: Most target users are CRM users rather than developers, so the connector needed to work without local technical setup.

Stateless short-lived HTTP

Chose short-lived stateless HTTP requests over long-lived server-event connections.

Rationale: The short-request design fit HubSpot's existing stack and avoided scale/connection-management concerns.

Read-only first version

Chose read-only CRM queries over agent write operations against CRM data.

Rationale: Read-only access reduces risk, simplifies scale, and avoids premature write-permission/data-quality hazards.

Open-source SDK contribution

Chose feed Java MCP SDK extensions and learnings back upstream over keeping all implementation work private.

Rationale: Open standards and shared SDK improvements accelerated HubSpot's own work and benefit the broader ecosystem.

Gotchas (what bit them)

MCP was still early enough that auth and conventions were incomplete.

Root cause: The protocol was emerging, with OpenAI-specific features, OAuth-version differences, and inconsistent casing across implementations.

Resolution: Implement the required auth/scoping pieces, support OpenAI's MCP variant, and expect custom extensions while contributing learnings back.

Remote MCP is harder than local MCP.

Root cause: Remote servers require microservice architecture, transport choices, stateless/stateful decisions, auth, and scale planning.

Resolution: Use a Dropwizard microservice, short-lived stateless HTTP requests, and SDK extensions for streamable HTTP.

Long-lived connections are harder to operate at scale.

Root cause: Server-sent/event-style connections introduce traffic-dependent connection management concerns.

Resolution: HubSpot chose stateless short-lived HTTP requests aligned with its current stack.

Write access to CRM data is much riskier than read-only analysis.

Root cause: Even authorized users may not know what they are doing, and CRM data may already be inconsistent or low quality.

Resolution: Start with read-only queries and defer write operations until additional permission and validation safeguards are designed.

Agent tool ecosystems need discovery and trust, not just many servers.

Root cause: There are many MCP servers, and it is hard to know which are verified, high quality, or security-conscious.

Resolution: Build discovery and registry services so clients find verified secure MCP servers.

AI-assisted code generation still requires domain and debugging expertise.

Root cause: Code agents can accelerate templating and micro changes but still struggle when bugs accumulate or the developer lacks context.

Resolution: Use AI as an Iron-Man-suit style accelerator with humans controlling specs, domain judgment, and debugging.

Evaluation

The source does not describe a formal benchmark. Evaluation is described through build-vs-buy analysis, compatibility with HubSpot's RPC/Java stack, OAuth/permission requirements, production load observation, SDK prototyping, and product usage: the read-only stateless connector reportedly had no load or server issues and was already delivering value to many customers.

Metrics: 75% of HubSpot customers use ChatGPT · less than four-week connector build · 500 million weekly ChatGPT customers/users · two remote MCP servers and one local server in play · over 100 HubSpot MCP implementations made by others · 70-80% internal adoption of AI coding tools among engineers · no load or server issues reported for stateless read-only version · OpenAI connector supports OAuth 2.0 while Anthropic MCP spec supports OAuth 2.1

Outcomes

• HubSpot became the first CRM with an MCP server and connector to OpenAI, according to the interview.
• The connector was built with OpenAI in less than four weeks.
• The first version supports read-only CRM analysis through ChatGPT.
• HubSpot extended the Java MCP SDK for streamable HTTP and contributed back to the SDK.
• The stateless short-HTTP design had no reported load or server issues.
• Customers can ask natural-language questions over CRM contacts, companies, deals, regions, and conversion patterns.
• HubSpot continues to build MCP clients, discovery/registry services, Breeze Assistant integrations, and additional MCP servers.

This is a strong production MCP case because it connects standardization, product UX, security, and operational scale. The read-only scope is a deliberate limitation, not a missing feature: it makes first deployment safer while the protocol, auth model, and write safeguards mature.