# MCP reference

Canonical: https://hypaware.ai/docs/mcp-reference

<!-- Generated by scripts/gen-mcp-reference.js. Do not edit by hand: run `node scripts/gen-mcp-reference.js`. -->

HypAware serves MCP in two places:

- `hyp mcp serve`, over stdio, for an agent on your host. It lists the tools core and your active plugins register.
- HypAware Cloud's `/v1/mcp`, over HTTP, for an agent with a member session or an agent token. What it lists depends on the credential.

Every tool below has a CLI command that does the same thing. Each tool's `tools/list` entry carries its title, description, input schema and hints, as shown here.

## Local tools

Registered by core and the bundled plugins. `hyp mcp serve` lists each one whose plugin is active.

### `graph_neighbors`

**Find related sessions**

Walk the activity graph from a node out to N hops

| | |
| --- | --- |
| Title | Find related sessions |
| Auth class | `read`: listed to any caller the host admits |
| Hints | `readOnlyHint: true` |
| Exposure | `cli+mcp`: a CLI command and an MCP tool on every transport |
| CLI equivalent | `hyp query graph neighbors <node>` |
| Registered by | `@hypaware/context-graph` |

| Argument | Type | Required | Default | CLI | Description |
| --- | --- | --- | --- | --- | --- |
| `node` | string | yes |  | `<node>` | Seed node: node_id, natural_key, or label. |
| `depth` | integer, at least 1 | no | `1` | `--depth` | Hops to walk (default 1). |
| `type` | string | no |  | `--type` | Restrict the seed to this node_type. |
| `edge_type` | array of string | no |  | `--edge-type` | Restrict traversal to these edge types. |
| `direction` | string: `out`, `in`, `both` | no | `"both"` | `--direction` | Edge direction to follow (default both). |
| `limit` | integer, at least 1 | no | `100` | `--limit` | Max neighbors to return (default 100). |
| `include-local-only` | boolean | no | `false` | `--include-local-only` | Include local-only graph content even when this context is synced. If this session is itself captured, that content enters the transcript and can be forwarded. |

### `grep_search`

**Search session text**

Grep stored ai_gateway_messages for a case-insensitive substring or regex, served from direct scans of the local cache. It covers only these columns: content_text, tool_name, session_id, conversation_id, agent_id, model, cwd, git_branch, git_remote. Every other column, including system prompts (system_text), tool definitions (tools), attributes, and raw frames, is NOT searched. Zero hits is not evidence the text is absent from those columns: read them with query_sql instead.

| | |
| --- | --- |
| Title | Search session text |
| Auth class | `read`: listed to any caller the host admits |
| Hints | `readOnlyHint: true` |
| Exposure | `cli+mcp`: a CLI command and an MCP tool on every transport |
| CLI equivalent | `hyp query grep <query>` |
| Registered by | `@hypaware/grep` |

| Argument | Type | Required | Default | CLI | Description |
| --- | --- | --- | --- | --- | --- |
| `query` | string | yes |  | `<query>` | Substring to find (case-insensitive), or a regex pattern with regex: true |
| `regex` | boolean | no |  | `--regex` | Treat query as a regular expression (compiled case-insensitive). Servers restrict regex mode to the operator; local search does not. |
| `session_id` | string | no |  | `--session-id` | Only messages of this session |
| `chain_id` | string | no |  | `--chain-id` | Only this chain (matches agent_id or conversation_id) |
| `from` | string | no |  | `--from` | Earliest day, YYYY-MM-DD. Hits come newest first; to page back to older hits, set "to" to an earlier day. |
| `to` | string | no |  | `--to` | Latest day, YYYY-MM-DD |
| `limit` | integer, 1 to 1000 | no | `50` | `--limit` | Max hits (default 50, max 1000) |
| `include-local-only` | boolean | no |  | `--include-local-only` | Include local-only rows even when this context is synced. If this session is itself captured, their content enters the transcript and can be forwarded. Local search only; a server enforces its own visibility |

### `query_sql`

**Run a SQL query**

Run a SQL query against registered datasets

| | |
| --- | --- |
| Title | Run a SQL query |
| Auth class | `read`: listed to any caller the host admits |
| Hints | `readOnlyHint: true` |
| Exposure | `cli+mcp`: a CLI command and an MCP tool on every transport |
| CLI equivalent | `hyp query sql <sql>` |
| Registered by | core |

| Argument | Type | Required | Default | CLI | Description |
| --- | --- | --- | --- | --- | --- |
| `sql` | string | yes |  | `<sql>` | A single read-only SELECT over the registered datasets. |
| `include-local-only` | boolean | no | `false` | `--include-local-only` | Include local-only rows even when this context is synced. If this session is itself captured, their content enters the transcript and can be forwarded. |

## Recommendation tools

