> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperterse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP transport

> Full MCP 2025-11-25 surface in Hyperterse, including tools, prompts, resources, completion, notifications, and session behavior.

Hyperterse is a full MCP server for tools, prompts, and resources. Discovery and execution use Streamable HTTP and JSON-RPC 2.0 on `/mcp`. There are no separate REST endpoints per tool, no GraphQL layer, and no custom tool protocol beyond MCP.

Hyperterse serves MCP over Streamable HTTP (`/mcp`) using JSON-RPC 2.0. It supports:

* two-tool entrypoints (`search`, `execute`)
* first-class prompts
* first-class resources and URI templates
* argument completion
* resource subscriptions
* progress and logging notifications
* session continuity across model reloads

<Tip>
  Declarative agents use A2A on `/agent/{agentName}`—separate from MCP.
  See [A2A transport](/runtime/a2a-transport); method details in [Runtime
  API](/agents/runtime-api).
</Tip>

## Endpoints

| Endpoint     | Methods                 | Purpose                                             |
| ------------ | ----------------------- | --------------------------------------------------- |
| `/mcp`       | `GET`, `POST`, `DELETE` | MCP Streamable HTTP transport and session lifecycle |
| `/heartbeat` | `GET`                   | Liveness endpoint (`{"success": true}`)             |

## Protocol version

Hyperterse implements MCP `2025-11-25`.

## Capability surface

Hyperterse capability exposure includes:

* `tools` (`listChanged`)
* `prompts` (`listChanged`) when prompt definitions exist
* `resources` (`listChanged`, `subscribe`) when resources/templates are configured
* `completions`
* `logging`

## MCP method support

| Method                             | Direction        | Notes                                                |
| ---------------------------------- | ---------------- | ---------------------------------------------------- |
| `initialize`                       | client -> server | Standard MCP handshake                               |
| `notifications/initialized`        | client -> server | Standard MCP post-init notification                  |
| `ping`                             | client -> server | Supported                                            |
| `tools/list`                       | client -> server | Returns transport entry tools (`search`, `execute`)  |
| `tools/call`                       | client -> server | Calls `search` or `execute`                          |
| `prompts/list`                     | client -> server | Lists configured prompts                             |
| `prompts/get`                      | client -> server | Resolves prompt messages with argument interpolation |
| `resources/list`                   | client -> server | Lists concrete resources                             |
| `resources/templates/list`         | client -> server | Lists URI template resources                         |
| `resources/read`                   | client -> server | Reads concrete or template-resolved content          |
| `resources/subscribe`              | client -> server | Validates subscription target and enables updates    |
| `resources/unsubscribe`            | client -> server | Unsubscribes from resource updates                   |
| `completion/complete`              | client -> server | Provides completions for prompt/template arguments   |
| `notifications/progress`           | client -> server | Supported (logged)                                   |
| `notifications/roots/list_changed` | client -> server | Supported (logged)                                   |
| `notifications/cancelled`          | client -> server | Supported (MCP cancellation)                         |

## Tool entrypoint design

`tools/list` intentionally exposes exactly two transport entry tools:

* `search` — discover project tools by natural language over tool metadata
* `execute` — execute a project tool by name with validated inputs

This is a core Hyperterse design choice: project tools are discovered and invoked through these two entrypoints.

### Search result limit

```yaml .hyperterse theme={null}
tools:
  search:
    limit: 10
```

If omitted, default is `10`.

## Prompt behavior

Prompts come from:

* prompt definitions discovered in your project (see [Project structure](/concepts/project-structure)), unless you override the directory in `.hyperterse`
* inline `prompts` in root config

`prompts/get` interpolates `{{ argumentName }}` placeholders from request arguments.

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "prompts/get",
  "params": {
    "name": "summarize-release",
    "arguments": { "audience": "engineering", "tone": "concise" }
  },
  "id": 11
}
```

## Resource behavior

Resources come from:

* resource definitions discovered in your project (see [Project structure](/concepts/project-structure)), unless you override the directory in `.hyperterse`
* inline `resources` and `resource_templates` in root config

`resources/read` resolves:

* concrete `uri` resources (`text` or `file`)
* `uri_template` resources (`text_template` or `file_template`) using URI path values

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "params": { "uri": "memory://orders/1001" },
  "id": 21
}
```

## Completion behavior

`completion/complete` is supported for:

* prompt argument completions (`ref/prompt`)
* resource template argument completions (`ref/resource`)

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "completion/complete",
  "params": {
    "ref": { "type": "ref/prompt", "name": "summarize-release" },
    "argument": { "name": "audience", "value": "eng" }
  },
  "id": 31
}
```

## Notifications emitted by Hyperterse

### List-change notifications

When model content changes during reload, Hyperterse emits:

* `notifications/tools/list_changed` (if tool digest changed)
* `notifications/prompts/list_changed`
* `notifications/resources/list_changed` (resources/templates list changes)

### Resource update notifications

When concrete resource content changes for an existing URI during reload:

* `notifications/resources/updated` is emitted for the changed URI.

### Tool call observability notifications

During `tools/call` execution for `search` and `execute`:

* `notifications/progress` is emitted (start/completion)
* `notifications/message` is emitted with structured log payloads

## Cancellation behavior

Cancellation from the client propagates through tool execution when connectors and scripts support it.

## Session behavior and reload continuity

* Streamable HTTP session IDs use `Mcp-Session-Id`.
* `DELETE /mcp` terminates a session.
* After a model reload, MCP stays on the same server process and keeps active sessions.
* Sessions keep working and receive list or update notifications when tools, prompts, or resources change.

## CORS and headers

Hyperterse sends CORS headers on `/mcp` responses, including:

* `Access-Control-Allow-Origin: *`
* `Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS`
* `Access-Control-Allow-Headers: Content-Type, Authorization, X-API-Key, Mcp-Session-Id`
* `Access-Control-Expose-Headers: Mcp-Session-Id`

## Example: two-tool flow

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}
```

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search",
    "arguments": { "query": "orders by status" }
  },
  "id": 2
}
```

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

## Heartbeat

```bash theme={null}
curl http://localhost:8080/heartbeat
```

```json theme={null}
{ "success": true }
```

Heartbeat shows the HTTP server is up, not that every database adapter is healthy.

## Related docs

* [A2A transport](/runtime/a2a-transport) — Agent HTTP on `/agent/{agentName}`
* [Prompts](/concepts/prompts)
* [Resources](/concepts/resources)
* [Prompt configuration](/reference/prompt-config)
* [Resource configuration](/reference/resource-config)
* [Root configuration](/reference/root-config)
* [Configuration schemas](/reference/configuration-schemas)