AirGap for ObjectScale MCP Server

Overview

The AirGap for ObjectScale MCP Server exposes the console's API as tools that AI assistants — including Claude, Cursor, and VS Code Copilot — can call directly using the Model Context Protocol. When enabled, any MCP-capable AI client can query job status, list protection groups, trigger syncs, and inspect system health without leaving the AI chat interface.

Transport

SSE (Server-Sent Events) over HTTP. Connect your MCP client to:

http://<host>:<port>/api/mcp/sse

For production use, place nginx in front to terminate TLS and proxy to this endpoint. The MCP server itself speaks plain HTTP only.

Enabling the Server

Go to Setup & Settings > MCP Server
Turn on Enable MCP Server
Click Save MCP Settings (shown as Save Changes while there are unsaved changes)

The enabled state is saved in the console settings and survives restarts. The server is disabled by default.

Authentication

When Require API Token is enabled (recommended), clients must present:

Authorization: Bearer <token>

Create tokens in Setup & Settings > Security > API Tokens. Use API Access scope. Copy the token ID shown after creation and add it to the Allowed Token IDs list on the MCP Server tab to restrict access to that specific token. Leave the list empty to allow any valid api-scope token.

Vault-scope and agent tokens are rejected by the MCP server for all requests, read or write.

warning

Never turn off Require API Token. Turning it off removes all MCP authentication. With Full Write enabled, an anonymous caller could create an API token with full access.

Write Mode

By default the MCP server is read-only — all read tools work, but any tool that creates, updates, deletes, or triggers an action returns an error until write mode is explicitly enabled.

The Available Tools panel renders three collapsible sections that visibly lock and unlock as you change the toggles:

Section	Default	Unlocks when	Visual
Read Tools	Always unlocked	Always	Emerald badge
Write Tools	Locked	Allow Full Write Access is enabled and saved	Amber badge
Destructive Tools	Locked	Both Full Write and Destructive Operations are enabled and saved	Red badge

A live "N tools accessible" counter in the section header reflects the total across the unlocked sections.

Allow Full Write Access

When enabled, the Write Tools section unlocks: alarm lifecycle (clear, suppress, enable/disable rules), vault sync triggers, agent drain/undrain, token management, bucket group create / assign, and sync schedule policy management.

Enable with care — an AI client with full write access can trigger jobs, drain agents, and modify configuration. Restrict access to a specific token using the Allowed Token IDs list.

Allow Destructive Operations

An additional toggle, only shown when Full Write is enabled. When both toggles are on, the Destructive Tools section unlocks: application restart, vault config deletion.

Tools that require destructive mode include a "confirm": true parameter requirement — the AI client must pass this explicitly to proceed.

Do not enable destructive operations for routine AI assistant use. Reserve it for specific operator-supervised maintenance sessions.

Available Tools

Read Tools (always available when server is enabled)

Tool	Description
`get_jobs`	List all jobs with optional status filter
`get_job_detail`	Full detail for one job including step logs
`get_settings`	Current settings with secrets masked
`list_vault_configs`	All vault protection policies
`get_vault_config`	Single vault policy by configId
`list_source_accounts`	Vault source account profiles (secrets masked)
`list_target_accounts`	Vault target account profiles (secrets masked)
`get_system_health`	Database and ClickHouse health metrics
`get_security_log`	Recent API security log entries
`list_storage_inventory`	Discovered ObjectScale buckets from inventory scan
`get_ingest_lag`	Audit ingest lag in seconds per source cluster; each row has `beyond_window` (see the System Monitor help, Where the numbers come from)
`get_vault_events`	Recent vault open/close/heartbeat/error events
`list_api_tokens`	Active tokens (no secret values)
`get_alarms`	List alarm events with optional status filter (ACTIVE/CLEARED/SUPPRESSED)
`get_alarm_active_count`	Count of currently ACTIVE alarm events
`get_alarm_monitor_status`	Alarm engine last/next tick timestamps and interval
`list_alarm_rules`	All configured alarm rules (enabled and disabled)
`get_job_stats`	Job count summary: total, running, completed, failed, canceled
`get_job_queue`	Pending and running jobs queue view
`list_job_schedules`	All job schedule configurations with last-run timestamps
`get_ingest_throughput`	Ingest throughput metrics from ClickHouse (the same lag rows as `get_ingest_lag`)
`get_vault_changelist_status`	Changelist sync windows for a vault config
`get_pending_sync_summary`	Non-terminal sync windows across all configs
`get_last_incomplete_copy`	Most recent job that is not in COMPLETED status
`get_incremental_summary`	Incremental sync summary aggregated over a period (7d/14d/30d)
`get_incremental_settings`	Current incremental sync enabled/disabled flag
`get_incremental_groups_live`	Live non-terminal windows for incremental sync
`list_agents`	All registered agents (copy engines and vault agents), with status
`get_agent_detail`	Detail for a single registered agent by ID
`get_agent_health_metrics`	Agent health metrics time-series from ClickHouse
`get_agent_jvm_profiles`	Available JVM profiles assignable to agents
`get_agent_capacity_current`	Current capacity utilization for all online agents
`list_bucket_groups`	All bucket protection groups
`get_bucket_inventory_stats`	Aggregate inventory stats: total, assigned, unassigned
`get_objectscale_status`	ObjectScale audit event totals per source type (`summary`) from the last full read of the audit statistics — up to 6 hours old on a large audit table without a usable statistics index, without a time of its own (see the System Monitor help); the live syslog status is `GET /api/objectscale/status`
`get_objectscale_stats`	ObjectScale persistent aggregate stats from ClickHouse: `summary` as in `get_objectscale_status`, `byCluster` from the audit statistics (empty until those have been read)
`get_audit_summary`	Audit data summary from ClickHouse
`get_system_metrics`	JVM, API call, and disk I/O metrics
`get_version`	Application build version number
`list_sync_schedule_policies`	All sync schedule policies

