Admin Tools — Setup & User Guide
Overview
This guide walks non-technical administrators, help desk personnel, and IT operators through understanding the newly released HOD 16.0.3 Admin Tools, discovering how many tools are available, understanding how tool invocation works step-by-step from prompt to execution, configuring end-to-end security parameters with clear explanations of why each setting is required, and connecting an AI chatbot (such as Claude Desktop) to perform administrative tasks with simple conversational commands.
What Are MCP Admin Tools?
MCP stands for Model Context Protocol. Think of it as a secure universal translator that sits between an AI chat assistant (like Claude Desktop) and your Host On-Demand (HOD) host system.
Released officially in HOD 16.0.3, Admin Tools empower non-technical staff and administrators to manage accounts, unlock users, and audit system configurations without ever opening green-screen emulators or navigating complex legacy admin consoles. Instead of typing scripts or manually calling REST endpoints, you simply ask in natural language: "Show all locked users" or "Unlock user JohnDoe", and the AI executes the action safely on your behalf.
NO DEVELOPMENT REQUIRED: You don't write any code or build APIs to set this up. The MCP Server automatically reads HOD's REST API definitions and exposes them as ready-to-use tools. You only need to verify configuration properties and connect your chatbot.
Working of MCP Admin Tools: From Prompt to Execution
When a user submits an administrative request through an AI chatbot, a series of interactions takes place between the AI client, the Model Context Protocol (MCP) server, and HCL Host On-Demand (HOD).
The following steps explain how an administrative request is processed, from interpreting the user's prompt to executing the requested operation and displaying the results.
Step 1: Submit an Administrative Request
The user enters an administrative request in natural language through an AI chat client, such as Claude Desktop.
For example:
-
"Show all locked users."
-
"Unlock user JohnDoe."
Step 2: Interpret the User Request
The Large Language Model (LLM) processes the user's request, identifies the intended administrative operation, and determines which available tool can perform the requested task.
Step 3: Communicate with the MCP Server
The AI client communicates with the configured HOD MCP server to discover the available administrative tools and their capabilities.
Step 4: Identify the Appropriate Administrative Tool
(tools-config.yaml)
Based on the available tool definitions configured in the
tools-config.yaml file, the AI client identifies the
appropriate tool, such as getLockedUsers or
unlockUser.
The required input parameters are then identified and supplied for the selected operation.
Step 5: Resolve the Backend API Endpoint
(api-config.yaml)
The MCP server uses the configuration defined in the api-config.yaml
file to identify the corresponding HOD REST API endpoint and HTTP method, such as
GET or POST, required to perform the requested operation.
Step 6: Validate Authentication and Authorization
Before executing the operation, the system performs the applicable security checks, which may include:
-
Validating the OAuth 2.0 bearer token.
-
Verifying the token's digital signature using JSON Web Key Set (JWKS).
-
Confirming that the authenticated user has the required administrative permissions.
These checks help ensure that only authorized users can perform administrative operations.
Step 7: Execute the Administrative Operation
After successful authentication and authorization, the HOD backend processes the requested operation, such as unlocking a user account.
The result of the operation is returned to the MCP server, typically in JSON format.
Step 8: Display the Operation Results
The MCP server returns the operation results to the AI client. The chatbot then presents the response in a user-friendly format, such as a structured table, status message, or confirmation of the completed operation.
This process enables administrators and IT operators to perform supported HOD administrative tasks through natural-language requests without manually interacting with individual REST API endpoints.
03 How Many Admin Tools Are There? (Complete Catalog)
In HOD 16.0.3, there are 14 core, dedicated Admin MCP Tools included out of the box, organized into 3 functional categories:
• 9 User Management Tools
• 4 Group Management Tools
• 1 Configuration Management Tool
| Category | Tool ID & Name | What It Does | Example Natural Language Prompt |
| User Management |
Create User (createUser) |
Registers a new user account with initial password, description, and group memberships. | "Create a new user named Alice with group Support" |
| User Management |
Get User Profile (getUserByUsername) |
Retrieves complete profile details, active status, and groups for a specific user. | "Get details for user jsmith" |
| User Management |
List All Users (getUsers) |
Lists all users currently configured within the HOD environment in a structured table. | "Show all the users in the system" |
| User Management |
Update User (updateUser) |
Modifies existing user profile data, updates passwords, or updates group memberships. | "Update user Alice: change description to Senior Support" |
| User Management |
Delete User (deleteUser) |
Permanently removes an obsolete or departed user account from the HOD directory. | "Delete user bob_temp" |
| User Management |
Unlock User (unlockUser) |
Unlocks an account locked due to repeated failed logins and assigns a temporary password. | "Unlock user jsmith with password Welcome123!" |
| User Management |
List Locked Users (getLockedUsers) |
Retrieves a complete list of all currently locked accounts across the system. | "Show me all locked user accounts" |
| User Management |
Verify Admin (isAdminUser) |
Checks whether a specified user possesses administrative rights in HOD. | "Is user jsmith an administrator?" |
| User Management |
Check PCOMM User (isPCOMMUser) |
Checks whether an account is configured for Personal Communications (PCOMM). | "Check if user Alice is a PCOMM user" |
| Group Management |
Create Group (createGroup) |
Creates a new user group within HOD to streamline permission management. | "Create a new group named 'Auditors'" |
| Group Management |
Get Group Details (getGroup) |
Fetches configuration parameters, member associations, and permissions for a group. | "Show details for group 'Mainframe_Ops'" |
| Group Management |
List All Groups (getGroups) |
Retrieves a complete list of all user groups configured in the HOD environment. | "List all configured user groups" |
| Group Management |
Delete Group (deleteGroup) |
Permanently deletes an existing group, with optional recursive subtree deletion. | "Delete group 'Legacy_Staff'" |
| Configuration |
Update Config (updateConfiguration) |
Safely updates system properties or HOD environment configurations using JSON data. | "Update HOD session timeout configuration" |
04 Before You Start (Prerequisites)
Before starting the server, ensure your machine meets the following basic requirements:
1. Host On-Demand 16.0.3 installed and operational.
2. Java Development Kit (JDK) 17 or later installed (the server JAR requires Java 17+ to launch).
3. Node.js (v24 or higher) required on the client machine where your AI application runs (such as Claude Desktop, VS Code, or other MCP-compatible clients) to run the npx and mcp-remote bridge connecting to the server.
4. Network connectivity between the MCP host and your HOD server.
5. Supported Operating Systems: Windows and Linux platforms.
6. AI Chatbot: Claude Desktop (or any MCP-compliant AI assistant).
05 Detailed Configuration Guide & Why Each Setting Is Required
To enable secure communication between the AI Chatbot, the MCP Server, and the Admin Tools, a few straightforward configuration settings must be defined. Below is the clean, complete breakdown of every file, the properties you need to set, and the exact security reason why each setting is required.
5.1 Configure web.properties (HOD Authentication Gateway)
Location: C:\Program Files\IBM\HostOnDemand_16.0.0.0\HOD\web.properties
Open or create web.properties and provide the following properties (example shown for Okta):
oidc_domain=https://hcl-software.okta.com
client_id=<YOUR_OKTA_CLIENT_ID>
redirect_uri=
scope=openid profile email
AuthorizationEndpoint=https://hcl-software.okta.com/oauth2/v1/authorize
expectedRoles=default-roles-hod_admin,HOD_Admin,zie_admin_role,admin,ADMIN,groups
roleClaimPaths=scp,groups,roles,realm_access.roles,https://myapp.com/roles
claim_id=preferred_username
| Property Name | Example Setting | Why It Is Required |
| oidc_domain / AuthorizationEndpoint | https://...okta.com | OIDC Provider URLs: Directs login and token authorization requests to your enterprise Identity Provider authority. |
| client_id / redirect_uri | Client credentials & callback | OAuth Client Registration: Connects HOD to the configured IdP client application and defines the trusted return URI. |
| scope | openid profile email | OAuth Scopes: Requests standard OpenID Connect profile and identity claims needed during token issuance. |
| claim_id | preferred_username | User Identification: Specifies which JSON claim to extract as the user's login ID (e.g. preferred_username instead of sub or email) to match the user in HOD's directory. |
| expectedRoles | HOD_Admin, admin, groups... | Access Control: Grants access to the admin tools only if the user's token contains at least one of these authorized roles. Blocks unauthorized standard users. |
| roleClaimPaths | scp, groups, roles... | IdP Flexibility: Identity Providers store user roles under different token keys (e.g. Okta uses 'groups', Keycloak uses 'realm_access.roles'). This tells the parser where to inspect in sequence. |
5.2 Configure config.properties (HOD Internal Claim Mapping)
Location: C:\Program Files\IBM\HostOnDemand_16.0.0.0\HOD\config.properties
Open config.properties and add:
claimid=preferred_username
WHY IT IS REQUIRED: After initial token validation at the outer gateway, requests reach the internal HOD REST API layer. This parameter instructs HOD's internal engine which JSON claim represents the user login ID, ensuring internal operations are executed against the correct HOD user profile.
5.3 Configure SSOConf.properties (Cryptographic Token Verification)
Location: C:\Program Files\IBM\HostOnDemand_16.0.0.0\private\SSOConf.properties
Open SSOConf.properties and configure your Identity Provider endpoints (example for Okta):
expectedIssuer=https://hcl-software.okta.com
jwks_uri=https://hcl-software.okta.com/oauth2/v1/keys
expectedRoles=default-roles-hod_admin,HOD_Admin,zie_admin_role,admin,ADMIN
roleClaimPaths=scp,groups,roles
| Parameter | Example Setting | Why It Is Required |
| expectedIssuer | https://hcl-software.okta.com | Issuer Check: Verifies that the token's 'iss' claim matches your trusted enterprise Identity Provider, blocking forged or unauthorized tokens. |
| jwks_uri | https://.../v1/keys | Cryptographic Signature Check: Retrieves the public signing keys from your IdP to mathematically verify that the token was authentically signed and not altered in transit. |
| expectedRoles & roleClaimPaths | admin, HOD_Admin... | Independent Authorization: Ensures HOD independently validates admin privileges before executing sensitive REST operations, providing defense-in-depth. |
5.4 Configure ConfigAgentParms.Data (HOD Admin Privilege Mapping)
Location: C:\Program Files\IBM\HostOnDemand_16.0.0.0\private\ConfigAgentParms.Data
Add the administrative user identifier matching the SSO login:
ADMIN=WriteUserFolders admin Arpan.bandyopadhyay
WHY IT IS REQUIRED & ACTION: Maps the SSO user identity directly to HOD's internal administrative role. Without this mapping, the HOD engine will reject write/update operations with a 403 Forbidden error, even if the OAuth token is valid.
ACTION: After saving this file, restart the Host On-Demand service.
5.5 Configure web.xml (WAR Servlet Context Parameters)
Location: WEB-INF/web.xml inside your deployed web application archive (WAR):
Add the JWT context parameters agentJwtIssuer and agentJwtJwksUri (Okta example):
<context-param>
<param-name>agentJwtIssuer</param-name>
<param-value>https://hcl-software.okta.com</param-value>
</context-param>
<context-param>
<param-name>agentJwtJwksUri</param-name>
<param-value>https://hcl-software.okta.com/oauth2/v1/keys</param-value>
</context-param>
WHY IT IS REQUIRED: Enables to independently validate JWT tokens and download public keys directly from the IdP. Once configured, save and redeploy the WAR.
5.6 Configure api-config.yaml (Admin Tool Endpoint Settings)
Location: C:\Program Files\IBM\HostOnDemand_16.0.3.0\lib\mcp\config\api-config.yaml
Configure the core API endpoint settings for Admin Tools:
| YAML Property | Setting | Why It Is Required |
| baseurl | <context-root> /api/admin/tools | Target REST API: Sets the destination URL where HOD Admin REST tools reside. The '/api/admin/tools' suffix must remain unchanged. |
| secured | true | Enforce Authentication: Mandates that all incoming MCP tool invocations must present valid security tokens. |
| isSameIDP | true | Single Authority: Confirms that both the MCP Server and the HOD backend rely on the same Identity Provider. |
| mcp.security.enabled | true | Endpoint Protection: Locks down all MCP communication ports, allowing only authenticated AI client traffic. |
5.7 Configure application.yaml (MCP Server OAuth2 & UI Security)
Location: C:\Program Files\IBM\HostOnDemand_16.0.3.0\lib\mcp\config\application.yaml
Configure the Spring Security OAuth2 resource server, client registration, and UI protection:
| YAML Property | Setting | Why It Is Required |
| spring.security.oauth2.resourceserver.jwt.issuer-uri | <issuer uri> | Token Signature & Validation: The authorization server base URL that signs incoming access tokens. The resource server downloads public keys to validate JWT signatures. |
| spring.security.oauth2.client.registration.keycloak.client-id | admin-mcp-ui | OAuth Client ID: Identifies the MCP UI application client registered in your Identity Provider (e.g., Keycloak or Okta). |
| spring.security.oauth2.client.registration.keycloak.client-secret | <client secret> | OAuth Client Secret: Confidential credential for the MCP UI application to authenticate against the authorization server. |
| spring.security.oauth2.client.registration.keycloak.authorization-grant-type | authorization_code | Grant Flow: Enforces standard OAuth2 Authorization Code grant type for browser-based user logins to the UI. |
| spring.security.oauth2.client.registration.keycloak.redirect-uri | {baseUrl}/login/oauth2/code/{registrationId} | Redirect URI: Standard callback template where the authorization server redirects users back after successful authentication. |
| spring.security.oauth2.client.registration.keycloak.scope | openid, profile, email | User Scopes: Standard OIDC scopes requested to retrieve the authenticated user's identity details. |
| mcp.security.enabled | true | Set to true if the MCP Server should require authentication |
| mcp.security.auth_type | OAUTH2 | Authentication Type: Mandates that all incoming MCP tool invocation requests must carry a valid OAuth2 bearer token. |
| mcp.security.ui_config.security_enabled | false (or true if UI security is required) | MCP Web UI Protection: Set to true if the MCP Server web interface should require authentication, or false for open administrative access on localhost. |
FURTHER REFERENCE & DEPLOYMENT: For additional advanced parameters and environment-specific settings, please refer to the main MCP Server Configuration documentation.
DEPLOYMENT STEP: After updating all configuration properties, restart the IBM HOD server, deploy HEX.war to your application server, and start the server.
Now Restart MCP server.
06 Connecting a Chatbot
We support various AI assistants and clients, including Claude Desktop and Visual Studio Code (VS Code Copilot) etc.
Below are the configuration steps and settings for Claude Desktop.
(For setup instructions regarding other AI assistants or developer environments, please refer to their respective official documentation websites.)
Once the server is running, connect your AI chatbot. For Claude Desktop, follow these simple steps:
1. Open your Claude Desktop configuration file:
Windows path: %APPDATA%\Claude\claude_desktop_config.json
2. Add the following block under "mcpServers":
{
"mcpServers": {
"hcl-mcp-server": {
"command": "npx.cmd",
"args": [
"--yes",
"--refresh",
"mcp-remote",
"<mcp server uri>",
"3000",
"--host", "localhost",
"--allow-http",
"--static-oauth-client-info",
"{\"client_id\":\"YOUR_CLIENT_ID\",\"client_secret\":\"YOUR_CLIENT_SECRET\"}"
]
}
}
}
Why these arguments are used:
• command ('npx.cmd'): Uses Windows Node package runner without requiring global installation.
• '--yes' & '--refresh': Confirms prompts automatically and pulls the freshest bridge package.
• 'mcp-remote': The bridge translating Claude's local commands into HTTP requests.
• '<mcp server uri>': The target protected MCP server URL (e.g., http://localhost:9092/mcp).
• '3000' & '--host localhost': Binds the local callback port securely to your loopback interface.
• '--static-oauth-client-info': Passes client credentials to authenticate before calling HOD.
3. Save the file and restart Claude Desktop. The hammer icon in Claude will indicate that your HOD tools are connected!
This is how Claude desktop looks like after successful connection with MCP server