IBM Z

You deploy this MCP server to connect IBM Z mainframe capabilities with Claude Code, enabling envelope encryption through Key Protect and REST access to mainframe programs via z/OS Connect. This server provides enterprise-grade security and modern mainframe integration, making it easier to manage keys and expose mainframe services to cloud applications and AI workflows.

How to use

You run the MCP server locally or in your development environment and connect it to your cloud Key Protect instance and your z/OS Connect service. The server exposes Key Protect operations for envelope encryption and z/OS Connect operations to call mainframe programs over REST. You interact with the server through the configured environment and let Claude Code orchestrate the workflows that involve Key Protect keys and mainframe services.

How to install

Follow these concrete steps to install and start the MCP server.

cd ~/ibmz-mcp-server
npm install

Configuration and usage notes

Configure the environment variables required by the MCP server as shown in the setup example. The server needs credentials for Key Protect and the z/OS Connect endpoint if you intend to reach the mainframe REST APIs. The example configuration adds the MCP server as a stdio process that runs the Node.js implementation from its index file and passes the necessary environment variables.

{
  "mcpServers": {
    "ibmz": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/matthewkarsten/ibmz-mcp-server/index.js"],
      "env": {
        "IBM_CLOUD_API_KEY": "your-api-key",
        "KEY_PROTECT_INSTANCE_ID": "your-instance-id"
      }
    }
  }
}

Security and prerequisites

Prerequisites include having Node.js installed and access to IBM Cloud Key Protect and a z/OS Connect-enabled mainframe. Ensure you store sensitive credentials securely and rotate root keys per your organization’s policy. The MCP server integrates envelope encryption, where root keys (KEK) reside in the HSM and data encryption keys (DEK) are wrapped before storage.

Demo and testing scripts

Run the provided demo and test scripts to verify the integration and capabilities. The scripts exercise the complete stack, including NLU workflows, key protection, and data storage interactions.

# Set environment for demos
export IBM_CLOUD_API_KEY="your-key"
export KEY_PROTECT_INSTANCE_ID="your-instance-id"

# Full 5-service pipeline test
node demo-full-stack.js

# End-to-end workflow test
node demo-e2e-workflow.js

# Envelope encryption test
node test-envelope-encryption.js

# Watson services suite test
node demo-watson-suite.js

Available tools

key_protect_list_keys

List encryption keys in Key Protect

key_protect_create_key

Create root or standard keys

key_protect_get_key

Get key details and metadata

key_protect_wrap_key

Wrap (encrypt) DEKs with a root key

key_protect_unwrap_key

Unwrap (decrypt) wrapped DEKs

key_protect_rotate_key

Rotate a root key

key_protect_delete_key

Delete a key (irreversible)

key_protect_get_key_policies

Get key policies

zos_connect_list_services

List available mainframe services

zos_connect_get_service

Get service details and OpenAPI spec

zos_connect_call_service

Call a mainframe service via REST

zos_connect_list_apis

List API requester configurations

zos_connect_health

Check z/OS Connect server health