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.

Overview

The corehub-mcp module runs inside the Core Hub JVM and mounts MCP transports alongside the existing REST and WebSocket routes. It ships 112 tools covering pipelines, agents, entities, connections, sync commands, notifications, metrics, Core Hub webhooks, email notifications, mapping functions, Chronos schedules and trigger flows, Query Studio (including PII classify), documentation search, groups, global configuration, license/version information, and pipeline export.

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            |
        +----------------------------->  /api/...   (REST)      |
                                      |  /mcp        (SSE)      |
                                      |  /mcp/http   (Streamable|
                                      |               HTTP)     |
                                      +------------+------------+
                                                   |
                                      +------------v------------+
                                      | corehub-mcp module       |
                                      |  - 112 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 (112 built-in tools)

    • Pipelines, agents, entities, connections, sync commands, notifications, metrics, Core Hub webhooks, email notifications, mapping functions, Chronos, Query Studio, 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 (start/stop sync, 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 (start/stop sync, 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.

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.

Connecting a client

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

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

with the header:

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

Any Core Hub session token or Personal API Token (gsp_…) works. Once connected, every tool the caller’s role permits becomes available.

User: which pipelines are running?
Agent -> list_pipelines()
Agent -> get_pipeline_status(pipeline_id="abc-123")

User: reset the checkpoint on pipeline abc-123 and start a full snapshot
Agent -> reset_pipeline_checkpoint(pipeline_id="abc-123")
Agent -> start_sync(pipeline_id="abc-123", with_snapshot=true)

Built-in tool catalog

Category Tools Highlights

Pipelines

10

create_pipeline, update_pipeline, list_pipelines, get_pipeline, get_pipeline_status, get_pipeline_snapshot_status, get_pipeline_entities_status, verify_pipeline_connections, delete_pipeline, reset_pipeline_checkpoint

Agents

14

add_agent, assign_agent, attach_connection, set_agent_specific_config, list_pipeline_agents, list_agent_types, get_agent, get_agent_raw, get_agent_node_info, discover_schemas, discover_tables, discover_columns, verify_agent_connection, unassign_agent

Entities

9

get_pipeline_entities, get_entity, describe_entity_schema, list_field_functions, draft_entity, create_entity, validate_entities, upsert_entities, delete_entities

Sync commands

8

start_sync, stop_sync, redo_sync, one_time_snapshot, start_group_sync, stop_group_sync, enter_maintenance_mode, exit_maintenance_mode

Notifications

4

get_notifications, get_notification, get_notification_count, mark_notifications_read

Metrics

6

get_pipeline_metrics, get_agent_metrics, get_entity_metrics, get_global_metrics, get_prometheus_metrics, get_agent_prometheus_metrics

Webhooks

13

get_webhook_configurations, update_webhook_configurations, send_webhook_notification, send_test_webhook, get_webhook_event_types, get_webhook_severities, get_webhook_delivery_logs, get_webhook_dead_letters, retry_webhook_dead_letter, get_webhook_retention_configuration, update_webhook_retention_configuration, purge_webhook_delivery_logs, purge_webhook_dead_letters

Email notifications

4

get_email_notification_configuration, update_email_notification_configuration, send_test_email_notification, send_email_notification

Mapping functions

3

list_mapping_functions, get_mapping_function_code, compile_mapping_function

Connections

4

create_connection, list_connections, get_connection, get_connection_usages

Chronos

21

list_schedules, get_schedule, create_schedule, update_schedule, delete_schedule, run_schedule, set_schedule_enabled, get_schedule_chain_status, list_trigger_flows, get_trigger_flow, create_trigger_flow, update_trigger_flow, delete_trigger_flow, set_trigger_flow_enabled, regenerate_trigger_flow_token, fire_trigger_flow, get_trigger_flow_logs, list_chronos_settings, get_chronos_setting, create_chronos_setting, update_chronos_setting (via the connected Chronos module address)

Query Studio

6

list_sql_capable_agents, execute_sql, explain_sql, get_table_ddl, classify_table, classify_schema

Documentation

2

search_documentation, search_support_knowledge

Groups & global config

5

list_groups, get_global_config, get_global_config_keys, get_release_channel, set_log_level

License / version / export

3

get_license_info, get_corehub_version, export_pipeline_yaml

Total: 112 tools. Any tool listed under a mutating category above (for example, create_pipeline, update_pipeline, add_agent, create_entity, delete_pipeline, start_sync, upsert_entities, enter_maintenance_mode, mark_notifications_read, set_log_level, send_webhook_notification, send_email_notification, Chronos schedule/trigger mutations) is classified WRITE and is the first to be hidden when GLUESYNC_MCP_READ_ONLY=true. Chronos tools resolve the connected chronos module and forward the caller’s Personal API Token; an MCP caller cannot override the module address. 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 — and execute_sql masks classified PII. See PII discovery and masking.

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.

  • 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.

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