Core API agent MCP

Engineering-only reference for MCP clients connecting to a HEAT cluster. The endpoint lives on Core API, not the versioned v2 public API.

Enablement

Platform key	Default	Purpose
`system.core.agent_mcp_enabled`	`false`	Master switch; `/api/mcp` returns 404 when false

Scope access (Off | Read | Write)

Key	Read tools	Write tools
`system.core.agent_mcp_projects_access`	`discover_projects`, `projects_list`, `project_get`	`project_create`, `project_update`
`system.core.agent_mcp_sessions_access`	`discover_session_templates`, `sessions_`, `session_`	`session_create`
`system.core.agent_mcp_templates_access`	`discover_node_templates`, `discovery_node_templates`, template lists/get	`session_template_create`
`system.core.agent_mcp_runners_access`	`runner_types_list`, `runner_tasks_list`	(none yet)

Session outputs (Off | Metadata | Data)

Key	Purpose
`system.core.agent_mcp_session_outputs_access`	`Metadata`: `node_output_summary` without blob fetch. `Data`: adds `node_output_data`.

Legacy boolean *_enabled keys map to Read (and outputs Metadata for sessions) when *_access is unset.

Hot reload: keys are read from Postgres on every MCP request; no Core API restart.

Endpoint

URL: GET/POST /api/mcp (Streamable HTTP)
Auth: system.core.auth_mode + Bearer when required
First tools: platform_status, then agent_mcp_capabilities

Always available (master on)

Group	Tools
Orientation	`platform_status` (recommended first), `platform_version`, `platform_health`, `platform_summary`, `platform_auth_context`
Policy	`agent_mcp_capabilities`
Fragments	`fragment_*`
Release discovery	`discovery_*` (release bundle sections)

Platform vs Cluster Manager

Core API MCP tools cover version, DB health, and operational counts (sessions, tasks, projects). They do not proxy Cluster Manager watchdog advisories.

When the MCP client uses an Administrator Bearer token on the same site origin, it may also call (HTTP, not MCP):

Endpoint	Purpose
`GET /api/environment/advisories`	Active environment advisories (security, performance, availability)
`GET /api/environment/metrics/service-latency`	Service probe latencies

platform_status includes these paths in externalEndpoints for agent discoverability.

Client example (LM Studio mcp.json)


{
  "mcpServers": {
    "heat": {
      "url": "https://your-site.example/api/mcp",
      "headers": { "Authorization": "Bearer <HEAT_API_TOKEN>" }
    }
  }
}

Control Center UI spec: references/lovable/cluster-manager/32-developer-tools-mcp.md
HTTP discovery: discovery.md
tools/agentic-cli