Write Tools (require Allow Full Write Access)

Tool	Description
`clear_alarm`	Manually clear an active alarm by alarm ID
`suppress_alarm`	Suppress an alarm rule for a specified duration
`enable_alarm_rule`	Enable a disabled alarm rule by rule code
`disable_alarm_rule`	Disable an active alarm rule by rule code
`load_default_alarm_rules`	Reset alarm rules to factory defaults
`sync_group_now`	Trigger an immediate incremental sync for a sync group. Refused while the group is in Vault Mode or the Incremental Sync switch is off
`reset_changelist_status`	Reset a changelist window to pending state for re-sync
`skip_changelist_status`	Mark a changelist window as skipped
`drain_agent`	Put a copy agent into drain mode (no new jobs assigned)
`undrain_agent`	Remove drain mode from a copy agent
`drain_all_agents`	Put all copy agents into drain mode at once
`undrain_all_agents`	Remove drain mode from all copy agents at once
`trigger_agent_upgrade`	Trigger a self-upgrade on one or all agents
`create_api_token`	Create a new API access token with specified scope
`delete_api_token`	Delete an API token by token ID
`create_sync_schedule_policy`	Create a new sync schedule policy
`delete_sync_schedule_policy`	Delete a sync schedule policy by ID
`create_bucket_group`	Create a new bucket group for policy assignment
`assign_bucket_to_group`	Assign an inventory bucket to a bucket group

Destructive Tools (require Allow Full Write Access and Allow Destructive Operations)

Tool	Description
`restart_application`	Trigger a full application restart of the console JVM
`delete_vault_config`	Permanently delete a vault protection policy config

Connecting Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "airgap-objectscale": {
      "type": "sse",
      "url": "https://<your-host>/api/mcp/sse",
      "headers": {
        "Authorization": "Bearer <your-api-token>"
      }
    }
  }
}

Connecting Cursor / VS Code

Use the SSE URL with the Bearer token header in your MCP client configuration. Refer to your client's documentation for the exact configuration format.

Security Notes

Enable TLS via nginx before exposing the MCP server to any network
Add the dedicated token ID to Allowed Token IDs to prevent token sharing
All MCP connections are logged in Setup & Settings > Security > API Access Log
The health endpoint (GET /api/mcp/health) requires no authentication and can be used for uptime monitoring
Disable the server when not in active use — the toggle persists immediately
Keep Allow Full Write Access disabled when not actively using write tools
Never enable Allow Destructive Operations for unattended or automated use

Overview​

Transport​

Enabling the Server​

Authentication​

Write Mode​

Allow Full Write Access​

Allow Destructive Operations​

Available Tools​

Read Tools (always available when server is enabled)​

Write Tools (require Allow Full Write Access)​

Destructive Tools (require Allow Full Write Access and Allow Destructive Operations)​

Connecting Claude Desktop​

Connecting Cursor / VS Code​

Security Notes​