MCP client and server

Test an MCP server

Hitspec can test local stdio servers and remote Streamable HTTP endpoints from the same CLI. probe completes protocol negotiation, follows every tools/list page, resolves each advertised input/output JSON Schema, and returns a failed test when a required tool is missing.

stdio
Streamable HTTP

Put the server executable and each argument after --. Hitspec executes the argv directly and does not invoke a shell.

hitspec mcp probe \
  --require-tool echo \
  --require-tool health \
  -- ./my-mcp-server --config ./server.json

hitspec mcp probe \
  --url http://127.0.0.1:3000/mcp \
  --require-tool echo \
  --json

The client uses the official Go SDK, whose current release supports stable MCP 2025-11-25, and reports the protocol version actually negotiated with the server in both human and JSON output.

Call a tool

call first verifies that the server advertises the exact, case-sensitive tool name, then sends one explicit tools/call request:

# Inline JSON arguments over stdio
hitspec mcp call echo \
  --args '{"message":"hello"}' \
  -- ./my-mcp-server

# Arguments from a bounded JSON file over Streamable HTTP
hitspec mcp call weather \
  --args @weather.json \
  --url https://mcp.example.com/mcp \
  --json

Arguments must be a JSON object and are limited to 1 MiB when read from a file. Before execution, Hitspec validates them against the advertised inputSchema; successful structured output is validated against outputSchema when present. Hitspec prints tool content before exiting. A protocol or transport error exits with code 4; a contract mismatch, an advertised tool that returns isError: true, an unknown tool, or a missing --require-tool exits with code 1. This preserves MCP’s distinction between a failed tool execution and a failed protocol request.

mcp call executes the selected tool and may cause external changes. Review the tool and arguments before running it. Tool annotations, descriptions, and output are server-provided data, not trusted authorization metadata.

Client flags

Flag	Applies to	Default	Behavior
`--url`	Both	unset	Streamable HTTP endpoint. Mutually exclusive with a stdio argv.
`--timeout`	Both	`30s`	Maximum duration for connect, discovery, and call.
`--json`	Both	`false`	Emit a stable machine-readable report.
`--header`	HTTP	unset	Repeatable `Name: Value` header. Transport-managed MCP headers are rejected.
`--env`	stdio	inherited	Repeatable `KEY=VALUE` child-process override. Hitspec does not echo values; child stderr is forwarded.
`--cwd`	stdio	current directory	Child-process working directory.
`--require-tool`	`probe`	unset	Require a tool name. Repeat the flag or pass comma-separated names.
`--args`	`call`	`{}`	Inline JSON object or `@path` to a JSON file.

HTTP redirects are rejected so credentials cannot cross endpoint boundaries. URLs containing credentials are also rejected; send authorization explicitly with --header. For repeatable automation, inject sensitive values through the calling environment or secret manager and avoid committing them to scripts.

Run Hitspec as an MCP server

Run Hitspec as a workspace-scoped Model Context Protocol server:

hitspec mcp serve --workspace /absolute/path/to/api-workspace

stdout is reserved exclusively for MCP JSON-RPC. The server does not start run history or a file watcher or execute shell hooks or database assertions. In v2.18.0, web search and durable capture are registered only when their operator-owned provider and artifact sink, respectively, are configured at startup. MCP initialization instructions are built from that registered surface, so clients are not prompted to use unconfigured search or capture tools. They also state whether hitspec_fetch is public-only or has operator-enabled non-public HTTP(S) authority, including private, loopback, link-local, and reserved targets; this does not broaden the public-only capture policy.

Tools

Tool	Purpose	Registered when
`hitspec_fetch`	Fetch one direct URL or one saved request as `raw`, `text`, `markdown`, or `json`.	Always
`hitspec_search_web`	Search the live public web and return normalized discovery candidates without persistence.	A search provider is configured
`hitspec_capture_webpage`	GET one public webpage, render Markdown, and preserve it in file.cheap.	An artifact sink is configured
`hitspec_list_requests`	List names, methods, source lines, and tags in workspace Hitspec files.	Always
`hitspec_validate`	Parse and structurally validate one workspace file without executing it.	Always

Hitspec is the only model-visible web surface. Tavily is the initial internal search provider and can be replaced without changing these tool names or schemas.

`hitspec_fetch` input

