> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metaphi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Compile and run a COBOL job, read the result, and break it on purpose.

## 1. Connect

Add `https://harwell.metaphi.ai/mcp/` to your MCP client and sign in. See [Connect an MCP server](https://docs.metaphi.ai/account/mcp.md). You need `harwell:runs:write`.

## 2. Write a unit

A unit is a directory in a mainframe codebase's own shape, plus a `run.json` that says what to run.

```text theme={"dark"}
hello/
  Progs/HELLO.cbl
  Procs/HELLOJOB.jcl
  run.json
```

`Progs/HELLO.cbl`:

```cobol theme={"dark"}
       IDENTIFICATION DIVISION.
       PROGRAM-ID. HELLO.
       PROCEDURE DIVISION.
           DISPLAY 'HELLO FROM THE SANDBOX'.
           STOP RUN.
```

`Procs/HELLOJOB.jcl`:

```text theme={"dark"}
//HELLOJOB JOB
//STEP01   EXEC PGM=HELLO
//SYSOUT   DD SYSOUT=*
```

`run.json`:

```json theme={"dark"}
{"submit": ["HELLOJOB"]}
```

`submit` names the deck by its file stem in `Procs/`. The deck runs program `HELLO`, found by its `PROGRAM-ID`.

## 3. Run it

Ask your agent: "Run the hello unit with Harwell." It calls `run_unit` with the directory:

```json theme={"dark"}
run_unit {"unit_zip_b64": "<the hello directory, zipped and base64-encoded>"}
```

`unit_zip_b64` is the directory as a base64 zip. Hum packs a directory path for you. In any other client, the agent runs:

```sh theme={"dark"}
cd hello && zip -qr - . | base64
```

## 4. Read the result

```text theme={"dark"}
HELLOJOB ok · STEP01 HELLO rc=0
JOB HELLOJOB  [ok]
  STEP01   HELLO   cobol   ran   RC=0   ran; 0 out DD(s)
--- HELLOJOB STEP01 HELLO · DISPLAY ---
HELLO FROM THE SANDBOX
```

The first line is the verdict. Then comes the job log, one line per step, and what each step displayed. The result also carries:

* `structuredContent`: the same result as JSON: `status`, `verdict`, `diagnostics`, and every job and step with its return code.
* Resource links to `report.json`, every listing and every spool file. Read one with `resources/read` when the text is not enough.

A step that ran reads `ran` or `ok`. Anything else failed, and the call is a tool error.

## 5. Break it

Change `HELLO.cbl` to use a name it never declares:

```cobol theme={"dark"}
           DISPLAY WS-GREETING.
```

Run it again. The result opens with the compiler's first error, at the line in your tree, and the call is a tool error:

```text theme={"dark"}
Progs/HELLO.cbl:4: error: 'WS-GREETING' is not defined
```

Fix the line and run again.

## Next

* [Run a batch job](https://docs.metaphi.ai/harwell/guides/batch-jobs.md): data sets, SORT, and chains of jobs.
* [Tools](https://docs.metaphi.ai/harwell/tools.md): every tool and its parameters.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.