ucontrol-mcp

MCP stdio server for the uControl Schema, uAsset, and uMap APIs documented in:

• DOCC80-API Settings-060526-173133.pdf
• DOCC80-Schema API's-060526-173649.pdf
• DOCC80-uAsset API's-060526-173407.pdf
• DOCC80-uMap API's-060526-173553.pdf

The server deliberately separates protocols by access type:

• Read-only tools are named ucontrol_read_* and are registered with readOnlyHint: true.
• Write/mutation tools are named ucontrol_write_* and are registered with readOnlyHint: false.
• Destructive write tools, such as delete, remove, unlink, and decommission operations, are registered with destructiveHint: true.
• ucontrol_read_protocols returns the complete local inventory with read/write/destructive classification and whether each tool is currently registered.

Install

npm install
npm run build

Configuration

Required:

UCONTROL_BASE_URL=https://ucontrol.example.com/uControl

Optional:

UCONTROL_API_TOKEN=...
UCONTROL_COOKIE=JSESSIONID=...
UCONTROL_TIMEOUT_MS=30000
UCONTROL_TOOL_MODE=read-only
UCONTROL_ALLOW_WRITES=false

Authentication follows the API Settings document: uControl can be configured to require bearer-token authentication, and authenticated users must be in the API-Access team.

UCONTROL_BASE_URL should normally include the /uControl context path. The server appends documented API paths such as /api/schema/definitions.

Read-only mode

This is the default. Only ucontrol_read_* tools are registered.

{
  "mcpServers": {
    "ucontrol": {
      "command": "node",
      "args": ["/Volumes/Hub/Code/GitHub/ucontrol-mcp/dist/index.js"],
      "env": {
        "UCONTROL_BASE_URL": "https://ucontrol.example.com/uControl",
        "UCONTROL_API_TOKEN": "replace-me",
        "UCONTROL_TOOL_MODE": "read-only"
      }
    }
  }
}

Read/write mode

Write tools are registered only when UCONTROL_TOOL_MODE=read-write. They still refuse to execute unless UCONTROL_ALLOW_WRITES=true.

{
  "mcpServers": {
    "ucontrol": {
      "command": "node",
      "args": ["/Volumes/Hub/Code/GitHub/ucontrol-mcp/dist/index.js"],
      "env": {
        "UCONTROL_BASE_URL": "https://ucontrol.example.com/uControl",
        "UCONTROL_API_TOKEN": "replace-me",
        "UCONTROL_TOOL_MODE": "read-write",
        "UCONTROL_ALLOW_WRITES": "true"
      }
    }
  }
}

LM Studio setup

LM Studio can run local stdio MCP servers from its MCP configuration. Build this project first, then add the server in LM Studio's MCP settings. If LM Studio exposes an Edit mcp.json action, use that; otherwise add the same JSON through its MCP server UI.

From this repository:

cd /Volumes/Hub/Code/GitHub/ucontrol-mcp
npm install
npm run build

Recommended starting configuration is read-only:

{
  "mcpServers": {
    "ucontrol": {
      "command": "node",
      "args": ["/Volumes/Hub/Code/GitHub/ucontrol-mcp/dist/index.js"],
      "env": {
        "UCONTROL_BASE_URL": "https://ucontrol.example.com/uControl",
        "UCONTROL_API_TOKEN": "replace-me",
        "UCONTROL_TOOL_MODE": "read-only"
      }
    }
  }
}

If LM Studio cannot find node, replace "command": "node" with the absolute path from:

which node

For write access, change the environment block explicitly:

"env": {
  "UCONTROL_BASE_URL": "https://ucontrol.example.com/uControl",
  "UCONTROL_API_TOKEN": "replace-me",
  "UCONTROL_TOOL_MODE": "read-write",
  "UCONTROL_ALLOW_WRITES": "true"
}

Restart or reload LM Studio's MCP servers after saving the configuration. In a chat, verify the connection with:

Use the ucontrol_read_protocols tool and summarize which uControl tools are registered.

Expected behavior:

• In read-only mode, only ucontrol_read_* tools appear as registered.
• In read/write mode, ucontrol_write_* tools also appear, but write calls still fail unless UCONTROL_ALLOW_WRITES=true.
• If uControl requires authentication, the API token must belong to a user in the API-Access team.