Field	Type	Applies to	Default and behavior
`url`	string	Direct URL	HTTP(S) URL. Supply exactly one of `url` or `file`.
`file`	string	Saved request	Workspace-relative `.http` or `.hitspec` file. Supply exactly one of `file` or `url`.
`name`	string	Saved request	Selects a uniquely named request. Mutually exclusive with `index`.
`index`	integer	Saved request	Selects a request by its one-based position. Mutually exclusive with `name`.
`environment`	string	Saved request	Environment name. Defaults to the config’s default environment, then `dev`.
`env_file`	string	Saved request	Workspace-relative dotenv file.
`config_file`	string	Saved request	Workspace-relative Hitspec config file.
`method`	string	Direct URL	HTTP method. Defaults to `GET`, or `POST` when `body` is non-empty.
`headers`	object	Direct URL	Map of request header names to string values.
`body`	string	Direct URL	UTF-8 request body.
`format`	string	Both	`text`. Accepts `raw`, `text`, `markdown`, or `json`.
`no_follow`	boolean	Both	`false`. When true, stops at the first redirect. Redirect chains otherwise have a fixed limit of 10.

A file containing multiple requests requires name or index. A saved request that declares @depends is rejected. Assertions, captures, conditions, hooks, shell blocks, database assertions, and @waitFor are not executed. hitspec_fetch never persists the response; use hitspec_capture_webpage for a durable artifact.

Live web search and capture

hitspec_search_web has this provider-neutral tool input:

Field	Type	Default and behavior
`query`	string	Required; maximum 512 Unicode characters.
`max_results`	integer	`5`; accepts 1–10.
`language`	string	Optional BCP 47 language hint. A provider returns an explicit error when it cannot apply the filter; Tavily does not currently support it.
`freshness`	string	`any`; accepts `any`, `day`, `week`, `month`, or `year`.
`include_domains`	string[]	Optional; at most 20 normalized public domains.
`exclude_domains`	string[]	Optional; at most 20 normalized public domains. A domain cannot appear in both lists.

The tool does not accept a provider, endpoint, API key, authorization header, arbitrary headers, generated-answer switch, or raw-content switch. Tavily is an internal adapter selected by the server operator, not a separate model-visible tool. The JSON document is capped at 64 KiB. It contains kind: "discovery", normalized query, results, and truncated. Each result contains only title, url, domain, snippet, optional published_at, and a response-local citation_id. truncated is true whenever candidates are omitted by the result limit or response cap; for the latter, Hitspec removes trailing results. Provider-specific request IDs and scores, generated answers, raw page content, and credentials are never exposed. Search snippets are discovery candidates, not verified or durable evidence. hitspec_capture_webpage has this compatibility-preserving input:

Field	Type	Default and behavior
`url`	string	Required public HTTP(S) webpage URL.
`name`	string	Optional file.cheap stash name; defaults to the HTML title.
`tags`	string[]	Optional extra tags; `web` and `markdown` are always included.
`ttl`	string	Optional file.cheap retention such as `24h`, `7d`, `30d`, or `2026-12-31`.
`index`	boolean	`true`; index the Markdown immediately for `fcheap search`.

The tool performs one public-network GET, renders static HTML as Markdown, and saves it through the fixed file.cheap adapter. It returns a compact receipt, not the page body or rendered Markdown:

{
  "url": "https://example.com/docs",
  "final_url": "https://example.com/docs",
  "title": "Example documentation",
  "http_status": 200,
  "content_type": "text/html",
  "markdown_bytes": 1842,
  "stash": {
    "id": "stash-id",
    "name": "Example documentation",
    "status": "saved",
    "created_at": "2026-07-13T12:00:00Z",
    "tags": ["web", "markdown"],
    "content_hash": "e3b0c442...",
    "file_count": 1,
    "total_size": 1842,
    "index_requested": true,
    "indexed": true
  }
}

The stash object includes file_count and total_size and may also include expires_at. Inspect status, indexed, and failed when present before deciding whether follow-up is needed.

Request discovery and validation input

hitspec_list_requests accepts an optional path: a workspace-relative directory or .http/.hitspec file. It defaults to the workspace root and searches directories recursively. If any discovered Hitspec file is invalid, the tool returns an error instead of an incomplete list.
hitspec_validate requires file, a workspace-relative .http or .hitspec file. Its result reports the file, validity, request count, and parse or structural errors.

Saved file, dotenv, config, and discovery paths are workspace-relative and are checked after symlink resolution.

Tool result content

Every successful tool call includes an MCP TextContent representation so clients that do not pass through structured output can still consume it:

