Model Context Protocol

Hantera exposes a Model Context Protocol (MCP) server so AI clients and developer tools can discover selected Hantera capabilities through one authenticated connection. Connect a compatible client, such as an IDE assistant or MCP Inspector, to:

https://{hostname}/mcp

Replace {hostname} with your tenant hostname, for example tenant.core.ams.hantera.cloud.

What the MCP server exposes

The single /mcp endpoint can expose two kinds of capability:

• Resources — permission-gated live platform reference, help material, and tenant resources such as installed apps, components, rules, and ingresses.
• Tools — built-in, read-only system_* tools and MCP tools explicitly exposed through MCP ingresses.

MCP ingresses let a tenant expose specific Reactor components to an agent without giving it arbitrary access to the Graph API. An ingress is the tool's contract: it selects the component, defines its input and output schema, controls its execution authority, and determines who can discover and call it.

General developer documentation is read directly from the developer portal, not served through MCP. MCP supplies deployment-specific reference such as the live Graph schema, commands, messages, and runtime types. Registry entries are available through built-in tools; installed-app metadata lists associated egress IDs, but there is no separate egress resource provider.

Connect a client

Modern MCP clients authenticate through Hantera OAuth 2.1. Point the client at the tenant's /mcp URL and follow its browser sign-in flow. Clients can identify themselves with Dynamic Client Registration or a Client ID Metadata Document; Hantera handles the protocol discovery and registration flow.

The authorizing user needs permission to authorize dynamically registered clients. After sign-in, the client receives tokens scoped to the /mcp protected resource and can discover the capabilities available to that user.

For a client configuration that accepts a remote MCP URL, use:

{
  "mcpServers": {
    "hantera": {
      "url": "https://tenant.core.ams.hantera.cloud/mcp"
    }
  }
}

The client performs OAuth discovery and opens the browser when it first connects. Do not put a long-lived access token in source control or in a client configuration.

Authorization and scopes

Hantera applies normal access-control rules to MCP. Generic MCP clients that authorize against /mcp without requesting explicit scopes receive the default MCP scope bundle. It includes MCP resource gates, backing permissions, and mcp/tools:call for tool discovery and invocation.

mcp/tools/ingress:call grants access to all ingress-defined tools. A tenant can instead grant a specific tool only:

mcp/tools/ingress/apps/hello-mcp/hello:call

The effective session is still limited by both the client scopes and the authorizing user's roles and ACL. A client or user without the relevant permission does not learn that the protected capability exists.

WARNING

Changing a role, client scope, or default scope policy does not change an already issued token. Disconnect or re-authorize the MCP client after an authorization change.

Discovery is intentionally hidden

MCP follows Hantera's permission-hiding model:

• Unauthorized resources and tools are omitted from discovery.
• An unauthorized tools/call is reported as an unknown tool.
• A tool that is invalid, inactive, or involved in a name collision is also omitted.

This behavior prevents capability names and resource configuration from being disclosed to callers who are not allowed to use them.

Troubleshoot a missing MCP tool

If an expected tool is absent from tools/list, check the following in order:

1. Reconnect after authorization changes. The token must include mcp/tools/ingress:call, mcp/tools:call, or the exact mcp/tools/ingress/{id}:call permission.
2. Verify that the ingress is active. Its Reactor component must compile and its parameters and result must be representable as an MCP tool contract.
3. Check the tool name. App and tenant-managed ingresses use generated names, not a configurable name.
4. Check for collisions. Conflicting active ingress tools are all hidden and produce warning signals at ingresses/{id}/tool.

See MCP ingresses for tool authoring and the MCP API reference for the protocol contract.

Next steps

• MCP ingresses — expose a Reactor component as an MCP tool.
• MCP API reference — Streamable HTTP, JSON-RPC, protocol versions, and capabilities.
• Built-in MCP tools — available system tools and their permissions.
• Authentication — Hantera OAuth flows and token lifecycle.
• Access Control — ACEs, roles, and hierarchical permissions.