VS Code setup

VS Code supports MCP servers through an mcp.json file. You can configure this server either for one workspace or for your VS Code user profile.

Options:

• Workspace config: create or edit .vscode/mcp.json in the workspace where you want the server available.
• User config: run MCP: Open User Configuration from the Command Palette.
• Guided flow: run MCP: Add Server from the Command Palette and choose Workspace or Global.

Build the server first:

cd /Volumes/Hub/Code/GitHub/ucontrol-mcp
npm install
npm run build

Recommended read-only .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "ucontrol-api-token",
      "description": "uControl API bearer token",
      "password": true
    }
  ],
  "servers": {
    "ucontrol": {
      "type": "stdio",
      "command": "node",
      "args": ["/Volumes/Hub/Code/GitHub/ucontrol-mcp/dist/index.js"],
      "env": {
        "UCONTROL_BASE_URL": "https://ucontrol.example.com/uControl",
        "UCONTROL_API_TOKEN": "${input:ucontrol-api-token}",
        "UCONTROL_TOOL_MODE": "read-only"
      }
    }
  }
}

For write access, change only the environment values intentionally:

"env": {
  "UCONTROL_BASE_URL": "https://ucontrol.example.com/uControl",
  "UCONTROL_API_TOKEN": "${input:ucontrol-api-token}",
  "UCONTROL_TOOL_MODE": "read-write",
  "UCONTROL_ALLOW_WRITES": "true"
}

After saving the config, start or restart the server with MCP: List Servers, then select ucontrol and choose Start or Restart. VS Code may ask you to trust the local server before exposing its tools in chat.

Verification prompt in VS Code Chat:

Use the ucontrol_read_protocols tool and summarize which uControl tools are registered.

Troubleshooting:

• If VS Code cannot find Node.js, replace "command": "node" with the absolute path from which node.
• If tools do not refresh after a code change, run MCP: Reset Cached Tools and restart the server.
• Use MCP: List Servers > ucontrol > Show Output to inspect startup errors.
• For remote SSH/devcontainer workspaces, configure the MCP server in the environment where Node.js and this repo path exist.
• Avoid committing real API tokens. Use VS Code inputs as shown above, or an envFile outside source control.

Tool matrix