Served by HypAware Cloud on `/v1/mcp`. Their names, schemas and CLI equivalents are shared with the client; `hyp mcp serve` does not list them.

### `get_recommendation`

**Read a recommendation**

Read one recommendation: its summary, status, status history and report. Set `include_evidence` for its evidence locators, basis queries, history reasons and links, and its page (capped at 64 KiB). Reading a cited turn is a separate session_evidence or query_sql call.

| | |
| --- | --- |
| Title | Read a recommendation |
| Auth class | `read`: listed to any caller the host admits |
| Hints | `readOnlyHint: true` |
| Exposure | `/v1/mcp` only |
| CLI equivalent | `hyp report get <rec-id>` |
| Registered by | HypAware Cloud, from the shared contract |

| Argument | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | string | yes |  | The recommendation id (hyprec- and 16 hex characters). |
| `include_evidence` | boolean | no | `false` | Add evidence, basis, history reasons and links, and the page. |

### `list_recommendations`

**List recommendations**

List the recommendations in your org's published reports, summary fields only (no evidence or history). `status` defaults to open. `counts` counts the rows this call read, by state: it is not an org total. Pass the returned `next_before` as `before` for the next page. Read one in full with get_recommendation.

| | |
| --- | --- |
| Title | List recommendations |
| Auth class | `read`: listed to any caller the host admits |
| Hints | `readOnlyHint: true` |
| Exposure | `/v1/mcp` only |
| CLI equivalent | `hyp report list --recommendations` |
| Registered by | HypAware Cloud, from the shared contract |

| Argument | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `status` | array of string: `open`, `in_progress`, `applied`, `dismissed` | no | `["open"]` | States to include (default: open). |
| `kind` | string | no |  | Only recommendations from reports of this kind. |
| `period` | string | no |  | Only recommendations from reports for this period. |
| `limit` | integer, 1 to 100 | no | `20` | Most rows to return (1 to 100). |
| `before` | string | no |  | Page cursor: the `next_before` a previous call returned. |

### `set_recommendation_status`

**Set recommendation status**

Set one recommendation's status. After you have fixed it and checked the fix, mark it applied, with a reason and a link to the change, such as the pull request. Dismissing needs a reason. A mark is added to the recommendation's history; nothing is removed.

| | |
| --- | --- |
| Title | Set recommendation status |
| Auth class | `write`, scope `report-publish`: listed only to a credential holding the scope; `hyp mcp serve` passes no scopes |
| Hints | `readOnlyHint: false`, `destructiveHint: false` |
| Exposure | `/v1/mcp` only |
| CLI equivalent | `hyp report mark <id> <state>` |
| Registered by | HypAware Cloud, from the shared contract |

| Argument | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `id` | string | yes |  | The recommendation id (hyprec- and 16 hex characters). |
| `state` | string: `open`, `in_progress`, `applied`, `dismissed` | yes |  | The new state. |
| `reason` | string | no |  | Why, in a line (at most 2000 characters). Required for dismissed. |
| `links` | array of string | no |  | Links to the change, such as the pull request or commit (absolute http(s) URLs, at most 8). |

## Server-only tools

`session_evidence` and the other tools HypAware Cloud registers on its own are defined in the server alone, so they have no entry here. Call `tools/list` on `/v1/mcp` for the tools your credential sees, with their titles, schemas and hints.

## Prompts

Each prompt is an agent command as text an agent can run (`prompts/list`, `prompts/get`). A rendering names only the tools the assembly lists.

### `fix_recommendation`

**Fix a recommendation**

Check one recommendation against the current code, make the change in this repository, and record it as applied. It makes the change without asking first. Review the diff before you merge it.

| | |
| --- | --- |
| Title | Fix a recommendation |
| Over stdio | always |
| Over `/v1/mcp` | when `get_recommendation` is listed |
| CLI equivalent | `hyp report fix <id>` |

| Argument | Required | Description |
| --- | --- | --- |
| `id` | yes | The recommendation id (hyprec- and 16 hex characters). |

### `open_recommendations`

**Open recommendations**

List the open recommendations and pick the ones that apply to this repository.

| | |
| --- | --- |
| Title | Open recommendations |
| Over stdio | always |
| Over `/v1/mcp` | when `list_recommendations` is listed |
| CLI equivalent | `hyp report list --recommendations --status open` |

| Argument | Required | Description |
| --- | --- | --- |
| `kind` | no | Only recommendations from reports of this kind. |
| `limit` | no | Most recommendations to list (1 to 50). |

### `check_team_history`

**Check team history**

Before starting a task, check whether the team has already done it, and what was decided.

| | |
| --- | --- |
| Title | Check team history |
| Over stdio | always |
| Over `/v1/mcp` | always |
| CLI equivalent | `hyp ask` |

| Argument | Required | Description |
| --- | --- | --- |
| `task` | yes | The task, in a sentence (at most 500 characters). |