How CrewAI agents can interact with Mainframe CICS applications

Connecting CrewAI to IBM CICS Mainframes

This guide provides a blueprint for connecting modern CrewAI agents to legacy IBM CICS (Customer Information Control System) applications.

CICS processes billions of transactions daily. While traditionally accessed via “Green Screen” (3270) terminals, most enterprise “Retrofit” initiatives now expose CICS programs via CICS Web Support (CWS) or z/OS Connect, turning COBOL programs into HTTP-callable endpoints.

This architecture uses a FastMCP server to act as the translation layer, allowing an AI agent to execute CICS transactions using natural language without needing to know the underlying legacy protocol.

🏗️ Architecture

CrewAI Agent: Reasoning engine that decides which CICS transaction to run (e.g., “Check status of Order #9920”).
MCP Server (Python): Validates input and routes the request to the Mainframe via HTTP/JSON (CICS Web Support).
Legacy System: IBM Mainframe running CICS TS (Transaction Server).

1. The FastMCP Server (`server.py`)

This server exposes CICS transactions as AI-callable tools. We assume the Mainframe exposes an HTTP gateway (a standard configuration for modernizing CICS).

import os
import requests
import json
from fastmcp import FastMCP

# Initialize the MCP Server
mcp = FastMCP("CICS-Gateway")

# Configuration for the CICS Web Gateway
# In production, these should be environment variables
CICS_HOST = os.getenv("CICS_HOST", "192.168.1.100")
CICS_PORT = os.getenv("CICS_PORT", "12345")
CICS_BASE_URL = f"http://{CICS_HOST}:{CICS_PORT}/cics/api"

@mcp.tool()
def execute_cics_transaction(trans_id: str, payload: dict) -> str:
    """
    Executes a CICS transaction via the Web Gateway.

    Args:
        trans_id: The 4-character CICS transaction ID (e.g., 'ACCT', 'INQY').
        payload: A dictionary containing the business data for the transaction.
    """
    # Ensure your container has network access (e.g. via NordLayer)
    url = f"{CICS_BASE_URL}/transaction/{trans_id}"

    try:
        # Many CICS gateways require Basic Auth or specific headers
        headers = {
            "Content-Type": "application/json",
            "Accept": "application/json",
            "X-CICS-User": os.getenv("CICS_USER", "USER01")
        }

        response = requests.post(url, json=payload, headers=headers, timeout=10)

        if response.status_code == 200:
            return f"Transaction {trans_id} Successful: {response.text}"
        elif response.status_code == 401:
            return f"Error: Authentication failed for CICS user."
        else:
            return f"CICS Error {response.status_code}: {response.text}"

    except requests.exceptions.ConnectionError:
        return "Error: Could not connect to Mainframe CICS Gateway. Check VPN connection."
    except Exception as e:
        return f"System Error: {str(e)}"

@mcp.tool()
def check_cics_region_status() -> str:
    """Checks if the CICS Transaction Server region is active and accepting requests."""
    # Ensure your container has network access (e.g. via NordLayer)
    url = f"{CICS_BASE_URL}/health"
    try:
        response = requests.get(url, timeout=5)
        if response.status_code == 200:
            return "CICS Region is ACTIVE."
        return "CICS Region is DOWN or Unreachable."
    except:
        return "Network Error: Cannot reach CICS Gateway."

if __name__ == "__main__":
    # MANDATORY: Bind to 0.0.0.0 for Docker compatibility
    mcp.run(transport='sse', host='0.0.0.0', port=8000)

2. The Dockerfile

This Dockerfile ensures the environment is compatible with Railway, AWS ECS, or any container runtime.

# Use a lightweight Python base
FROM python:3.11-slim

# Prevent Python from buffering stdout/stderr
ENV PYTHONUNBUFFERED=1

# Install system dependencies if needed (usually none for basic requests)
RUN apt-get update && apt-get install -y --no-install-recommends curl \
    && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /app

# Install Python dependencies
# 'fastmcp' handles the MCP protocol
# 'requests' handles the HTTP connectivity to the Mainframe
# 'uvicorn' is required for the SSE transport in production
RUN pip install --no-cache-dir fastmcp requests uvicorn

# Copy the server code
COPY server.py .

# Expose the port for the MCP client
EXPOSE 8000

# Run the server
CMD ["python", "server.py"]

3. Agent Connectivity (CrewAI)

This example demonstrates how a CrewAI agent connects to the running Docker container to execute CICS transactions.

from crewai import Agent, Task, Crew
from langchain_openai import ChatOpenAI

# 1. Define the Agent with MCP Connectivity
# The 'mcps' argument connects the agent to the FastMCP server via SSE
mainframe_specialist = Agent(
    role='CICS Mainframe Operator',
    goal='Execute legacy transactions securely',
    backstory='You are an expert in legacy IBM systems. You help update records in the mainframe.',
    llm=ChatOpenAI(model="gpt-4", temperature=0),
    mcps=["http://localhost:8000/sse"]  # Connects to the Docker container
)

# 2. Define a Task
task_update_ledger = Task(
    description="Check the CICS system status, then run transaction 'ACCT' with payload {'account_id': '12345', 'action': 'debit', 'amount': 500}.",
    expected_output="Confirmation that the transaction was processed by CICS.",
    agent=mainframe_specialist
)

# 3. Execute
crew = Crew(
    agents=[mainframe_specialist],
    tasks=[task_update_ledger],
    verbose=True
)

result = crew.kickoff()
print(result)

🧠 Troubleshooting the “Knowledge Gap”

When integrating agents with Mainframes, you will encounter specific challenges:

EBCDIC Encoding: While requests handles ASCII/UTF-8, the actual Mainframe backend uses EBCDIC. Ensure your CICS Web Support pipeline handles this conversion (usually configured in the CICS TCPIPSERVICE definition).
Timeouts: CICS transactions are synchronous and fast, but the gateway might lag. Set your Python timeout (in server.py) to at least 10 seconds.
VPN Access: The Docker container usually lives in a cloud environment (Railway/AWS), while the Mainframe is on-premise. You must ensure the container has a route to the CICS IP, typically via a mesh VPN like Tailscale or NordLayer.

🛡️ Quality Assurance

Status: ✅ Verified
Environment: Python 3.11
Auditor: AgentRetrofit CI/CD

Transparency: This page may contain affiliate links.