Search docs.molo17.com

    Core Hub MCP server

    The Core Hub MCP server is an embedded Model Context Protocol server that exposes pipeline management, debugging, observability, and SQL querying tasks as tools an AI agent can call directly against Core Hub, without a separate process or a hosted proxy.

    How-to guide

    For a step-by-step walkthrough tested on a running Gluesync, see the how-to guide Automate Gluesync with the REST API, MCP and webhooks.

    Overview

    The corehub-mcp module runs inside the Core Hub JVM and mounts MCP transports alongside the existing REST and WebSocket routes. It ships 149 built-in tools covering pipelines, agents, entities, connections, sync commands, snapshot speed tests, notifications and system conditions, metrics, Core Hub webhooks, email notifications, mapping functions, Chronos schedules and trigger flows, Query Studio (including PII classify and saved queries), the Validator, published AI agents and the Enterprise brain, documentation search, groups, global configuration, license/version information, pipeline export, support log upload and backups.

    Availability

    The Core Hub MCP server ships with Core Hub 2.2.10.0 and later, enabled by default. GLUESYNC_MCP_ALLOWED_HOSTS and GLUESYNC_MCP_ALLOWED_ORIGINS are available from Core Hub 2.3.1.1; from 2.3.1.4, leaving GLUESYNC_MCP_ALLOWED_HOSTS empty accepts any hostname (see DNS-rebinding protection).

    The MCP server has zero elevated privileges of its own. It extracts the bearer token from the incoming MCP request and forwards it to a loopback REST call, so RBAC, license, and audit checks all continue to run inside Core Hub exactly as they do for the Web UI. If a user cannot delete a pipeline via the UI, the MCP tool won’t let them either.

    Architecture

    MCP client (Claude Code,             Gluesync Core Hub JVM
    Claude Desktop, MCP
    Inspector, ...)
            |                             +-------------------------+
            |  HTTPS + Bearer token       | Ktor routing            |
            +----------------------------->  /pipelines, ... (REST) |
                                          |  /mcp        (SSE)      |
                                          |  /mcp/http   (Streamable|
                                          |               HTTP)     |
                                          +------------+------------+
                                                       |
                                          +------------v------------+
                                          | corehub-mcp module       |
                                          |  - 149 built-in tools     |
                                          |  - LoopbackCoreHubClient  |
                                          +------------+------------+
                                                       | localhost
                                          +------------v------------+
                                          | Core Hub REST API        |
                                          | (owns RBAC, license,     |
                                          |  storage, audit)         |
                                          +---------------------------+

    Key features

    • Embedded, zero-footprint deployment

      • Runs inside the same Core Hub JVM process, no additional container or proxy to operate

      • Enabled by default; a single environment variable can disable it entirely

    • Two standard MCP transports

      • Server-Sent Events (SSE) at /mcp, mounted inside Core Hub’s authenticated routing block

      • Streamable HTTP at /mcp/http, the modern single-endpoint transport preferred by newer clients, protected by Core Hub’s global JWT filter

    • RBAC-safe by design

      • Every tool call uses the caller’s own bearer token. By default (when GLUESYNC_MCP_IN_PROCESS is false), Core Hub forwards the call via the loopback HTTP client; the optional in-process client is a dev-only opt-in, not the production default

      • No tool can perform an action the calling user’s role would not otherwise permit

    • Broad tool coverage across the platform (149 built-in tools)

      • Pipelines, agents, entities, connections, sync commands, notifications, metrics, Core Hub webhooks, email notifications, mapping functions, Chronos, Query Studio, published AI agents and the Enterprise brain, documentation search, groups, global configuration, license/version info, and pipeline export

      • See Built-in tool catalog below for the full breakdown

    • Dynamic database tools via Query Studio

      • At session open, the server discovers the SQL-capable agents visible to the caller’s token and registers their Query Studio tools as namespaced MCP tools (db_<pipelineId>_<agentId>_<toolName>)

      • Lets an MCP client query the databases behind Core Hub directly, still scoped by the caller’s own permissions

    • Read-only and allow-list controls

      • Read-only deployments can hide every tool marked WRITE (sync_command, delete pipeline, upsert entities, enter maintenance mode, etc.)

      • An explicit allow-list can further restrict which tools are exposed

    Configuration

    The module is controlled entirely through environment variables read by Core Hub at startup; no separate configuration file is required.

    Variable Default Effect

    GLUESYNC_MCP_ENABLED

    true

    Master switch. Set to false to skip mounting the /mcp* routes entirely.

    GLUESYNC_MCP_BASE_PATH

    /mcp

    Path prefix. The SSE transport is mounted at this exact path, the streamable-HTTP transport at ${basePath}/http.

    GLUESYNC_MCP_READ_ONLY

    false

    When true, every tool marked WRITE (sync_command, delete pipeline, upsert entities, enter maintenance, etc.) is hidden from the tool list.

    GLUESYNC_MCP_DYNAMIC_DB_TOOLS

    true

    When true, each MCP session dynamically discovers and registers the per-agent Query Studio tools visible to the caller’s bearer token. Set to false to disable dynamic database tool discovery.

    GLUESYNC_MCP_IN_PROCESS

    false

    When true, tool calls use an in-process Core Hub client instead of the self-HTTP loopback client. Dev-only opt-in; not the production default. Production continues to forward calls with the caller’s bearer token via the loopback HTTP client.

    GLUESYNC_MCP_ALLOWED_HOSTS

    empty (any hostname)

    Available from Core Hub 2.3.1.1. Comma-separated hostnames, besides localhost, 127.0.0.1 and [::1], that MCP clients may use in the Host header. When empty, Core Hub 2.3.1.4 and later accept any hostname and check only the browser Origin; 2.3.1.1 to 2.3.1.3 accepted only the localhost names. Setting it restricts the endpoint to the listed hostnames, for example gluesync.corp.example.com,gluesync-int.example.com. Matching ignores case and port: host:port is accepted and the port is dropped. Write IPv6 addresses in brackets ([fd00::10]). Wildcards are not supported; list each hostname. An invalid entry (a URL with a scheme, a path, @, *) is skipped with a warning in the Core Hub log and never stops Core Hub from starting. See Running behind a reverse proxy or on a custom hostname.

    GLUESYNC_MCP_ALLOWED_ORIGINS

    empty (derived)

    Available from Core Hub 2.3.1.1. Comma-separated browser origins, such as https://ai.corp.example.com, accepted in the Origin header besides the localhost origins. When empty, Core Hub accepts https://<host>; for every entry of GLUESYNC_MCP_ALLOWED_HOSTS, or, when that is empty too, an origin whose hostname is the request’s own Host. Only the hostname of an origin is compared. Requests without an Origin header, which is how CLI and IDE clients connect, are not affected.

    An allow-list (only expose a specific set of tool names) is also supported at the module level for embedders that need tighter control than the read-only switch alone provides.

    Transports

    Server-Sent Events (/mcp)

    MCP-standard SSE transport. Mounted inside Core Hub’s authenticated routing block, so the JWT or API token is validated before the stream opens.

    Streamable HTTP (/mcp/http)

    Modern single-endpoint transport preferred by newer MCP clients. Authentication is enforced by Core Hub’s global JWT filter.

    Both transports check the Host and Origin headers of every request; see DNS-rebinding protection.

    Connecting a client

    Point an MCP client (Claude Code, Claude Desktop, MCP Inspector, or any other MCP-compatible agent) at:

    https://<corehub-host>:1717/mcp/http

    Core Hub serves port 1717 over TLS when SSL_ENABLED=true, which every Gluesync installer kit sets. Use http:// only on a Core Hub you started with TLS disabled. Behind the kit’s reverse proxy, use the proxy address instead, for example https://<gluesync-host>/mcp/http. Settings → AI agents shows the exact address under Connect. A client that cannot verify the kit’s self-signed certificate needs your own certificate (see HTTPS and secure WebSockets).

    with the header:

    Authorization: Bearer <corehub-jwt-or-api-token>

    A Core Hub session token works, and so does a Personal API Token (gsp_…) with the gluesync.mcp or gluesync.mcp_read permission scope (or a legacy token without permission scopes). Create and rotate long-lived tokens under Settings (the gear icon in the upper-right corner) → Account → Personal API Tokens. Once connected, the tools the caller’s role permits become available:

    • with gluesync.mcp, every tool, including the ones that change pipelines, settings, and data;

    • with gluesync.mcp_read, the read-only tools: a tool that changes something answers with an error naming the scope, queries run read-only, and company tools are not offered.

    A token limited to specific agents reaches only those agents and gets no company tools. See Personal API Tokens and scopes.

    For the Enterprise brain setup prompt and local-only reachability notes (cloud MCP clients versus loopback Core Hub), see Enterprise brain.

    User: which pipelines are running?
    Agent -> list_pipelines()
    Agent -> get_pipeline_status(pipeline_id="abc-123")
    
    User: copy the customers table of pipeline abc-123 again, then keep it in sync
    Agent -> sync_command(pipeline_id="abc-123", command="redo", entity_names=["customers"])

    sync_command runs the four sync commands with one tool: start (with with_snapshot for a snapshot ahead of CDC), stop, redo (forget the entity’s progress, take a full snapshot, then CDC) and one_time_snapshot. It takes entity_ids, entity_names, a group_id (start and stop), or nothing for the whole pipeline. From Core Hub 2.3.2.0 it replaces the separate start_sync, stop_sync, redo_sync, one_time_snapshot, start_group_sync and stop_group_sync tools of earlier releases.

    Do not let an agent call reset_pipeline_checkpoint on its own initiative. It deletes the read position of every entity of the pipeline, so changes made while the entities are stopped can be lost. Use it only under the supervision of MOLO17 Support, as described in Diagnose and recover a stalled pipeline or entity. To copy a table again, sync_command with redo is enough.

    Built-in tool catalog

    This catalog is generated from the Core Hub source (defaultGluesyncTools()), and matches the tools a Core Hub 2.3.2 session lists. WRITE tools are the ones hidden by GLUESYNC_MCP_READ_ONLY=true and refused to a gluesync.mcp_read token.

    Category Tools Read (READ) Change something (WRITE)

    Pipelines

    12

    list_pipelines, get_pipeline, get_pipeline_status, get_pipeline_snapshot_status, get_pipeline_entities_status, verify_pipeline_connections, get_pipeline_draft_status

    complete_pipeline_configuration, delete_pipeline, create_pipeline, update_pipeline, reset_pipeline_checkpoint

    Agents

    14

    list_pipeline_agents, get_agent, get_agent_node_info, verify_agent_connection, discover_schemas, discover_tables, discover_columns, list_agent_types

    get_agent_raw, add_agent, attach_connection, set_agent_specific_config, assign_agent, unassign_agent

    Connections

    6

    list_connections, get_connection, get_connection_usages, get_connection_sign_in

    create_connection, delete_connection

    Entities

    10

    get_pipeline_entities, get_entity, describe_entity_schema, list_field_functions, draft_entity, validate_entities, suggest_chain_order

    create_entity, upsert_entities, delete_entities

    Sync & maintenance

    9

    resolve_restart_positions, check_snapshot_autotuning, get_snapshot_autotuning

    sync_command, start_sync_from_point, enter_maintenance_mode, exit_maintenance_mode, start_snapshot_autotuning, stop_snapshot_autotuning

    Observability

    11

    get_notifications, get_notification, get_system_conditions, get_notification_count, get_pipeline_metrics, get_agent_metrics, get_entity_metrics, get_global_metrics, get_prometheus_metrics, get_agent_prometheus_metrics

    mark_notifications_read

    Webhooks

    13

    get_webhook_configurations, get_webhook_event_types, get_webhook_severities, get_webhook_delivery_logs, get_webhook_dead_letters, get_webhook_retention_configuration

    update_webhook_configurations, send_test_webhook, send_webhook_notification, retry_webhook_dead_letter, update_webhook_retention_configuration, purge_webhook_delivery_logs, purge_webhook_dead_letters

    Email notifications

    5

    get_email_notification_configuration

    update_email_notification_configuration, send_test_email_notification, send_email_notification, update_email_alert_recipients

    Mapping functions

    3

    list_mapping_functions, get_mapping_function_code

    compile_mapping_function

    Chronos

    21

    list_schedules, get_schedule, get_schedule_chain_status, list_trigger_flows, get_trigger_flow, get_trigger_flow_logs, list_chronos_settings, get_chronos_setting

    create_schedule, update_schedule, delete_schedule, run_schedule, set_schedule_enabled, create_trigger_flow, update_trigger_flow, delete_trigger_flow, set_trigger_flow_enabled, regenerate_trigger_flow_token, fire_trigger_flow, create_chronos_setting, update_chronos_setting

    Query Studio

    8

    list_sql_capable_agents, execute_sql, explain_sql, get_table_ddl, list_saved_queries, get_saved_query

    classify_table, classify_schema

    Query Forge

    1

    get_query_forge_driver_info

    —

    Validator

    6

    list_data_comparison_runs, get_data_comparison_run, list_data_comparison_differences

    trigger_data_comparison, reconcile_data_comparison_differences, cancel_data_comparison_run

    Visualize

    8

    list_visualization_collections, list_visualizations, get_visualization, get_visualization_data

    embed_visualization_chart, create_visualization, author_visualization, refresh_visualization

    Documentation

    2

    search_documentation, search_support_knowledge

    —

    AI agents

    7

    list_published_agents, get_agent_run, search_enterprise_brain, export_ai_settings

    start_agent_run, publish_skill, import_ai_settings

    Core Hub

    12

    list_groups, get_global_config, get_global_config_keys, get_release_channel, get_usage_analytics_status, get_license_info, get_corehub_version, export_pipeline_yaml, get_backup_status

    set_log_level, set_usage_analytics, run_backup

    Support

    1

    —

    upload_support_logs

    Total: 149 built-in tools, 64 of them WRITE. Earlier releases had fewer: 142 up to 2.3.1.0, 143 in 2.3.1.1 to 2.3.1.3 (with get_system_conditions), and 144 in 2.3.1.4 (with get_connection_sign_in). 2.3.2.0 merged the six start, stop, redo, snapshot and group tools into sync_command and added the restart-from-a-point, snapshot speed test, chain order, support upload and backup tools. get_backup_status and run_backup are offered only while dev mode is on, so a session normally lists 147 built-in tools. A session also lists the db_<pipelineId>_<agentId>_<toolName> tools of the SQL-capable agents the token can reach (see Dynamic database tools) and the approved company tools of the Enterprise brain (company_<server>_<tool>), so the number a client shows is usually higher than 149.

    Notes on some categories:

    • Pipelines: get_pipeline_draft_status and complete_pipeline_configuration read why a pipeline is still a Draft and leave Draft once its source and target agents have saved connections.

    • Entities: call suggest_chain_order before you create or edit a multi-table entity (a chain) with upsert_entities.

    • Sync & maintenance: sync_command covers start, stop, redo and one-time snapshot. resolve_restart_positions previews, and start_sync_from_point runs, a restart from a point in time. The *_snapshot_autotuning tools run the snapshot speed test.

    • Observability: get_system_conditions lists conditions that affect the whole Core Hub, such as the link to Gluesync Connect being down or the data folder running low on disk space, and answers an empty list when everything is healthy.

    • Email notifications: update_email_alert_recipients replaces the recipient list and leaves the SMTP server, credentials and filters unchanged.

    • Connections: a connection still used by an agent cannot be deleted. get_connection_sign_in reads the state of a connection that a user signs in to (Databricks OAuth U2M) and never returns a token.

    • Chronos: the tools resolve the connected Chronos module address; an MCP caller cannot override it.

    • Query Forge: get_query_forge_driver_info returns the latest GA release of the Gluesync JDBC driver. See Query Forge.

    • Validator: compare one entity and optionally reconcile every difference (reconcile_all) or a listed set of difference ids. See Validator.

    • Visualize: saved charts, their data, building or revising one from a plain-language request, and a time-limited PNG link to show a chart in a chat, report or e-mail. See Visualize.

    • AI agents: invoke published Spark agents and search the Enterprise brain from any MCP client; runs execute as the caller, and publish_skill needs Manager/Super admin or the skills:publish key scope. export_ai_settings and import_ai_settings move the AI configuration between Core Hubs as a bundle without secrets.

    • Core Hub: get_usage_analytics_status and set_usage_analytics read and switch the anonymous usage analytics. get_agent_raw (under Agents) returns stored credentials, so it counts as WRITE.

    • Support: upload_support_logs archives the Core Hub logs and uploads them into the support ticket of a log upload voucher.

    Chronos tools forward the caller’s Personal API Token. Custom webhook and email sends require configuration-change permission and bypass saved event and severity filters so an approved agent can report on demand. classify_table and classify_schema return labels only — never raw cell values — but store the verdicts they find, so they are WRITE tools; execute_sql masks classified PII. list_saved_queries and get_saved_query return saved queries the caller owns or that are shared with them. See Saved queries and PII discovery and masking.

    Saved queries

    execute_sql runs a statement the caller writes. Two more read tools let Spark, or any other MCP client, open queries already saved in Query Studio:

    Tool What it returns

    list_saved_queries

    Saved queries the caller can see: their own, plus PIPELINE and TEAM queries shared with them. Optional filters: pipeline_id, agent_id, and scope (mine or team).

    get_saved_query

    One saved query by saved_query_id, including its SQL, when the caller owns it or it is shared with them.

    A personal query owned by someone else is not returned. Viewer and external-module callers only see their own personal queries. Monitor and above also see shared pipeline and team queries (see MONITOR). Those are the same visibility rules as the Saved Queries page.

    To run one, call get_saved_query, then execute_sql with the returned sql, pipelineId, and agentId. execute_sql stays read-only and still masks classified PII.

    Spark receives these tools only when they are on that agent’s MCP tool allow-list. The Ask your data starter includes list_saved_queries and get_saved_query together with list_sql_capable_agents, execute_sql, and explain_sql.

    Dynamic database tools

    When GLUESYNC_MCP_DYNAMIC_DB_TOOLS is enabled, opening an MCP session triggers a discovery step against Query Studio:

    1. The server calls Core Hub’s /query-studio/mcp/agents endpoint, using the caller’s own bearer token, to list the SQL-capable agents that user can access.

    2. For each agent, it fetches the agent’s registered Query Studio MCP tools from /query-studio/pipelines/{pipelineId}/agents/{agentId}/mcp/tools.

    3. Each discovered tool is registered as an MCP tool named db_<pipelineId>_<agentId>_<toolName>, with its description prefixed by the agent’s display name.

    4. Invoking one of these tools forwards the call, with the same bearer token, to /query-studio/pipelines/{pipelineId}/agents/{agentId}/mcp/invoke.

    This is what lets an external MCP client reach the databases connected to Core Hub directly through the same MCP session — still scoped by the caller’s Query Studio permissions and the pipeline’s SQL-capable agents.

    Security model

    • No standalone credentials: the module holds no service account or elevated token; every call is authenticated with the caller’s own bearer token.

    • Token scopes: a Personal API Token’s permission and agent scopes apply to every tool call. See Personal API Tokens and scopes.

    • Session ownership: an MCP session belongs to the token and user that opened it. A request naming the session with another token or user gets HTTP 404, on both the SSE and the streamable HTTP transport.

    • RBAC parity with the Web UI: by default, tool calls are forwarded to the same loopback REST API the Web UI uses (the optional in-process client is a dev-only opt-in), so permissions, license limits, and audit logging apply identically.

    • Read-only deployments: set GLUESYNC_MCP_READ_ONLY=true to expose only inspection/reporting tools, suitable for observability-only AI agents.

    • Transport security: place Core Hub behind TLS in production; MCP traffic (SSE and streamable HTTP) is served on the same origin and port as the rest of the Core Hub API.

    • PII redaction: execute_sql masks classified columns in the tool result. classify_table and classify_schema return labels and confidence only. See PII discovery and masking.

    • DNS-rebinding protection: see DNS-rebinding protection.

    DNS-rebinding protection

    A web page can make a browser send requests to a hostname that it then re-resolves to an address inside your network, such as the Core Hub host. To stop such a page from driving the MCP endpoint, Core Hub checks the Origin header that a browser sends, and, once you list hostnames in GLUESYNC_MCP_ALLOWED_HOSTS, the Host header too:

    • With GLUESYNC_MCP_ALLOWED_HOSTS empty (Core Hub 2.3.1.4 and later), any Host is accepted. A browser Origin must name the request’s own Host, a localhost name, or an entry of GLUESYNC_MCP_ALLOWED_ORIGINS.

    • With GLUESYNC_MCP_ALLOWED_HOSTS set, /mcp and /mcp/http answer only when the Host header names a listed hostname or a localhost name, and a browser Origin must be allowed too. Core Hub 2.3.1.1 to 2.3.1.3 always worked this way, with only the localhost names allowed when the variable was empty.

    A refused request gets HTTP 403:

    {"error":{"code":-32000,"message":"Invalid Host: gluesync.corp.example.com"},"jsonrpc":"2.0"}
    • localhost, 127.0.0.1 and [::1] are always allowed, so local clients and the in-product AI Studio keep working.

    • To restrict the endpoint to the hostnames your MCP clients use, list them in GLUESYNC_MCP_ALLOWED_HOSTS. List only hostnames you control and serve over TLS.

    • The protection cannot be turned off. Allowing a hostname does not replace authentication: every request still needs a valid bearer token.

    • Core Hub logs the allowed hostnames at startup, and logs a warning naming the refused host the first time a request with it is refused (then at most once every 10 minutes per host).

    Running behind a reverse proxy or on a custom hostname

    When MCP clients reach Core Hub through a reverse proxy or a DNS name, for example https://gluesync.corp.example.com/mcp/http, the proxy forwards that name in the Host header. From Core Hub 2.3.1.4, with GLUESYNC_MCP_ALLOWED_HOSTS empty, that works with no setup. On 2.3.1.1 to 2.3.1.3, or once the variable lists other hostnames, every MCP request answers 403 Invalid Host: gluesync.corp.example.com until the hostname is listed. Set it on the Core Hub container and restart Core Hub:

    services:
      gluesync-core-hub:
        environment:
          - GLUESYNC_MCP_ALLOWED_HOSTS=gluesync.corp.example.com

    The startup log then shows the hostname among the allowed hosts. On releases before 2.3.1.1, which do not have GLUESYNC_MCP_ALLOWED_HOSTS, have the reverse proxy rewrite the Host header to localhost for requests under /mcp. That rewrite keeps working after the upgrade.

    In-product AI Studio and Settings

    The Control Plane keeps two related Settings surfaces:

    • Settings → AI agents (MCP) — discover endpoints and copy configuration for external MCP clients connecting to this server (see Connecting a client).

    • Settings → LLM providers and side navigation AI Studio (/ai-studio) — bring-your-own LLM providers (including optional token prices and monthly spend) and in-product agents that call MCP tools with the signed-in user’s permissions. Super admins administer the vault; managers can review providers and spend. See AI models and LLM providers and AI Studio.

    These surfaces are complementary; AI Studio does not replace the MCP client guidance tab.

    See also