Hyperterse — Agentic server framework.

Every tools/call request passes through a deterministic pipeline. The stages are identical for DB-backed and script-backed tools — only the execution step differs. If any stage fails, execution halts immediately and an error response is returned.

Tool resolution

Hyperterse matches the tool name from tools/call to the tool definition it loaded for that server run. If no tool matches, a JSON-RPC error is returned with code -32601.

Authentication

If the tool defines an auth block, the configured plugin is invoked with the request context and policy parameters.

Plugin returns nil: authentication passes; the request continues.
Plugin returns an error: the request stops; the error goes back to the caller.
No auth block: stage is skipped entirely.

Input transform

If mappers.input is configured or discovered by convention, the mapper script’s export default function executes in the embedded runtime. Payload:

{
  "inputs": { "user_id": 42 },
  "tool": "get-user"
}

The returned object replaces the inputs for all subsequent stages. Throwing an error stops processing. If no input transform is configured, inputs pass through unchanged.

Execution

The execution stage branches based on the tool’s configuration. Only one path runs per invocation.

Script-backed tools

When handler is configured, the handler script’s export default function executes in the embedded runtime. The return value becomes the execution result.

DB-backed tools

When use and statement are configured, the executor runs six substeps:

Input validation — validate all declared inputs against type definitions. Missing required inputs and type mismatches produce errors.
Environment substitution — resolve {{ env.VAR }} placeholders. Missing variables produce errors.
Input substitution — replace {{ inputs.field }} placeholders with post-transform values. Substitution is textual.
Cache check — if caching is enabled, compute the cache key from tool name + statement hash. On hit, return cached result and skip connector execution.
Connector execution — run the statement against the configured connector and return row/object results.
Cache store — on miss, store the result with the configured TTL.

Output transform

If mappers.output is configured or discovered by convention, the mapper script’s export default function executes in the embedded runtime. Payload:

{
  "results": [{ "id": 42, "name": "Jane Doe", "email": "jane@example.com" }],
  "tool": "get-user"
}

The returned value replaces the result for response serialization. Throwing an error stops processing. If no output transform is configured, the raw result is used directly.

Response serialization

The final result is JSON-encoded and wrapped in an MCP content block:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"id\":42,\"name\":\"Jane Doe\",\"email\":\"jane@example.com\"}]"
    }
  ]
}

Error propagation

Stage	Error condition	JSON-RPC code
Tool resolution	Tool name not found	`-32601`
Authentication	Plugin returns error	`-32000`
Input transform	Script throws	`-32000`
Input validation	Missing input or type mismatch	`-32000`
Env substitution	Missing variable	`-32000`
Connector execution	Query error	`-32000`
Handler execution	Script throws	`-32000`
Output transform	Script throws	`-32000`

Error messages from scripts and connectors are included in the response. Stack traces are logged at debug level but not exposed to callers.

Observability hooks

Each pipeline execution is instrumented with OpenTelemetry spans when tracing is enabled. Span attributes include tool name, execution stage, cache hit/miss, connector type, and duration. Sensitive values are redacted. See Observability.

Documentation Index

​Tool resolution

​Authentication

​Input transform

​Execution

​Script-backed tools

​DB-backed tools

​Output transform

​Response serialization

​Error propagation

​Observability hooks