Endevor-MCP v1.0.0

A Model Context Protocol (MCP) server providing 43 tools for complete Broadcom Endevor SCM interaction via the REST API v2. Built for AI-driven mainframe operations — inventory browsing, element lifecycle management, package workflows, and security-focused source code review.

Endevor-MCP + hack3270: Source-Informed Mainframe Penetration Testing

Endevor-MCP becomes exceptionally powerful when paired with hack3270 (52 MCP tools for TN3270 data stream manipulation). Together they give a single AI agent 95 tools — the ability to read every line of source code behind a mainframe application and operate the live application simultaneously. This is a fundamentally different class of testing capability.

Why This Matters

Mainframe CICS applications were architected in the 1980s-2000s around a trust model that no longer holds: the 3270 terminal was the security boundary. Field protection, numeric-only restrictions, field length limits, hidden fields, and screen flow control were all enforced by the terminal hardware — not the server. The COBOL programs behind these screens routinely accept MAP input and use it directly in arithmetic, SQL queries, file access, and transaction routing without any server-side validation.

hack3270 breaks this trust model. It intercepts the TN3270 data stream and lets you modify protected fields, send non-numeric data to numeric fields, overwrite hidden fields, bypass screen flow, and send arbitrary AID keys — none of which a real 3270 terminal would allow.

But without source code, hack3270 testing is blind. You can fuzz fields and watch for crashes, but you don't know why a field is vulnerable, what the server does with your input, or where the real attack surface is. You're guessing.

Endevor-MCP eliminates the guessing. With access to the Endevor source code repository, the AI agent can:

• Read the BMS map to know every field on every screen — including hidden dark fields, protected fields, and their expected data formats — before touching the live application
• Read the COBOL program to see exactly what happens after EXEC CICS RECEIVE MAP: which fields are validated, which are trusted blindly, which go directly into EXEC SQL statements, which control transaction routing
• Read the copybooks to know the PIC clause of every field — the difference between PIC X(10) (alphanumeric) and PIC S9(7)V99 COMP-3 (packed decimal that will SOC7 abend on invalid data)
• Read the JCL to understand batch job structures, dataset naming conventions, STEPLIB concatenations, and find hardcoded credentials — intelligence that becomes immediately actionable if TSO escape is achieved
• Trace program flow through EXEC CICS LINK and EXEC CICS XCTL chains to find authorization bypasses where a sensitive program can be invoked directly, skipping the security check in the calling program
• Review change history to prioritize testing on recently modified code — new code has new bugs

The result: instead of blind fuzzing with hack3270, the AI agent performs surgical, source-informed exploitation. It reads the COBOL source, identifies that ORDQTYI goes directly into a COMPUTE with no IS NUMERIC check, then uses hack3270's send_field_data() to send alphabetic characters to that field and trigger the SOC7 abend. It reads the EVALUATE EIBAID block, discovers PA1 invokes an undocumented admin menu, then uses hack3270's send_aid_key() to access it. Every finding from source code can be proven live, and every live anomaly can be traced back to its root cause in the code.

This transforms mainframe application penetration testing from a slow, uncertain process into a systematic, comprehensive assessment covering 19 distinct vulnerability classes across COBOL, BMS, copybooks, JCL, DB2, VSAM, CICS, and batch processing.

Author

Garland Glessner — gglessner@gmail.com

License

GNU General Public License v3.0 — see LICENSE

Features

• 43 MCP tools covering the complete Endevor REST API v2

• Full inventory browsing: Datasources, environments, stages, systems, subsystems, types, elements, members

• Element lifecycle management:

  • Add, Update, Retrieve, Print, Generate, Move, Delete
  • Sign-in / Sign-out for element locking
  • Transfer across inventory locations
  • Component dependency analysis (ACM)

• Package workflow management:

  • Create, Update, Cast, Approve, Deny, Execute, Submit
  • Commit, Reset, Backout, Backin, Delete

• Async task management: List, check status, and retrieve results of long-running operations

• SCL submission: Execute arbitrary Software Control Language statements

• Fingerprint validation: Optimistic concurrency control

• Auto-connect via environment variables: Configure ENDEVOR_* env vars in mcp.json — the server connects with Basic Auth, obtains a JWT, and is ready immediately (no manual endevor_connect needed)

• Authentication support:

  • Auto-auth via env vars (Basic Auth -> JWT on startup)
  • HTTP Basic Auth (username/password)
  • Bearer Token (JWT)
  • JWT acquisition via Endevor /auth endpoint
  • Mutual TLS (mTLS) with client certificates

• TLS/SSL support: Custom CA certs, client certs, verification bypass for test environments

• Security assessment ready: Purpose-built workflows for mainframe source code review and vulnerability analysis

Quick Start

1. Clone and install

git clone https://github.com/gglessner/Endevor-MCP.git
cd Endevor-MCP
pip install -r requirements.txt

2. Open in Cursor

Open the Endevor-MCP directory as your project in Cursor. Everything is pre-configured:

• .cursor/mcp.json — auto-registers the MCP server (43 tools)
• .cursor/skills/endevor-mcp/SKILL.md — teaches the AI assistant all tools and workflows

No manual setup needed. See MCP_SETUP.md for VS Code and advanced configurations.

3. Configure credentials

Edit .cursor/mcp.json with your Endevor instance details:

