MCP API Reference

Hantera implements the Model Context Protocol over Streamable HTTP and JSON-RPC 2.0. The server exposes permission-gated resources, built-in system_* tools, and tools backed by MCP ingresses.

For connecting a client and completing OAuth authorization, see Model Context Protocol.

Endpoint

POST /mcp

All JSON-RPC requests, responses, and notifications use this one endpoint. Responses are returned directly in the HTTP response body; this implementation does not use an SSE response stream.

Request header	Value	When required
Content-Type	application/json	Every request
Accept	application/json	Every request
Authorization	Bearer {access-token}	Every authenticated request
Mcp-Session-Id	Session ID	Legacy protocol requests after initialize
MCP-Protocol-Version	Modern protocol version	When used, must match the request metadata

An unauthenticated request receives an OAuth protected-resource challenge. Clients should use the published metadata and OAuth flow rather than manually constructing access tokens.

JSON-RPC

Requests use JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Successful responses contain result; protocol failures contain a JSON-RPC error object. Component or business failures from tools/call are normally result-level tool errors with isError: true, not JSON-RPC transport failures.

Protocol versions and sessions

Hantera supports both MCP protocol eras on /mcp:

	Legacy protocols	Modern protocol
Supported versions	2025-03-26, 2025-06-18, 2025-11-25	2026-07-28
Handshake	initialize, followed by notifications/initialized	No handshake
Session	Server returns Mcp-Session-Id; send it on later requests	Stateless requests
Version selection	initialize.params.protocolVersion	_meta.io.modelcontextprotocol/protocolVersion
Server identity	initialize result	Result metadata

Use server/discover to learn the supported protocol versions, server identity, and capabilities. Modern requests include the protocol version in _meta; when MCP-Protocol-Version is also sent, it must agree with that value.

Modern discovery and list responses are private to the authenticated session and should not be shared across users or authorization contexts.

Capabilities and methods

The server advertises only capabilities that have registered providers and that the session can access.

Capability	Methods	Purpose
Resources	resources/list, resources/templates/list, resources/read	Discover and read live platform reference, help material, and tenant resources allowed by the session.
Tools	tools/list, tools/call	Discover and invoke built-in tools and active, authorized MCP ingress tools.

General developer guides, examples, and app-authoring documentation are available directly from the developer portal, not through MCP resources. Registry entries are read using built-in tools; installed-app metadata includes the app's egress IDs, but egresses do not have a separate MCP resource provider.

tools/list

Lists tools visible to the current session. An MCP ingress appears only when all of the following are true:

• it is active and targets a compiled Reactor component;
• its input and result shapes can be represented as an MCP contract;
• its generated name does not collide with another active MCP ingress;
• the session has mcp/tools/ingress/{ingressId}:call or a broader grant such as mcp/tools/ingress:call or mcp/tools:call.

Tools that fail one of these conditions are hidden rather than returned as forbidden.

tools/call

Invokes a tool using its generated name and a JSON object of arguments:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "apps_hello_mcp_hello",
    "arguments": {}
  }
}

Ingress-tool output includes structured content and a text fallback. Invalid argument names or types result in JSON-RPC invalid-parameter errors. Component evaluation and business failures are returned as tool results with isError: true.

See MCP ingresses for the generated-name rules, authorization, execution authority, and component schema requirements.

Tool namespaces

Hantera owns the system_ namespace for built-in, read-only tools. Their visibility is gated by MCP permissions; some tools also enforce backing platform permissions, while fixed report data products use their tool gates. See the built-in tools reference for the catalog and permission details.

Ingress tools have separate deterministic namespaces:

• app ingress: apps_<appId>_<ingressId> after sanitization;
• tenant-managed ingress: tool_<ingressId> after sanitization.

Ingresses cannot use the reserved system_ prefix.

Authentication and permission behavior

MCP uses Hantera OAuth 2.1 protected-resource metadata, Dynamic Client Registration, and Client ID Metadata Documents. Generic clients authorizing against /mcp without explicitly requested scopes receive the default MCP scope bundle, including mcp/tools:call for tools. The final session still intersects that bundle with the client's registered scopes and the user's effective permissions.

Resources and tools that the caller cannot access are deliberately hidden. A call to an unauthorized tool is indistinguishable from a call to an unknown tool.

Related

• Model Context Protocol — connection, OAuth, scopes, and troubleshooting.
• Built-in MCP tools — tool catalog and permissions.
• MCP ingresses — define tenant and app tools.
• Authentication — general Hantera OAuth flows.