Tool	Access	HTTP	Endpoint	Destructive
ucontrol_read_protocols	read	LOCAL	local	no
ucontrol_read_schema_definitions	read	GET	/api/schema/definitions	no
ucontrol_read_schema_data	read	GET	/api/schema/data/{definition}	no
ucontrol_read_schema_ire_rules	read	GET	/api/schema/ire/data	no
ucontrol_read_assets	read	GET	/api/asset/data/{definition}	no
ucontrol_read_asset	read	GET	/api/asset/data/{definition}/{record_identifier}	no
ucontrol_read_asset_tags	read	GET	/api/asset/tag/view	no
ucontrol_write_asset_assign_location	write	POST	/api/asset/location/assign	no
ucontrol_write_asset_remove_location	write	POST	/api/asset/location/remove	yes
ucontrol_write_asset_assign_business_unit	write	POST	/api/asset/business-unit/assign	no
ucontrol_write_asset_remove_business_unit	write	POST	/api/asset/business-unit/remove	yes
ucontrol_write_asset_assign_business_context	write	POST	/api/asset/business-context-info/assign	no
ucontrol_write_asset_remove_business_context	write	POST	/api/asset/business-context-info/remove	yes
ucontrol_write_asset_set_deleted_status	write	POST	/api/asset/set/deleted/status	yes
ucontrol_write_asset_add_relationships	write	POST	/api/asset/relationships/add	no
ucontrol_write_asset_delete_relationships	write	POST	/api/asset/relationships/delete	yes
ucontrol_write_asset_create	write	POST	/api/asset/create	no
ucontrol_write_asset_update	write	POST	/api/asset/update	no
ucontrol_write_asset_tag_create	write	POST	/api/asset/tag/create	no
ucontrol_write_asset_tag_delete	write	POST	/api/asset/tag/delete	yes
ucontrol_write_umap_model_create	write	POST	/api/umap/model/create	no
ucontrol_write_umap_sso_group_create	write	POST	/api/umap/sso/group	no
ucontrol_write_umap_team_create	write	POST	/api/umap/team	no
ucontrol_write_umap_model_decommission	write	POST	/api/umap/model/decommission	yes
ucontrol_read_umap_model_details	read	GET	/api/umap/model/details	no
ucontrol_read_umap_review_data	read	GET	/api/umap/review/data	no
ucontrol_read_umap_sso_group_details	read	GET	/api/umap/sso/group/details	no
ucontrol_read_umap_team_details	read	GET	/api/umap/team/details	no
ucontrol_write_umap_model_recommission	write	POST	/api/umap/model/recommission	no
ucontrol_write_umap_model_rename	write	POST	/api/umap/model/rename	no
ucontrol_write_umap_model_assign	write	POST	/api/umap/model/assign	no
ucontrol_write_umap_component_create	write	POST	/api/umap/component/create	no
ucontrol_write_umap_dependency_create	write	POST	/api/umap/dependency/create	no
ucontrol_write_umap_environment_create	write	POST	/api/umap/environment/create	no
ucontrol_write_umap_service_create	write	POST	/api/umap/model/services/create	no
ucontrol_write_umap_model_delete	write	POST	/api/umap/model/delete	yes
ucontrol_write_umap_service_delete	write	POST	/api/umap/model/services/delete	yes
ucontrol_read_umap_application_types	read	GET	/api/umap/model/applicationType/list	no
ucontrol_read_umap_bmc_appliances	read	GET	/api/bmc_appliance/data	no
ucontrol_read_umap_components	read	GET	/api/umap/component/data	no
ucontrol_read_umap_dependencies	read	GET	/api/umap/dependency/data	no
ucontrol_read_umap_environments	read	GET	/api/umap/environment/data	no
ucontrol_read_umap_ire_rules	read	GET	/api/umap/ire/data	no
ucontrol_read_umap_lead_accounts	read	GET	/api/umap/model/leadAccount/list	no
ucontrol_read_umap_modelling_types	read	GET	/api/umap/model/modellingType/list	no
ucontrol_read_umap_models	read	GET	/api/umap/model/list	no
ucontrol_read_umap_service_types	read	GET	/api/umap/model/services/serviceType/list	no
ucontrol_read_umap_services	read	GET	/api/umap/model/services/list	no
ucontrol_write_umap_service_link	write	POST	/api/umap/model/services/link	no
ucontrol_read_umap_model_cis	read	GET	/api/umap/model/ci/list	no
ucontrol_read_umap_model_patterns	read	GET	/api/umap/model/dp/pattern/list	no
ucontrol_write_umap_component_modify	write	POST	/api/umap/component/modify	no
ucontrol_write_umap_dependency_modify	write	POST	/api/umap/dependency/modify	no
ucontrol_write_umap_environment_modify	write	POST	/api/umap/environment/modify	no
ucontrol_write_umap_model_modify	write	POST	/api/umap/model/modify	no
ucontrol_write_umap_service_modify	write	POST	/api/umap/model/services/modify	no
ucontrol_write_umap_model_publish	write	POST	/api/umap/model/publish	no
ucontrol_write_umap_service_pull	write	POST	/api/umap/model/services/pull	no
ucontrol_write_umap_service_push	write	POST	/api/umap/model/services/push	no
ucontrol_write_umap_model_ci_unlink	write	POST	/api/umap/model/ci/unlink	yes
ucontrol_write_umap_model_patterns_unlink	write	POST	/api/umap/model/dp/patterns/unlink	yes
ucontrol_write_umap_populate	write	POST	/api/umap/populate/umap	no

Notes on documented edge cases

• ucontrol_read_asset_tags preserves the vendor-documented GET request with a JSON body. Native fetch disallows GET bodies, so the client uses Node's HTTP client for that path.
• ucontrol_write_umap_populate sends Content-Type: text/plain with a JSON string body shaped as { "data": [...] }, matching the uMap document.
• Query values that accept multiple IDs can be passed either as a comma-separated string or as an array; arrays are serialized as comma-separated values.
• ucontrol_write_umap_model_modify keeps the vendor warning in the tool description: omitted optional values may wipe existing values.

Development

npm run build
npm test

The test suite starts a local loopback HTTP server. In restricted sandboxes, that may require approval.