Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.hyperterse.com/llms.txt

Use this file to discover all available pages before exploring further.

Hyperterse is a full MCP server for tools, prompts, and resources. Discovery and execution use Streamable HTTP and JSON-RPC 2.0 on /mcp. There are no separate REST endpoints per tool, no GraphQL layer, and no custom tool protocol beyond MCP. Hyperterse serves MCP over Streamable HTTP (/mcp) using JSON-RPC 2.0. It supports:
  • two-tool entrypoints (search, execute)
  • first-class prompts
  • first-class resources and URI templates
  • argument completion
  • resource subscriptions
  • progress and logging notifications
  • session continuity across model reloads
Declarative agents use A2A on /agent/{agentName}—separate from MCP. See A2A transport; method details in Runtime API.

​
Endpoints

EndpointMethodsPurpose
/mcpGET, POST, DELETEMCP Streamable HTTP transport and session lifecycle
/heartbeatGETLiveness endpoint ({"success": true})

​
Protocol version

Hyperterse implements MCP 2025-11-25.

​
Capability surface

Hyperterse capability exposure includes:
  • tools (listChanged)
  • prompts (listChanged) when prompt definitions exist
  • resources (listChanged, subscribe) when resources/templates are configured
  • completions
  • logging

​
MCP method support

MethodDirectionNotes
initializeclient -> serverStandard MCP handshake
notifications/initializedclient -> serverStandard MCP post-init notification
pingclient -> serverSupported
tools/listclient -> serverReturns transport entry tools (search, execute)
tools/callclient -> serverCalls search or execute
prompts/listclient -> serverLists configured prompts
prompts/getclient -> serverResolves prompt messages with argument interpolation
resources/listclient -> serverLists concrete resources
resources/templates/listclient -> serverLists URI template resources
resources/readclient -> serverReads concrete or template-resolved content
resources/subscribeclient -> serverValidates subscription target and enables updates
resources/unsubscribeclient -> serverUnsubscribes from resource updates
completion/completeclient -> serverProvides completions for prompt/template arguments
notifications/progressclient -> serverSupported (logged)
notifications/roots/list_changedclient -> serverSupported (logged)
notifications/cancelledclient -> serverSupported (MCP cancellation)

​
Tool entrypoint design

tools/list intentionally exposes exactly two transport entry tools:
  • search — discover project tools by natural language over tool metadata
  • execute — execute a project tool by name with validated inputs
This is a core Hyperterse design choice: project tools are discovered and invoked through these two entrypoints.

​
Search result limit

.hyperterse
tools:
  search:
    limit: 10
If omitted, default is 10.

​
Prompt behavior

Prompts come from:
  • prompt definitions discovered in your project (see Project structure), unless you override the directory in .hyperterse
  • inline prompts in root config
prompts/get interpolates {{ argumentName }} placeholders from request arguments. 
{
  "jsonrpc": "2.0",
  "method": "prompts/get",
  "params": {
    "name": "summarize-release",
    "arguments": { "audience": "engineering", "tone": "concise" }
  },
  "id": 11
}

​
Resource behavior

Resources come from:
  • resource definitions discovered in your project (see Project structure), unless you override the directory in .hyperterse
  • inline resources and resource_templates in root config
resources/read resolves:
  • concrete uri resources (text or file)
  • uri_template resources (text_template or file_template) using URI path values
{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": { "uri": "memory://orders/1001" },
  "id": 21
}

​
Completion behavior

completion/complete is supported for:
  • prompt argument completions (ref/prompt)
  • resource template argument completions (ref/resource)
{
  "jsonrpc": "2.0",
  "method": "completion/complete",
  "params": {
    "ref": { "type": "ref/prompt", "name": "summarize-release" },
    "argument": { "name": "audience", "value": "eng" }
  },
  "id": 31
}

​
Notifications emitted by Hyperterse

​
List-change notifications

When model content changes during reload, Hyperterse emits:
  • notifications/tools/list_changed (if tool digest changed)
  • notifications/prompts/list_changed
  • notifications/resources/list_changed (resources/templates list changes)

​
Resource update notifications

When concrete resource content changes for an existing URI during reload:
  • notifications/resources/updated is emitted for the changed URI.

​
Tool call observability notifications

During tools/call execution for search and execute:
  • notifications/progress is emitted (start/completion)
  • notifications/message is emitted with structured log payloads

​
Cancellation behavior

Cancellation from the client propagates through tool execution when connectors and scripts support it.

​
Session behavior and reload continuity

  • Streamable HTTP session IDs use Mcp-Session-Id.
  • DELETE /mcp terminates a session.
  • After a model reload, MCP stays on the same server process and keeps active sessions.
  • Sessions keep working and receive list or update notifications when tools, prompts, or resources change.

​
CORS and headers

Hyperterse sends CORS headers on /mcp responses, including:
  • Access-Control-Allow-Origin: *
  • Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
  • Access-Control-Allow-Headers: Content-Type, Authorization, X-API-Key, Mcp-Session-Id
  • Access-Control-Expose-Headers: Mcp-Session-Id

​
Example: two-tool flow

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": { "query": "orders by status" }
  },
  "id": 2
}

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "execute",
    "arguments": {
      "tool": "get-orders",
      "inputs": { "status": "pending" }
    }
  },
  "id": 3
}

​
Heartbeat

curl http://localhost:8080/heartbeat

{ "success": true }
Heartbeat shows the HTTP server is up, not that every database adapter is healthy.