Skip to main content
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

​
Endpoints

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

​
Protocol version

The runtime uses MCP 2025-11-25 protocol types through the Go MCP SDK.

​
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 by SDK
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 -> serverAccepted and logged by runtime
notifications/roots/list_changedclient -> serverAccepted and logged by runtime
notifications/cancelledclient -> serverHandled by SDK cancellation flow

​
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:
  • discovered files under app/prompts/**/*.terse (or configured directory)
  • inline root config prompts array
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:
  • discovered files under app/resources/**/config.terse (or configured directory)
  • inline root config resources and resource_templates
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

Hyperterse runs tool execution with request context propagation. MCP cancellation and transport-level context cancellation are propagated through the execution path where connectors/scripts support context-aware operations.

​
Session behavior and reload continuity

  • Streamable HTTP session IDs use Mcp-Session-Id.
  • DELETE /mcp terminates a session.
  • Runtime reload updates the existing MCP adapter in place (does not replace the server instance), preserving active sessions.
  • Existing sessions continue to function after reload and receive list/update notifications for changed MCP entities.

​
CORS and headers

The runtime applies 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 indicates HTTP runtime liveness, not downstream adapter health.