Hyperterse

What is Hyperterse?

Hyperterse is an open-source framework for building MCP (Model Context Protocol) tool servers from declarative configuration. Instead of exposing many individual MCP tool endpoints, it compiles your tool definitions into a standards-compliant MCP server that agents use through a consistent interface.

The framework’s core purpose is to let you “define tools once” (including database connections and authentication rules) and have Hyperterse handle the runtime concerns—such as auth enforcement, result caching, and observability—without requiring you to write and maintain glue code for each tool endpoint.

Key Features

• Declarative tool definitions from directories and declaration files: Each directory under app/tools/ becomes a tool automatically, so you don’t write registration code for each tool.
• Two-tool MCP interface (search + execute): Agents interact with a server that exposes exactly two MCP tools—search and execute—while Hyperterse discovers and routes to the correct underlying tool implementation dynamically.
• Built-in authentication via api_key plugin: Attach authentication to tools with the built-in api_key plugin (or implement your own), with auth enforced automatically before each execute call.
• Caching with global or per-tool TTL: Enable result caching so identical execute calls can return cached results instead of hitting your database; caching rules can be set globally or per tool.
• Multi-database support with managed pooling and lifecycle: Connect PostgreSQL, MySQL, MongoDB, and Redis using adapters; Hyperterse manages connection pooling, health checks, and graceful shutdown.
• Observability using OpenTelemetry: Hyperterse includes OpenTelemetry tracing, metrics, and structured logging to debug end-to-end search and execute calls.
• TypeScript scripts for handlers and transforms: When declaration files alone aren’t enough, add handlers/transforms as scripts that run in a sandboxed runtime with fetch and console.
• Compile & deploy as a single artifact: Hyperterse compiles declaration files and scripts into one artifact that can be served on Docker, Kubernetes, bare metal, or any cloud environment.

How to Use Hyperterse

1. Install Hyperterse using one of the provided commands (cURL, NPM, Bun, or Homebrew).
2. Create your tool and adapter definitions:
   • Put database adapters under app/adapters/.
   • Put tool declarations under app/tools/, where each tool is represented by its directory name and includes a declaration file containing a SQL statement, typed inputs, and optional auth and caching rules.
3. (Optional) Add TypeScript handlers/transforms when you need logic beyond what declaration files support.
4. Build/compile your server artifact so your tools, scripts, and configuration are bundled together.
5. Serve the compiled MCP server in your target environment; agents then use search to find tools and execute to run the selected tool with structured inputs.

Use Cases

• Database-backed research or analytics tools: Define many SQL-based tools in app/tools/ and let an agent use search to find the right query tool and execute to run it with typed inputs.
• Multi-tenant or access-controlled tool execution: Attach API key authentication rules to specific tools so auth runs automatically before each execute call.
• Cost or latency-sensitive query workflows: Enable global or per-tool caching with a TTL so repeated execute calls can return cached results rather than re-querying the database.
• Teams standardizing MCP server behavior: Use Hyperterse’s built-in auth, caching, and OpenTelemetry tracing to keep different tool servers consistent without maintaining separate boilerplate for each tool endpoint.
• Production deployments across infrastructure types: Compile to a single artifact and deploy it to Docker, Kubernetes, bare metal, or cloud environments without changing the tool definition approach.

FAQ

• What is Hyperterse built for? Hyperterse is for building MCP tool servers from declaration files, compiling and serving them with built-in support for auth, caching, and observability.

• Is Hyperterse free to use? Yes. It is free and open source under the Apache 2.0 license, and it can be self-hosted.

• How do declaration files map to tools? Tools are defined under app/tools/; each tool directory corresponds to a tool name, and the directory’s declaration file specifies a SQL statement, typed inputs, and optional auth/caching rules.

• Which databases are supported? Hyperterse supports PostgreSQL, MySQL, MongoDB, and Redis out of the box, using dedicated adapters.

• What MCP interface does Hyperterse expose to agents? Hyperterse exposes exactly two MCP tools—search and execute—regardless of how many tool definitions you include.

Alternatives

• Custom MCP tool servers with explicit endpoints: Build an MCP server that exposes one tool endpoint per capability. This can offer fine-grained control, but typically requires writing and maintaining more registration, validation, auth, caching, and observability code.
• Frameworks that focus on routing/discovery rather than compilation: Use an approach where an agent or router maps requests to backend functions/tools. Compared to Hyperterse, you may still need to implement validation, auth, caching, and tracing consistently.
• Database-only tool libraries with application-managed middleware: Use typed database access libraries and implement middleware for auth, caching, and tracing in your app layer. This shifts responsibilities away from an MCP framework and can increase integration effort per tool.
• General-purpose workflow engines for tool execution: Orchestrators that run tasks based on configurations. These alternatives may support tool chaining, but Hyperterse is specifically oriented around MCP server behavior and declarative tool compilation into a standards-compliant interface.