The HS-X MCP server.

TL;DR

The 30-second tour

One command registers the server with Claude Code; the agent gets twelve 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 containing pretty-printed JSON, and failures come back as JSON-RPC errors carrying the same hint text the CLI prints.

01 · Scope

What ships today

The shipped tool surface is the local loop: validate a project, discover its capabilities, invoke them, replay a failure, run a background dev session and tail its log, and write one kind of deployment secret. The MCP server does not expose 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.

The nine project tools and hs-x dev invoke share one engine. A capability invoked over MCP goes through the same runtime router a deployed Worker serves: payload validation, context construction, handler, result envelope. A green result from an agent means the same thing as a green result from your terminal. The testing guide walks that loop end to end, three ways.

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

hsx.dev.capabilities

Lists the workers a project declares and each worker's capabilities: tools, triggers, card backends, syncs, with their ids and kinds. This is the discovery step; the ids it returns are exactly what hsx.dev.invoke accepts, so an agent never guesses.

{ "root": "." }

hsx.dev.invoke

Invokes one capability through the production runtime router, in process. Fixture defaults fill the dispatch payload, enough for handlers that only read their input and the enrolled object; pass input, enrolledObject, or install to override them. Handlers that call HubSpot APIs through ctx.hubspot need a connected portal, the same boundary production has.

{
  "capabilityId": "score-record",
  "input": { "threshold": 50 },
  "enrolledObject": { "id": "d1", "objectType": "deals", "properties": { "amount": "99000" } }
}

Returns ok, the owning worker, the capability kind, the HTTP status the router produced, and the full response envelope. Every invocation also records its exact dispatch to .hs-x/last-invocation.json in the project.

hsx.dev.invoke_last

Replays the recorded dispatch from .hs-x/last-invocation.json: same capability, same payload, byte for byte. This is the failure-replay loop; an agent edits the handler and replays without reconstructing the payload. Takes only the optional root, and errors with a pointed message if nothing has been recorded yet.

hsx.dev.session.start

Starts a dev server for the project as a detached background process — the same hs-x dev the local dev guide describes, so @hs-x/cli must be installed with hs-x on the PATH. Output streams to .hs-x/dev-server.log, and the session record lands in .hs-x/dev-session.json. One session per project: if a healthy session is already up, the tool returns it with alreadyRunning: true instead of spawning a second.

{ "root": ".", "port": 8787 }

port is optional and defaults to 8787. Returns url, pid, port, and logPath once /_hsx/health responds; if the server is not healthy within ten seconds, the tool errors and points you at hsx.dev.logs.

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.

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.

hsx.dev.logs

Tails the session log — the request lines and handler logs that .hs-x/dev-server.log accumulates. Takes an optional lines (default 50) alongside root, and returns the logPath plus the trailing lines, so an agent can see what a failing dev request actually did without leaving the transport.

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

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

environment is production, staging, or dev and defaults to production. An optional controlPlaneUrl redirects that one call to a different control-plane endpoint, taking precedence over the HSX_CONTROL_PLANE_URL environment variable. The response confirms the write and never echoes the secret material back through the transport.

hsx.docs.search

Searches the HS-X documentation by keyword and returns ranked pages — title, section, the markdown URL, and a one-line summary — 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.

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

{ "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 nine project tools need no credentials at all; they read, invoke, and serve local source. The one prerequisite among them is hsx.dev.session.start, which spawns the installed hs-x binary and therefore expects @hs-x/cli on the PATH — a binary, not a credential. Configuration is three 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 overrides the control-plane endpoint for the secrets tool (default https://api.hs-x.dev); the tool's per-call controlPlaneUrl argument wins over both.
• 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 only, never a deployed Worker. 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 twelve 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: June 10, 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.