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