tn5250-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| T5250_JAVA | No | Path to Java. Default: found automatically (Java 11+). | |
| T5250_PACE | No | Seconds to wait between flow steps. Default: 0 (no wait). | 0 |
| T5250_PORT | No | Port for HTTP transport (path /mcp). Default: 8250. | 8250 |
| T5250_BLOCK | No | Comma-separated extra block regexes. Default: none extra. | |
| T5250_FLOWS | No | Colon-separated paths to flow files or directories. Default: none. | |
| T5250_JT400 | No | Path to jt400.jar. Default: no SQL/IFS tools. | |
| T5250_LOG_DIR | No | Directory for transcript logs. Default: no logs. | |
| T5250_CODEPAGE | No | Default codepage. Default: cp037 (also cp273, cp500, cp1140, ...). | cp037 |
| T5250_PROFILES | No | Colon-separated paths to connection profile files or directories. Default: none. | |
| T5250_TOOLSETS | No | Comma-separated toolsets to enable. Default: all. | |
| T5250_READ_ONLY | No | Set to 1 to enable read-only mode. Default: 0 (off). | 0 |
| T5250_TRANSPORT | No | Transport protocol: stdio or http. Default: stdio. | stdio |
| T5250_FLOWS_ONLY | No | Set to 1 to offer only flows (no free typing). Default: 0 (off). | 0 |
| T5250_RECORD_DIR | No | Directory to save recorded flows. Default: recordings are returned, not saved. | |
| T5250_ALLOW_SHELL | No | Set to 1 to allow pase. Default: 0 (off). | 0 |
| T5250_NO_REMEMBER | No | Set to 1 to hide the remember-password checkbox. Default: 0 (checkbox shown when keyring is installed). | 0 |
| T5250_VIEWER_PORT | No | Viewer port. Default: 8251 (a free port if taken); 0 = off. | 8251 |
| T5250_VIEWER_TOKEN | No | Viewer token. Default: random per start (set it to keep viewer links valid across restarts). | |
| T5250_ALLOWED_HOSTS | No | Comma-separated allowed hostnames. Default: any. | |
| T5250_ALLOW_COMPILE | No | Comma-separated libraries where compile and build_project are allowed; * = any. Default: no compile/build_project. | |
| T5250_COMMAND_ALLOW | No | Comma-separated allowed command patterns. Default: any command (block list still applies). | |
| T5250_PROFILES_ONLY | No | Set to 1 to allow only saved connection profiles. Default: 0 (off). | 0 |
| T5250_REQUIRE_CHECK | No | Set to 0 to disable required screen checks. Default: 1 (checks required). | 1 |
| T5250_ALLOW_COMMANDS | No | Set to 1 to allow run_command and call_program. Default: 0 (off). | 0 |
| T5250_IFS_WRITE_ROOT | No | Colon-separated directories where ifs_write is allowed. Default: no ifs_write. | |
| T5250_ALLOW_SQL_WRITE | No | Set to 1 to allow sql_execute. Default: 0 (off). | 0 |
| T5250_NO_DEFAULT_BLOCKS | No | Set to 1 to disable the default block list. Default: 0 (defaults on). | 0 |
| T5250_ALLOW_MEMBER_WRITE | No | Comma-separated libraries where member_write is allowed; * = any. Default: no member_write. | |
| T5250_RECONNECT_ATTEMPTS | No | Number of reconnect attempts. Default: 10; 0 = off. | 10 |
| T5250_RECONNECT_INTERVAL | No | Seconds between reconnect attempts. Default: 5. | 5 |
| T5250_PASSWORD_CACHE_HOURS | No | Hours to keep saved passwords in memory. Default: 8; 0 = don't keep. | 8 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Drive IBM i (AS/400) 5250 green-screen sessions.
Workflow: connect -> get_screen -> fill / press -> read the screen that press returns.
SQL and IFS tools (sql_query, ifs_list, ifs_read, ...), when offered, work through the IBM i host servers, not the screen: host_connect first. They are faster and exact for reading data; use the screen for applications.
connect with a saved profile ({"profile": name}; list_profiles shows them) when there are any; a profile may sign on by itself after connecting.
Every fill/press must carry
expect(text that must be on the current screen, or "row:text") orscreen_id(from the last screen you read). If the screen changed - because the host moved on or the human typed in the viewer - the call is refused so nothing lands on the wrong screen. Re-read and decide again.Fields are referred to by id ("row,col"), "#index" or label as listed under the screen. Values are placed per the field's rules (right-adjust, signed numbers, uppercase); press sends only fields you changed.
Signing on: never type passwords. Give the user the viewer link (viewer tool) and let them sign on there, then continue. Hidden fields are never shown to you.
keyboard ERROR means an operator error: read the message line, press Reset. keyboard BUSY means the host is still working: call wait.
Other tools may be screen flows defined by the user (whole procedures such as "add an order"). When one fits the task, use it instead of fill/press: it checks every screen on the way and validates its parameters. A flow that needs a password (e.g. a sign-on flow) asks the user for it in the viewer; give them the viewer link first.
If the host drops the connection, the server reconnects by itself; the session then starts over at the sign-on screen. Call wait, then sign on again.
record_start / record_stop turn what you (and the user in the viewer) do on a session into a reusable screen flow (YAML).
press refuses keys a real terminal would refuse (mandatory entry, mandatory fill, wrong check digit) and says which field to fix; nothing is sent then.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| connectA | Open a 5250 session and return the first screen: Sign On, or the screen after the profile's after-connect flow (e.g. a menu once signed on). |
| get_session_logA | The session's transcript: connects, fills (passwords masked), keys, flows, reconnects and recordings, newest last. Useful to retrace what happened, also after a disconnect. |
| forget_passwordA | Forget saved passwords (kept after sign-ons that worked, in memory and, if the user chose so, in the system keychain). The next sign-on asks again. |
| list_profilesA | List the saved connection profiles you can connect with. |
| disconnectA | Sign off (from the command line of the current screen) and close the session. A screen without a command line can't be signed off from; the result says so. |
| list_sessionsA | List open sessions and their state. |
| get_screenA | Read the current screen: text with row/column rulers, cursor, keyboard state, screen_id and the input fields. |
| fillA | Type values into input fields without sending anything to the host. |
| pressA | Send a key to the host (after optional fills) and return the screen the host answers with. Reset only clears an operator error locally. |
| waitA | Wait until the host is waiting for input (and optionally for some text), e.g. after a long-running command or while the user signs on. |
| viewerA | Link to the live web viewer, where the human can watch, sign on or take over. Give it to the user when a password is needed. |
| record_startA | Start recording a screen flow on this session: every key pressed from now on (by you or by the user in the viewer) becomes a step. Passwords are never recorded. Finish with record_stop. |
| record_stopA | Stop recording and return the flow as YAML (saved when the server has a record folder). The flow is available as a tool right away. Review it before relying on it. |
| keysA | List the key names press accepts. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 14 tools
Most tools target distinct actions: connect/disconnect, list_sessions/list_profiles, get_screen/get_session_log all have clear boundaries aided by descriptions. The closest overlap is fill vs press, but fill explicitly types without sending while press sends to host, so they remain distinguishable.
A partial verb_noun convention appears in get_session_log, forget_password, list_profiles, list_sessions, get_screen, record_start, record_stop, but it is broken by bare verbs (connect, fill, press, wait) and bare nouns (viewer, keys). Readable but mixed conventions.
14 tools is well-scoped for a 5250 terminal automation server, covering connection lifecycle, screen interaction, recording, and support tools without excess.
Core terminal workflow is covered: connect, navigate (get_screen, fill, press, wait), session/profile management, recording, and logging. Minor gaps exist around profile creation/editing and recording management (delete/list recordings).