How do I use ucontrol-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ucontrol-mcp list all schema definitions" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

Related MCP server: mcpdeployment

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.

ucontrol-mcp

ucontrol-mcp

Install

Configuration

Read-only mode

Read/write mode

LM Studio setup

VS Code setup

Tool matrix

Notes on documented edge cases

Development

Maintenance

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API