LQABR HubSpot Server

The LQABR central HubSpot MCP server. Built on FastMCP, and standalone — no dependency on the LQABR mono-repo.

RUNNING.md — how to run it: setup, credentials, both transports, agentgateway, troubleshooting. CONSUMING.md — how the email / voice / scheduling agents call it: ADK McpToolset, auth, the wire contract, tool scoping. This file is the design rationale; those two are the procedures.

LQABR_MCP/
├── hubspot-crm-mcp-server/
│   ├── __init__.py              (empty, per mcp.odt Step 4)
│   ├── hubspot_crm_server.py    the launcher — mcp.odt Step 5
│   ├── test_server.py           remote smoke test — handoff S8
│   ├── hubspot_mcp/             THE IMPLEMENTATION (vendored)
│   │   ├── __init__.py          provenance + drift warning — read this
│   │   ├── server.py            the FastMCP object + the two tools
│   │   ├── secrets.py           Secret Manager access
│   │   ├── obs/                 the four logs: system/process/audit/tokens
│   │   │   ├── __init__.py
│   │   │   ├── context.py       RunContext, run_id, lead_ref_id
│   │   │   └── loggers.py
│   │   └── hubspot/
│   │       ├── __init__.py
│   │       ├── crm.py           upsert_lead_profiles / get_lead_profile
│   │       ├── auth.py          get_hubspot_token(), short-lived M2M
│   │       ├── schema.py        LeadProfile, PushResult, property mapping
│   │       └── failures.py      failure taxonomy + CircuitBreaker
│   └── tests/                   61 tests ported from the mono-repo
├── .vscode/hubspot_mcp.json     stdio config — mcp.odt Steps 7–8
├── Dockerfile                   Cloud Run image — handoff S4
├── .dockerignore
├── pytest.ini
├── .python-version              3.12, matching the Dockerfile
├── .env.example                 mode switches + secret IDs (no values)
├── pyproject.toml
├── RUNNING.md                   step-by-step runbook — start here
├── CONSUMING.md                 client integration guide for other agents
└── README.md

This is a fork, not a move

hubspot_mcp/ is a copy of the mono-repo's implementation. Only the import lines were rewritten; no logic, field name or HubSpot property name changed. Verified by diff — the only differing lines across all nine files are:

- from lqabr_core.obs import get_obs, utc_now_iso
+ from ..obs import get_obs, utc_now_iso
- from lqabr_core.leadgen.secrets import ...
+ from ..secrets import ...

The mono-repo still needs its copy. Do not delete it.

Module	Also used by
lqabr_core.obs	8 files in lead_profile/src, 2 in text_voice/src, lqabr_core/crm
lqabr_core.leadgen.*	12 lead_profile files incl. call_mcp.py, plus evals/run_eval.py
lqabr_core.leadgen.secrets	lead_profile model.py, 2 test files

The consequence: there are now two write paths to HubSpot carrying the same field names and the same HubSpot property names — and the data contract says those names are the contract. Any fix to crm.py, any auth change, any HubSpot property rename must be applied in both places by hand. Nothing enforces it. Budget for that, or plan to retire one side.

Why this lives outside the mono-repo

The LQABR repo has a top-level package literally named mcp at its root, which shadows the mcp SDK that FastMCP depends on. Running from inside the repo breaks FastMCP's own imports.

Do not add the LQABR repo root to PYTHONPATH.

Library: FastMCP, not the official SDK

The dependency is fastmcp>=3.4.7. Do not add mcp>=2.0 — the two are mutually exclusive:

• fastmcp 3.4.7 pins mcp<2.0,>=1.24.0 transitively (it installs mcp 1.29).
• MCPServer, the official SDK's server class, exists only in mcp>=2.0.

So a project can use FastMCP or MCPServer, never both. This one uses FastMCP. Nothing here imports MCPServer.

Two consequences worth knowing:

• Transport names differ. FastMCP's HTTP transport is "http" ("streamable-http" is accepted as an alias) and the endpoint path kwarg is path=. The official SDK spells that streamable_http_path=.
• Type fields differ. Because mcp is pinned to 1.x, the bundled types use camelCase: Tool.inputSchema, not input_schema.

The mono-repo's lqabr_core/leadgen/server.py still uses MCPServer. That is now a second divergence between the two codebases, on top of the fork.

Running it

uv sync

# stdio — local ADK MCPToolset, or the VSCode config in .vscode/
uv run python hubspot-crm-mcp-server/hubspot_crm_server.py

# HTTP — what Cloud Run runs
uv run python hubspot-crm-mcp-server/hubspot_crm_server.py \
    --transport http --host 0.0.0.0 --port 8080

Credentials

tools/list needs nothing. A tool call needs the HubSpot token, and that comes from Secret Manager — context §7.6 / CLAUDE.md §5: secrets are never hard-coded and never committed.

cp .env.example .env                    # holds mode switches + secret IDs only
gcloud auth application-default login
uv sync --extra gcp --extra test        # both extras; --extra gcp alone drops pytest
export UV_ENV_FILE=.env

