Skip to main content
Each app/tools/*/config.terse defines one MCP tool — its execution strategy, inputs, mappers, authentication, and caching behavior.

​
Full schema

app/tools/get-user-profile/config.terse
name: get-user-profile
description: 'Retrieve a user profile by primary key'
use: primary-db
statement: |
  SELECT id, name, email, created_at
  FROM users
  WHERE id = {{ inputs.user_id }}
inputs:
  user_id:
    type: int
    description: 'User primary key'
mappers:
  input: './validate-input.ts'
  output: './format-output.ts'
auth:
  plugin: api_key
  policy:
    value: '{{ env.API_KEY }}'
cache:
  enabled: true
  ttl: 120

​
Field reference

​
name
string
MCP tool name. Must be unique across all tools.Default: directory name (e.g., get-user from app/tools/get-user/).
​
description
string
Human-readable tool description. Exposed in the tools/list MCP response. Strongly recommended for agent discoverability.
​
use
string
Adapter name for statement execution. References an adapter identifier defined in app/adapters/.
use must be a single adapter name. Array values are rejected during validation.
Exactly one of use or handler must be set. A tool cannot define both.
​
statement
string
SQL query or database command. Supports {{ env.VAR }} and {{ inputs.field }} placeholders. Use YAML multiline syntax (|) for readability.
statement: |
  SELECT id, name, email
  FROM users
  WHERE id = {{ inputs.user_id }}
​
inputs
object
Map of input parameter definitions. Each key becomes a named parameter in the MCP tool’s input schema.
​
handler
string
Optional handler script path for fully script-backed tools. When set, it replaces database execution entirely. The handler receives inputs and returns results directly.Use path#exportName to call a non-default export. Without #exportName, Hyperterse calls the script’s export default (function name ignored).
​
mappers
object
Optional mapper script paths for pre/post processing. All paths are relative to the tool directory.
If mapper/handler scripts are omitted, convention-based discovery applies — see Scripts.
​
auth
object
Tool-level authentication. Omitting this block entirely makes the tool unauthenticated.
​
cache
object
Per-tool cache settings. Overrides the global cache configuration from .hyperterse.

​
Validity rules

A tool is valid when exactly one of these conditions is met:
  1. use is defined (database-backed tool).
  2. handler is defined (script-backed tool).
Tools with neither use nor handler — or with both — are rejected during validation.

​
Runtime mapping

  • Tool configs are compiled into project tool definitions at startup/reload.
  • Project tools are discoverable via MCP tools/call on search (ranked metadata results).
  • Project tools execute via MCP tools/call on execute with:
    • tool = resolved tool name
    • inputs = caller payload validated against inputs definitions
  • auth runs before execution and can reject requests.
  • mappers.input runs before statement/handler execution; mappers.output runs after.
  • handler tools run script-backed execution; use + statement tools run connector-backed execution.
  • cache settings map to runtime in-memory result caching policy.
  • Tool calls emit MCP progress and logging notifications during execution.
tools/list intentionally returns the transport entry tools (search, execute) as a core runtime design. Your configured project tools are discovered through search and invoked through execute.

​
JSON Schema

Editor validation: schema/tool.terse.schema.json. Associate with **/tools/**/config.terse. See Configuration schemas.