Skip to main content
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.
Execution pipeline: tool resolution, auth, input transform, execution, output transform, response

Every tool invocation passes through the same deterministic pipeline

​
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:
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:
  1. Input validation — validate all declared inputs against type definitions. Missing required inputs and type mismatches produce errors.
  2. Environment substitution — resolve {{ env.VAR }} placeholders. Missing variables produce errors.
  3. Input substitution — replace {{ inputs.field }} placeholders with post-transform values. Substitution is textual.
  4. Cache check — if caching is enabled, compute the cache key from tool name + statement hash. On hit, return cached result and skip connector execution.
  5. Connector execution — run the statement against the configured connector and return row/object results.
  6. 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:
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:

​
Error propagation

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.