uv sync --extra <x> syncs exactly that extra set, so --extra gcp on its own uninstalls pytest. test_server.py runs as a CLI without pytest, but uv run pytest obviously needs it.

.env carries no secret values — just HUBSPOT_AUTH_MODE, LQABR_SECRET_PROJECT and the secret's ID. The token itself is fetched over the Secret Manager API at runtime, held in memory, never logged (the audit line records only length and last four characters), and cached for 900s so rotation needs no redeploy.

auth.py and secrets.py both fail closed — unset means an explicit error, never a silent default.

LQABR_SECRET_BACKEND=env exists as a last resort for offline work or CI. secrets.py scopes it to "local development, CI and tests only" and there is no automatic fallback to it — you must type it. It puts a live credential in a file on disk. Never set it in Cloud Run.

Every flag has an env-var default (MCP_TRANSPORT, MCP_HOST, PORT, MCP_PATH), so the container starts with no arguments — Cloud Run injects PORT.

Tests

uv run pytest              # 61 tests, all passing, none touch real HubSpot

pytest.ini puts hubspot-crm-mcp-server/ on the path so import hubspot_mcp resolves — the folder itself can't be a package because of the hyphen.

The contract is TEN fields, not nine

LeadProfile carries ten: the nine everyone documents, plus contact_name (added for the firstname/lastname mapping). The mono-repo's test_wrapper_shape_is_the_nine_fields_plus_ids still asserted 9 and had been failing there — schema.py is byte-identical, so this project inherited it.

Resolved 2026-08-18: the code was right, the number was stale. The test is renamed test_wrapper_shape_is_the_contract_fields_plus_ids and now asserts the field names rather than a count, so the next addition fails with something readable.

The same fix is still owed to the mono-repo — that assertion is unchanged there and still red. The docs that say "9 fields" should be corrected too.

Testing a deployed server

# local
uv run python hubspot-crm-mcp-server/test_server.py

# Cloud Run — mints a Google ID token via ADC
uv run python hubspot-crm-mcp-server/test_server.py \
    --url https://lqabr-mcp-server-xxxx.a.run.app/mcp --auth google

# one real read against HubSpot — writes nothing
... --auth google --employee-id EMP-00042

Read-only by design: it never calls upsert_lead_profile. Sends X-LQABR-Run-Id so the server's audit logs attribute the call (the B10 fix).

The ID token audience is the service base URL without /mcp. The script strips it for you.

The client uses fastmcp.Client, which handles the initialize handshake, so there is no session plumbing in this file. Headers ride on a StreamableHttpTransport. This now matches the reference sample's library.

Deploying to Cloud Run

Two-stage uv build, non-root mcp user, PID 1 is Python so SIGTERM drains cleanly. Self-contained: no sibling folder, no git dependency.

docker build -t lqabr-mcp-server .

Commit a uv.lock and switch the sync to --frozen before production.

Then S5–S8: create mcp-server-sa, grant secretmanager.secretAccessor on lqabr-hubspot-access-token, deploy --no-allow-unauthenticated, grant the three agent service accounts roles/run.invoker, point test_server.py at it.

Tools exposed

Tool	Direction	Notes
upsert_lead_profile	write	Company upsert → Contact upsert → association. Idempotent.
get_lead_profile	read	contract fields + contact_hs_id + company_hs_id.

Dedup: Contact on employee_id, Company on company_id. Email lives in the custom email_id property.

Open item. The registered tool name is upsert_lead_profile (singular), but the design docs, session handoff and project instructions all say upsert_lead_profiles (plural), and the underlying function is plural. This is a wire contract — settle it before any client wires up.

Credentials

Two, never confused:

• Google ID token proves agent → this server (Cloud Run service-to-service).
• HubSpot M2M token proves this server → HubSpot, minted per call inside the server. Callers never see it.

This service is the sole holder of the HubSpot credential.

Verified

In a clean venv containing only fastmcp 3.4.7 (which brought mcp 1.29), requests and pytest — with lqabr_core absent (confirmed ModuleNotFoundError) and MCPServer absent (confirmed ImportError):

• zero lqabr_core imports anywhere in the project
• ported test suite: 61 passed, 0 failed
• stdio — tools/list returns both tools, PYTHONPATH stripped entirely
• --transport http — binds host/port/path, full fastmcp.Client session
• --transport streamable-http — alias accepted, serves the same endpoint
• test_server.py — PASS against the running server, exit 0
• test_server.py under pytest — 3 passed with a server, 3 skipped without
• live call_tool reached the real chain: transport → tool → crm.py → auth.py → secrets.py, failing only at the deliberate AuthConfigError / SecretConfigError guards (no GCP config in the test environment). The wiring is proven end to end.

Not verified: the Docker image has never been built — no Docker daemon was available where these files were assembled. Nothing has touched real HubSpot; every test uses a fake.