The HS-X MCP server.

TL;DR

The 30-second answer

One command registers the server with Claude Code; the agent gets eight tools.

claude mcp add hs-x -- npx -y @hs-x/mcp

The transport is stdio: newline-delimited JSON-RPC, MCP protocol 2024-11-05, methods initialize, tools/list, and tools/call. Every tool result is one text content item — pretty-printed JSON for every tool except hsx.docs.fetch, which returns the page markdown verbatim. A tool that fails returns a result flagged isError: true whose text is { "ok": false, "tool": "<name>", "error": "<message>" }, carrying the same hint text the CLI prints; JSON-RPC error objects are reserved for protocol faults (an unknown tool name, malformed tools/call params, an unsupported method).

01 · Scope

What ships today

The shipped tool surface validates a project, inspects or safely stops an existing dev session, tails its log, and writes one kind of deployment secret. This local stdio @hs-x/mcp coding-agent server is distinct from a HubSpot Breeze mcp-server component, which registers your external OAuth-protected remote service with HubSpot; use the Breeze MCP guide for that workflow. The coding-agent MCP server does not expose project-code execution, scaffold, connect, deploy, promote, or rollback as tools. For those, agents run the CLI directly; every hs-x command accepts --json and returns a machine-readable envelope, so a shell tool plus the CLI reference covers the rest of the lifecycle today.

Project validation over MCP and hs-x dev invoke in the CLI share the same project model. Capability execution remains CLI-only until HS-X can run it outside the credential-bearing MCP process. The testing guide walks the supported terminal loop end to end.

02 · Registration

Wire it into your agent

Registration is manual and takes one command or one JSON block per agent. Installing @hs-x/cli does not write MCP entries into any agent config, and there is no hosted endpoint to point a URL at; the server runs on your machine, in the directory whose project you want it to see.

For Claude Code, register it user-wide or per project:

claude mcp add hs-x -- npx -y @hs-x/mcp

For Cursor (in ~/.cursor/mcp.json), or any agent that reads the common mcpServers shape, the equivalent entry is:

{
  "mcpServers": {
    "hs-x": {
      "command": "npx",
      "args": ["-y", "@hs-x/mcp"]
    }
  }
}

A project-scoped .mcp.json at the repo root uses the same shape and keeps the server's working directory inside the project, which is what the tools default to.

The package installs a hs-x-mcp binary, so a global npm i -g @hs-x/mcp followed by "command": "hs-x-mcp" works the same way. Pin nothing else; the server has no flags.

03 · Tools

The eight tools

Every project tool takes an optional root, a path to the project to operate on. It defaults to the server's working directory, and it must resolve inside that directory (or inside an allowed root; see the next section). That containment is enforced server-side, so an agent cannot wander the filesystem by passing ../.

hsx.status

Project health at a glance, using the same validation substrate as hs-x status: whether the project is ok, how many files were checked, and diagnostic counts by severity.

{ "root": "." }

Returns ok, root, filesChecked, and diagnosticsBySeverity with error and warning counts.

hsx.check

The full diagnostic list behind the summary, equivalent to hs-x check. Same single optional root argument. Returns every diagnostic with its code, severity, message, and where present the file and line, so an agent can fix findings without re-running anything in a terminal.

Project-code discovery, invocation and replay, and dev-server startup are deliberately not exposed through the local MCP process, because a tool that imports or spawns project code would run it with the MCP server's credentials and local-user authority. Use hs-x dev, hs-x dev invoke, and the dev HTTP API directly until a separately deployed, credential-isolated sandbox service exists.

hsx.dev.session.status

Whether the recorded session is actually alive. Reads .hs-x/dev-session.json, probes /_hsx/health, and returns running alongside the recorded url, pid, and port. No record means running: false, not an error. If the recorded pid is alive but is not this project's HS-X dev process, running is false and reason reads recorded process identity mismatch.

hsx.dev.session.stop

Stops the session: SIGTERM to the recorded pid, then removes .hs-x/dev-session.json. Stopping when nothing is running succeeds with running: false, so an agent can call it without checking first. The one refusal: if the recorded pid belongs to some other process, the tool fails with Refusing to stop the recorded pid because it is not the HS-X dev process for this project. rather than sending a signal.

hsx.dev.logs

Tails the local session log (.hs-x/dev-server.log, the request lines and handler logs the dev server accumulates) and, when .hs-x/hubspot.json binds a deployed app, appends HubSpot's own app-log rows for the same project — card and extension renders, proxy executions, webhooks, OAuth — the same merged timeline hs-x logs prints. Takes lines (default 50, max 1000) and sinceMinutes (the HubSpot lookback, default 15, max 10080) alongside root. Returns logPath, the trailing lines, and a hubspot object: { active: true, appId, rows } when the HubSpot leg ran, or { active: false, reason } when there is no app binding or no HubSpot CLI credential. A missing HubSpot leg is a reason, never an error, so the local tail always comes back.

