Skip to main content
Hyperterse is an MCP server. All tool interaction — discovery and execution — goes through a single endpoint using the MCP Streamable HTTP transport over JSON-RPC 2.0. There are no per-tool REST endpoints, no GraphQL layer, and no custom protocol. The transport is the protocol, and the protocol is MCP.

​
Endpoints

EndpointMethodsPurpose
/mcpGET, POST, DELETEMCP Streamable HTTP. Handles tools/list, tools/call, and session lifecycle.
/heartbeatGETReturns {"success": true} when the server is accepting connections.

​
tools/list

Returns exactly two tools:
  • search: discovers relevant tools using ranked metadata matching (name, description, statement, and input metadata).
  • execute: executes a selected tool by name with a structured input payload.
Request: 
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}
Response: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "search",
        "description": "Search available tools by natural-language intent and tool metadata.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Natural-language query used to find relevant tools."
            }
          },
          "required": ["query"]
        }
      },
      {
        "name": "execute",
        "description": "Execute a tool by name using a structured input object.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "tool": {
              "type": "string",
              "description": "Name of the target tool to execute."
            },
            "inputs": {
              "type": "object",
              "description": "Structured inputs for the target tool."
            }
          },
          "required": ["tool", "inputs"]
        }
      }
    ]
  }
}

​
Search result limit

search does not accept a caller-provided limit. Result count is controlled by root config:
.hyperterse
tools:
  search:
    limit: 10
If omitted, the runtime default is 10.

​
tools/call

Typical flow:
  1. Call search with a natural-language query.
  2. Pick a returned tool name.
  3. Call execute with tool + inputs.

​
search request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": {
      "query": "find orders by status"
    }
  },
  "id": 2
}

​
search successful response

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"name\":\"get-orders\",\"relevance_score\":97,\"description\":\"Returns orders by status\",\"statement\":\"SELECT * FROM orders WHERE status = {{ inputs.status }}\",\"inputs\":[{\"name\":\"status\",\"type\":\"string\",\"optional\":false,\"description\":\"order status\"}]}]"
      }
    ]
  }
}
Each search hit includes:
  • name
  • relevance_score (integer 1..100, higher = more relevant)
  • description
  • statement
  • inputs

​
execute request

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "execute",
    "arguments": {
      "tool": "get-orders",
      "inputs": {
        "status": "pending"
      }
    }
  },
  "id": 3
}

​
execute successful response

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"status\":\"pending\",\"statement\":\"SELECT * FROM orders WHERE status = pending\"}]"
      }
    ]
  }
}
The content array always contains one text entry with JSON-encoded tool results. Error response: 
{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32000,
    "message": "execution failed: user_id must be a positive integer"
  }
}
Errors from auth failures, input validation, connector execution, and script exceptions are returned through MCP tool error payloads. Stack traces are logged but not exposed.

​
Heartbeat

curl http://localhost:8080/heartbeat

{ "success": true }
The heartbeat bypasses the MCP handler and auth pipeline. It returns 200 OK when the HTTP server is accepting connections, regardless of connector health.

​
CORS

The runtime applies CORS headers to all responses:
  • Origins: * (all)
  • Methods: GET, POST, DELETE, OPTIONS
  • Headers: Content-Type, Authorization, X-API-Key, Mcp-Session-Id
Preflight (OPTIONS) requests are handled automatically. For production deployments behind a reverse proxy, configure CORS at the proxy layer and restrict the built-in policy to your domain.

​
HTTP headers in the execution context

HTTP request headers from tools/call requests are forwarded into the execution pipeline so auth plugins can evaluate authentication data (X-API-Key, Authorization, and custom headers) when making access decisions.

​
Session management

The MCP Streamable HTTP transport supports session-based interaction via the Mcp-Session-Id header. DELETE /mcp terminates a session. For stateless tool invocation — the common case — sessions are not required. Each POST /mcp with a tools/call method is independently executed.