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. |
|
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_PROCESSisfalse), 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 |
|---|---|---|
|
|
Master switch. Set to |
|
|
Path prefix. The SSE transport is mounted at this exact path, the streamable-HTTP transport at |
|
|
When |
|
|
When |
|
|
When |
|
empty (any hostname) |
Available from Core Hub 2.3.1.1. Comma-separated hostnames, besides |
|
empty (derived) |
Available from Core Hub 2.3.1.1. Comma-separated browser origins, such as |
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 |
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 |
|
|
Agents |
14 |
|
|
Connections |
6 |
|
|
Entities |
10 |
|
|
Sync & maintenance |
9 |
|
|
Observability |
11 |
|
|
Webhooks |
13 |
|
|
Email notifications |
5 |
|
|
Mapping functions |
3 |
|
|
Chronos |
21 |
|
|
Query Studio |
8 |
|
|
Query Forge |
1 |
|
— |
Validator |
6 |
|
|
Visualize |
8 |
|
|
Documentation |
2 |
|
— |
AI agents |
7 |
|
|
Core Hub |
12 |
|
|
Support |
1 |
— |
|
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_statusandcomplete_pipeline_configurationread why a pipeline is still a Draft and leave Draft once its source and target agents have saved connections. -
Entities: call
suggest_chain_orderbefore you create or edit a multi-table entity (a chain) withupsert_entities. -
Sync & maintenance:
sync_commandcovers start, stop, redo and one-time snapshot.resolve_restart_positionspreviews, andstart_sync_from_pointruns, a restart from a point in time. The*_snapshot_autotuningtools run the snapshot speed test. -
Observability:
get_system_conditionslists 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_recipientsreplaces 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_inreads 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_inforeturns 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_skillneeds Manager/Super admin or theskills:publishkey scope.export_ai_settingsandimport_ai_settingsmove the AI configuration between Core Hubs as a bundle without secrets. -
Core Hub:
get_usage_analytics_statusandset_usage_analyticsread and switch the anonymous usage analytics.get_agent_raw(under Agents) returns stored credentials, so it counts asWRITE. -
Support:
upload_support_logsarchives 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 |
|---|---|
|
Saved queries the caller can see: their own, plus |
|
One saved query by |
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:
-
The server calls Core Hub’s
/query-studio/mcp/agentsendpoint, using the caller’s own bearer token, to list the SQL-capable agents that user can access. -
For each agent, it fetches the agent’s registered Query Studio MCP tools from
/query-studio/pipelines/{pipelineId}/agents/{agentId}/mcp/tools. -
Each discovered tool is registered as an MCP tool named
db_<pipelineId>_<agentId>_<toolName>, with its description prefixed by the agent’s display name. -
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=trueto 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_sqlmasks classified columns in the tool result.classify_tableandclassify_schemareturn 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_HOSTSempty (Core Hub 2.3.1.4 and later), anyHostis accepted. A browserOriginmust name the request’s ownHost, a localhost name, or an entry ofGLUESYNC_MCP_ALLOWED_ORIGINS. -
With
GLUESYNC_MCP_ALLOWED_HOSTSset,/mcpand/mcp/httpanswer only when theHostheader names a listed hostname or a localhost name, and a browserOriginmust 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.1and[::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
-
AI Studio — BYO LLM providers and in-product agents that use this MCP tool catalog.
-
Query Studio — the in-portal SQL workbench whose tools are surfaced dynamically through the MCP server.
-
PII discovery and masking — classify tools, result masking, and the global toggle.
-
Query Forge — federated JDBC access built on the same Query Studio execution path.
-
REST APIs — the underlying Core Hub API the MCP tools call into.