hsx.secrets.hubspot_oauth.set

Stores a HubSpot app OAuth client secret on the control plane for one account, project, environment, and app: the MCP twin of hs-x secrets hubspot-oauth set. This is the one tool that talks to the network and the one that needs a credential (see below). Because it mutates credential state, every call must explicitly pass "confirm": true.

{
  "accountId": "acct_123",
  "projectId": "deal-tagger",
  "hubSpotAppId": 4837261,
  "clientId": "client-id",
  "clientSecret": "client-secret",
  "environment": "staging",
  "confirm": true
}

environment is production, staging, or dev and defaults to production. Missing or false confirm is rejected before the MCP server reads its bearer credential, resolves the destination, or starts a network request. The response confirms a successful write and never echoes the secret material back through the transport. The destination is fixed by the server's HSX_CONTROL_PLANE_URL; a tool call cannot override it.

hsx.docs.search

Searches the HS-X documentation by keyword and returns ranked pages — title, section, the markdown url, and a one-line description — drawn from the docs site's llms.txt catalog. Unlike the project tools it takes no root; it reads the public docs site over the network. The catalog is streamed with a 1 MiB cap and strict UTF-8 decoding.

{ "query": "webhook signature dedup", "limit": 8 }

limit is optional (default 8, max 25). Follow a result up with hsx.docs.fetch.

hsx.docs.fetch

Fetches one documentation page as clean markdown — the .md mirror behind any /docs URL. Pass a path or URL from hsx.docs.search (with or without the .md suffix); the tool returns the page body as text, ready to read. The path must live under /docs/; anything else is rejected. Pages are streamed with a 2 MiB cap, an 8-second timeout, and strict UTF-8 decoding.

{ "path": "/docs/guides/triggers" }

Both docs tools read from https://hs-x.dev by default; set HSX_DOCS_URL to point them at another docs deployment.

04 · Credentials

Roots, tokens, environment

The five local project/session tools need no HS-X credential. (hsx.dev.logs will additionally use your HubSpot CLI login, if one exists, to fetch HubSpot app logs; without it the local tail still works.) Configuration is four environment variables on the server process, set in the env block of your agent's MCP entry:

• HSX_MCP_ALLOWED_ROOTS widens the root sandbox beyond the working directory: a colon-separated list of absolute paths the root argument may also resolve into.
• HSX_SESSION_TOKEN authorizes hsx.secrets.hubspot_oauth.set. It is the same API token you generate in the dashboard and paste into hs-x login, supplied here as an environment variable. The MCP server does not read the CLI's stored account credentials; without the variable, the secrets tool refuses with instructions and everything else keeps working.
• HSX_CONTROL_PLANE_URL fixes the public HTTPS origin for the secrets tool (default https://api.hs-x.dev). Credential-bearing tool calls cannot override it; origins with credentials, paths, queries, fragments, loopback/private IPs, or redirects are rejected. Production requests pin the connection to the validated DNS result while TLS verifies the original hostname, and response bodies are capped at 64 KiB.
• HSX_DOCS_URL overrides the docs site the hsx.docs.search and hsx.docs.fetch tools read from (default https://hs-x.dev). They need no credential — the docs are public.

{
  "mcpServers": {
    "hs-x": {
      "command": "npx",
      "args": ["-y", "@hs-x/mcp"],
      "env": { "HSX_SESSION_TOKEN": "hsx_token_from_the_dashboard" }
    }
  }
}

05 · Design preview

What is not shipped yet

Two pieces of the MCP story are design preview, documented so you can tell the boundary; neither is callable today.

• A hosted HTTP transport. The server is stdio-only. There is no remote MCP endpoint to claude mcp add --transport http against; registration always launches a local process.
• Tool coverage of the wider CLI. Scaffold, connect, deploy, promote, rollback, production log tailing (hs-x logs), and migrate exist as CLI commands, not MCP tools — hsx.dev.logs reads the local dev session plus HubSpot's app logs; it never reads Workers Logs from a deployed Worker (that is hs-x logs). The intended path for agents today is the shell with --json; first-class tools for more of the lifecycle land behind the same dispatcher as the eight above.

When either ships, this page changes first.

Related

Where the tools lead

• CLI reference — every shipped command an agent can drive with --json, including the hs-x secrets twin of the secrets tool.
• Test a migrated app — the discover, invoke, replay loop in practice: terminal, agent, and raw HTTP.
• Local dev — what hs-x dev adds on top of one-shot invocation: a real portal, live reload, log streaming.
• Agent tools — the other MCP in the picture: capabilities your Worker exposes to HubSpot's Breeze agents.
• Secrets — why the runtime needs hubspot-oauth set and what it unlocks.
• Getting started — the first session the tools slot into.

Last updated: August 27, 2026. Reflects the current @hs-x/mcp release (MCP protocol 2024-11-05); the server self-reports its version in initialize.serverInfo, and the tool list mirrors its own tools/list. Refreshed whenever the tool surface changes.