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 all registered tools with their input schemas. Request: 
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}
Response: 
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get-user",
        "description": "Retrieve a user by their identifier",
        "inputSchema": {
          "type": "object",
          "properties": {
            "user_id": {
              "type": "integer",
              "description": "Primary key of the user record"
            }
          },
          "required": ["user_id"]
        }
      }
    ]
  }
}

​
Schema generation

Input schemas are generated from the tool’s inputs block:
.terse typeJSON Schema type
string"string"
int"integer"
float"number"
boolean"boolean"
datetime"string"
Required inputs (non-optional, no default) appear in the required array.

​
tools/call

Executes a tool with the provided arguments. Request: 
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get-user",
    "arguments": {
      "user_id": 42
    }
  },
  "id": 2
}
Successful response: 
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "[{\"id\":42,\"name\":\"Jane Doe\",\"email\":\"jane@example.com\"}]"
      }
    ]
  }
}
The content array 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 as JSON-RPC error objects. 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.