hitspec_fetch with raw returns a JSON text envelope containing sanitized source, status, content type, byte size, encoding: "base64", and data.
text and markdown return their rendered documents as text content. json returns the machine-safe response envelope serialized as text content.
Discovery and validation return their JSON documents serialized as text content.
Search returns the bounded discovery JSON as text content. Webpage capture also publishes its typed compact receipt as structured content when the client supports it.

Server flags

Flag	Default	Behavior
`--workspace`	`.`	Fixes the filesystem boundary exposed to all tools. Use an absolute path in client configuration.
`--max-body-bytes`	`1048576` (1 MiB)	Maximum fetched response-body size.
`--timeout`	`30s`	Maximum duration of one HTTP request.
`--allow-private-network`	`false`	Allows private, loopback, and other non-public targets; it also enables the standard saved-request modes described below.
`--search-provider`	`none`	Live search provider. Currently `none` or `tavily`; may also come from `HITSPEC_SEARCH_PROVIDER`.
`--fcheap-path`	unset	Fixed file.cheap executable for webpage capture; may also come from `HITSPEC_FCHEAP_PATH`.
`--fcheap-stash-dir`	file.cheap default	Optional fixed stash directory; may also come from `HITSPEC_FCHEAP_STASH_DIR`.

Tavily authentication comes only from the server process’s TAVILY_API_KEY. The key is never accepted as a tool argument or returned in output. The file.cheap child receives an allowlisted environment that excludes this key.

Limits and network policy

The default body limit is 1 MiB (--max-body-bytes). Crossing it is an error, never a truncated success.
The default request timeout is 30 seconds (--timeout).
Direct URLs and saved requests allow only public HTTP(S) destinations by default. The initial host, redirects, DNS answers, and dial target are checked.
URL credentials are rejected and response provenance omits URL query strings.
A saved request that uses digest, AWS, or OAuth2 authentication, multipart data, or a configured proxy is rejected under the public-only policy. The proxy is not silently ignored.
Redirect chains are limited to 10; callers can set no_follow to disable redirects entirely.

To test a local API, the person starting the server must grant that authority:

hitspec mcp serve \
  --workspace "$PWD" \
  --allow-private-network

This operator grant also switches saved requests to the standard Hitspec HTTP client, enabling configured proxies and digest, AWS, OAuth2, and multipart request modes. Grant it only to agents and workspaces that need that authority. hitspec_fetch and durable webpage capture are intentionally not marked read-only because HTTP requests and artifact writes can have external effects. The discovery-only hitspec_search_web tool is marked read-only and open-world.

Approval boundaries

Tool	Recommended policy
`hitspec_search_web`	Eligible for AUTO only when this exact bounded tool is explicitly allowlisted.
`hitspec_capture_webpage`	Treat as a public-network read plus durable write; allowlist only when both effects are approved.
`hitspec_fetch`	Keep approval-gated because callers can choose methods, headers, and bodies. It never persists content.

AUTO never enables private-network access or relaxes URL, redirect, DNS, body, or workspace checks.

Direct MCP client configuration

{
  "mcpServers": {
    "hitspec": {
      "command": "hitspec",
      "args": [
        "mcp", "serve",
        "--workspace", "/absolute/api-workspace",
        "--search-provider", "tavily",
        "--fcheap-path", "/absolute/path/to/fcheap"
      ]
    }
  }
}

Inject TAVILY_API_KEY into the server process through the MCP host or tvault; do not write its value into this configuration. See Agent artifact workflow for MCPHub, Local Agent, and file.cheap composition.

Getting Started

Core Concepts

Features

Guides

Examples

CLI Reference

Configuration

Assertions Reference

Built-in Functions

Authentication

Output Formats

Integrations

MCP client and server

Test an MCP server

Call a tool

Client flags

Run Hitspec as an MCP server

Tools

`hitspec_fetch` input

Live web search and capture

Request discovery and validation input

Tool result content

Server flags

Limits and network policy

Approval boundaries

Direct MCP client configuration

​Test an MCP server

​Call a tool

​Client flags

​Run Hitspec as an MCP server

​Tools

​hitspec_fetch input

​Live web search and capture

​Request discovery and validation input

​Tool result content

​Server flags

​Limits and network policy

​Approval boundaries

​Direct MCP client configuration

Test an MCP server

Call a tool

Client flags

Run Hitspec as an MCP server

Tools

`hitspec_fetch` input

Live web search and capture

Request discovery and validation input

Tool result content

Server flags

Limits and network policy

Approval boundaries

Direct MCP client configuration