MCP Server
HSYCO exposes a Model Context Protocol (MCP) server for external AI clients. An MCP client can connect to HSYCO, list the available HSYCO tools, and request permission to use them through the Manager.
The MCP server is intended for administrators and developers who want to use an external AI client with live HSYCO context. For example, an MCP client can inspect runtime status, search HSYCO documentation, read or edit the project currently open in Manager, work with EVENTS files through Code Editor, or create downloadable files.
Endpoint
Configure the MCP client to use the HSYCO /mcp endpoint.
When HSYCO has a public or otherwise trusted HTTPS certificate:
https://<hsyco-host>:<https-port>/mcp
When HSYCO uses its default self-signed HTTPS certificate, most MCP clients will reject the connection unless the certificate is added to the client trust store or the client explicitly allows self-signed certificates.
For local or trusted-network use, configure the MCP client with the HTTP endpoint when HTTP is enabled:
http://<hsyco-host>:<http-port>/mcp
The endpoint uses the MCP Streamable HTTP transport. Use HTTPS with a trusted certificate when the client is not running on the same trusted host or trusted network.
Manager approval
Connecting to the MCP endpoint does not immediately grant access to HSYCO. The MCP client can initialize a session and list tools, but protected HSYCO tools require approval from an administrator in Manager.
When an MCP client calls a protected tool, HSYCO shows an MCP Connection Request popup in Manager. The Manager user can approve or reject the request.
After approval:
- the MCP session is connected to the approving Manager session;
- tools run with the access rights and context of that Manager administrator;
- the Manager toolbar shows the MCP status badge;
- Manager shows notices when MCP tools update files, open editor context, or report errors;
- clicking the MCP badge shows the current session state and a disconnect action.
If the request is rejected, closed, or not approved in time, the MCP client receives an approval error and must request access again.
Session lifetime
Only one MCP session can be approved at a time. If another MCP session is already connected, new requests are rejected until the current session is disconnected or expires.
Pending approval requests expire after a short time. Approved sessions use the client session timeout, with a default of 30 minutes.
Disconnect the MCP session from the Manager toolbar when the external client no longer needs access.
Tool bundles
MCP clients can limit the exposed HSYCO tools by setting toolBundles during MCP initialization. If no bundle is specified, all shared HSYCO tool bundles are available after Manager approval.
Available bundles are:
| Bundle | Description |
|---|---|
docs | Search HSYCO documentation, object references, code references, and icons. |
runtime_status | Read host and device status. |
runtime_config | Read configuration and server definitions. |
runtime_sessions | List active user sessions. |
runtime_state | Query live variables, I/O, UI state, datasources, and indexed state. |
runtime_history | Read timelines, logs, and datalogger data. |
runtime_media | Read images and camera data. |
runtime_execution | Run sandboxed JavaScript for data analysis. |
runtime_control | Set live variable, I/O, and UI values. |
runtime_events | Inspect EVENTS errors. |
runtime_files | Read and search saved text files. Configuration files also require runtime_config. |
runtime_source | Inspect EVENTS and Java source. |
catalog | Read and search the HSYCO catalog. |
editor_project | Inspect and edit the project currently open in Manager Project Editor. |
editor_code | Read, edit, and control Manager Code Editor tabs. |
session_files | Create downloadable files and read uploaded files associated with the AI session. |
client_page | Inspect limited live context from a connected HSYCO client page. |
The approval tools are always available:
| Tool | Description |
|---|---|
hsyco_approval_request | Opens a Manager approval popup for the current MCP session. |
hsyco_approval_status | Returns the current approval status for the MCP session. |
Protected HSYCO tools request Manager approval automatically if the session has not already been approved.
See Assistant Tools for the full list of shared tool names.
Security
Only approve MCP requests from clients you trust. An approved MCP session can use the enabled tool bundles with the approving Manager administrator's access rights.
Pay particular attention to sessions that enable editor_project, editor_code, or runtime_control, because they can modify live HSYCO configuration or runtime state.
Use HTTPS or a trusted local network for MCP client connections, and disconnect the session when the external client no longer needs access.