# The HS-X MCP server.

HS-X ships a stdio MCP server, @hs-x/mcp, that gives coding agents a structured handle on a local project: validate it, list its capabilities, invoke any of them through the production runtime router, replay the last dispatch, run a background dev session and tail its log, store a HubSpot OAuth secret, and search the HS-X documentation. The surface is deliberately small. Everything else the CLI does, an agent reaches by running hs-x with --json in a shell. This page lists every tool with its input shape, plus registration and credentials.

## The 30-second tour

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

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

| Tool | What it does |
| --- | --- |
| `hsx.status` | Project health summary: files checked, diagnostic counts |
| `hsx.check` | Full validation diagnostics, the same substrate as `hs-x check` |
| `hsx.dev.capabilities` | List every worker and capability id in the project |
| `hsx.dev.invoke` | Run one capability through the production runtime router |
| `hsx.dev.invoke_last` | Replay the last recorded invocation |
| `hsx.dev.session.start` | Start a background dev server for the project (logs to `.hs-x/dev-server.log`) |
| `hsx.dev.session.status` | Health + identity of the running session |
| `hsx.dev.session.stop` | Stop the session |
| `hsx.dev.logs` | Tail the session log — request lines + handler logs |
| `hsx.secrets.hubspot_oauth.set` | Store a HubSpot app OAuth client secret |
| `hsx.docs.search` | Search the HS-X docs (guides, answers, reference) by keyword |
| `hsx.docs.fetch` | Fetch one docs page as clean markdown |

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.

## 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](/docs/cli) 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](/docs/guides/test-a-migrated-app) walks that loop end to end, three ways.

## 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:

```sh
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:

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

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

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

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

```json
{
  "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](/docs/guides/dev-mode) 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.

```json
{ "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).

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

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

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

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

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

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

## Where the tools lead

- [CLI reference](/docs/cli) — every shipped command an agent can drive with `--json`, including the `hs-x secrets` twin of the secrets tool.
- [Test a migrated app](/docs/guides/test-a-migrated-app) — the discover, invoke, replay loop in practice: terminal, agent, and raw HTTP.
- [Local dev](/docs/guides/dev-mode) — what `hs-x dev` adds on top of one-shot invocation: a real portal, live reload, log streaming.
- [Agent tools](/docs/guides/agent-tools) — the other MCP in the picture: capabilities your Worker exposes to HubSpot's Breeze agents.
- [Secrets](/docs/guides/secrets) — why the runtime needs `hubspot-oauth set` and what it unlocks.
- [Getting started](/docs/guides/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.*