{
  "mcpServers": {
    "endevor-mcp": {
      "command": "python",
      "args": ["run_endevor_mcp.py"],
      "cwd": "${workspaceFolder}",
      "env": {
        "ENDEVOR_HOST": "mainframe.example.com",
        "ENDEVOR_PORT": "443",
        "ENDEVOR_DATASOURCE": "ENDVCONF",
        "ENDEVOR_USERNAME": "USER01",
        "ENDEVOR_PASSWORD": "secret"
      }
    }
  }
}

The server auto-connects with Basic Auth, obtains a JWT bearer token, and all 43 tools are immediately ready using conn_id="auto".

Manual connect (alternative — if env vars are not configured):

endevor_connect(host="mainframe.example.com", port=443,
                datasource="ENDVCONF",
                username="USER01", password="secret")

Tool Reference (43 tools)

Connection Management (3 tools)

Authentication & Health (3 tools)

Async Task Management (3 tools)

Inventory / List Tools (8 tools)

Element Actions (11 tools)

Package Actions (13 tools)

SCL & Fingerprint (2 tools)

Endevor Inventory Hierarchy

Datasource (configuration — points to an Endevor instance)
└── Environment (DEV, QA, PROD, ...)
    └── Stage Number (1, 2, ...)
        └── System (FINANCE, HR, PAYMENTS, ...)
            ├── Subsystem (ACCTS, PAYROLL, CLAIMS, ...)
            │   └── Element (PAYCALC, EMPRPT, CUSTMNT, ...)
            └── Type (COBOL, COPYBOOK, JCL, ASMPGM, PLI, BMS, ...)

Common Element Types

Type names vary by installation. Use endevor_list_types to discover what's configured.

Architecture

Endevor-MCP/
├── .cursor/
│   ├── mcp.json                    # Auto-registers MCP server with env var auth
│   └── skills/
│       └── endevor-mcp/
│           ├── SKILL.md            # Core skill — 43 tools, auth, workflows
│           ├── mainframe-security.md   # 19 vulnerability classes with COBOL patterns
│           └── security-checklist.md   # Review checklist + hack3270 cross-reference
├── endevor_mcp/
│   ├── __init__.py                 # Package metadata
│   ├── client.py                   # HTTP REST client & connection manager
│   └── server.py                   # FastMCP server with 43 tools + auto-connect
├── run_endevor_mcp.py              # Entry point
├── requirements.txt                # Dependencies
├── MCP_SETUP.md                    # Setup guide for Cursor & VS Code
├── README.md                       # This file
└── LICENSE                         # GPL v3

HTTP REST Client (client.py)

Thread-safe persistent HTTP session management:

• requests-based HTTP client with connection pooling
• Basic Auth and Bearer Token authentication
• Full TLS configuration (custom CA, mTLS, verification bypass)
• Automatic datasource path prefixing
• JWT token acquisition via Endevor /auth endpoint

MCP Server (server.py)

FastMCP server with 43 registered tools organized by category:

• Connection management and authentication
• Async task management for long-running operations
• Inventory browsing with wildcard support
• Element lifecycle operations (multipart/form-data for content upload)
• Package workflow management (JSON body)
• SCL submission and fingerprint validation
• Intelligent response parsing with structured output

Authentication Quick Reference

Package Lifecycle

INEDIT → (cast) → INAPPROVAL → (approve) → APPROVED → (execute) → EXECUTED → (commit) → COMMITTED
                         ↓                       ↓              ↓
                      (deny)                 (reset)        (backout)
                         ↓                       ↓              ↓
                      DENIED                  INEDIT        EXECUTED
                                                            (backin)

Security Assessment Details

19 Vulnerability Classes

The skill documentation covers 19 vulnerability classes applicable to the full field of mainframe application security (see mainframe-security.md for complete details with COBOL source code patterns):

Plus a comprehensive 10-category source code review checklist and a 21-row hack3270 + Endevor-MCP cross-reference table in security-checklist.md.

Parameter Reference

Common Parameters

Change Control Parameters

Search & Filter Parameters

Print Options

Package Statuses

SCL Quick Reference

SCL (Software Control Language) is Endevor's native scripting language, submitted via endevor_submit_scl:

LIST ELEMENT '*'
  FROM ENVIRONMENT 'DEV' SYSTEM 'FINANCE' SUBSYSTEM '*'
       TYPE 'COBOL' STAGE NUMBER 1
  OPTIONS SEARCH .

RETRIEVE ELEMENT 'PAYCALC'
  FROM ENVIRONMENT 'DEV' SYSTEM 'FINANCE' SUBSYSTEM 'ACCTS'
       TYPE 'COBOL' STAGE NUMBER 1
  TO DSN 'USER01.REVIEW.COBOL' MEMBER 'PAYCALC'
  OPTIONS CCID 'REVIEW01' COMMENT 'Security review' .

MOVE ELEMENT 'PAYCALC'
  FROM ENVIRONMENT 'DEV' SYSTEM 'FINANCE' SUBSYSTEM 'ACCTS'
       TYPE 'COBOL' STAGE NUMBER 1
  OPTIONS CCID 'REL21' COMMENT 'Release 2.1' .

Requirements

• Python 3.9+
• mcp[cli] >= 1.0.0 (MCP framework)
• requests >= 2.31.0 (HTTP client)
• urllib3 >= 2.0.0

Target API

• Endevor REST API v2 (version 2.26)
• Compatible with Endevor 18.0, 18.1, and 19.0