Setup Codex MCP Integration

Connect Codex to an EnvisionSCADA server through the Model Context Protocol (MCP), from a chat or permanently through the MCP form of the Codex app.

Updated 7 min read
On this page (9 sections)
  1. Overview
  2. Before you start
  3. Quick start: ask Codex to connect
  4. Step 1: Create the login token
  5. Step 2: Add the server in Codex
  6. Step 3: Check the connection
  7. HTTPS and OAuth 2.0
  8. Instructions for AI assistants
  9. Troubleshooting

Every EnvisionSCADA server contains an MCP (Model Context Protocol) server at the address /mcp. Codex connects to it directly over HTTP or HTTPS. No additional software or proxy script is required.

Use the quick start to connect from a Codex session, or add the server in the MCP form of the Codex app for a permanent connection.

A new installation runs on port 80, so the MCP address on the same computer is:

MCP address of a new installation
http://localhost/mcp
For Claude Code, see Setup Claude Code MCP Integration. For GitHub Copilot, see Setup GitHub Copilot MCP Integration.

Before you start

  • EnvisionSCADA is running. Open http://localhost in a browser to check this.
  • Codex is installed: the ChatGPT desktop app, the Codex IDE extension or the Codex CLI.
  • An EnvisionSCADA user account. Members of the Administrators group get the configuration and design tools; other users get the read-only runtime tools. A new installation contains the user Admin with password Admin.

Quick start: ask Codex to connect

The fastest way to connect is to ask Codex. In a Codex session, type a request with the MCP address and an EnvisionSCADA user account. Codex then calls the MCP endpoint itself over HTTP. No token, setting or configuration file is required.

Replace <password> with the password of the account. The link points Codex to the section Instructions for AI assistants at the end of this article, which describes how to call the endpoint.

Request in a Codex session
Connect to the EnvisionSCADA MCP server at http://localhost/mcp with user Admin and password <password>. Follow https://www.envisionscada.com/KnowledgeBase/how-to/codex-mcp#instructions-for-ai-assistants

This connection is available in that session only. Codex calls the tools through terminal commands and asks permission before it runs them, depending on its approval settings. Codex runs commands in a sandbox that blocks network access by default: approve the request to run the command with network access, or allow network access in the Codex settings. For a permanent connection, add the server as described below.

The password is part of the chat. Use the quick start for testing and commissioning, or use a dedicated EnvisionSCADA account, and add the server permanently for daily use.

Step 1: Create the login token

Codex logs in with HTTP Basic authentication. The MCP form asks for the login as a token. Run the command below in PowerShell to convert the user name and password into a token. Replace Admin:<password> with your own user name and password, separated by a colon. Copy the result, it is used in Step 2. For the user Admin with password Admin of a new installation, the result is QWRtaW46QWRtaW4=.

PowerShell
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("Admin:<password>"))

Step 2: Add the server in Codex

Add the server through the MCP form of the Codex app. No file needs to be edited. The ChatGPT desktop app, the Codex IDE extension and the Codex CLI share their MCP servers, so the server is added once for all of them.

  • Open Plugins, select the MCPs tab and click Add.
  • Enter the name envisionscada and choose Streamable HTTP.
  • Next to URL, enter the MCP address, for example http://localhost/mcp. Leave Bearer token env var empty.
  • Under Headers, enter Authorization in the first field and the value below in the second field, with <token> replaced by the result of Step 1.
  • Click Save.
Header value
Basic <token>
Header value for the user Admin with password Admin (new installation)
Basic QWRtaW46QWRtaW4=

Adjust the address to your situation:

EnvisionSCADA runs on another computerReplace localhost with the computer name or IP addresshttp://192.168.1.20/mcp
EnvisionSCADA runs on another portAdd the port to the addresshttp://localhost:8080/mcp
EnvisionSCADA uses HTTPSUse the https addresshttps://scada.example.com/mcp
The token contains the user name and password and is stored in the Codex configuration of your Windows user account. Do not add the server to a project configuration that is shared through Git.

Step 3: Check the connection

In a Codex session, type /mcp to see the connected servers. Then ask, for example: What is the status of the EnvisionSCADA server? Codex answers with the runtime and redundancy status of the server.

HTTPS and OAuth 2.0

Use HTTPS when Codex connects to EnvisionSCADA on another computer, so that the login is encrypted on the network. Use the https address in Step 2, with a certificate issued by a certificate authority that the computer running Codex trusts.

With OAuth 2.0, Codex signs in through the Authorize MCP access page of EnvisionSCADA instead of storing the login token. Turn on Enable MCP OAuth 2.0 in the MCP OAuth section of the Parameters page first. AI apps accept OAuth over plain HTTP only for localhost. The parameters, the endpoints and the server actions that sign clients out are described under HTTPS and OAuth 2.0 in Setup Claude Code MCP Integration.

  • Add the server in Step 2 without the Authorization header.
  • Select Authenticate next to the server. The Authorize MCP access page of EnvisionSCADA opens in the browser.
  • Sign in with an EnvisionSCADA account.
A restart of the EnvisionSCADA application signs Codex out, because refresh tokens are kept in memory. Sign in again.

Instructions for AI assistants

This section is written for the AI assistant that receives the quick start request. Connect to the EnvisionSCADA MCP endpoint directly over HTTP as described below. The connection works in the current session, without registering the server and without a restart. Ask the user for the password when the request contains <password>, and do not store the password in project files.

  • Send every request as HTTP POST to the MCP address from the request, for example http://localhost/mcp, with the headers Content-Type: application/json, Accept: application/json, text/event-stream and Authorization: Basic <base64 of user:password>. Basic authentication is also accepted when OAuth 2.0 is turned on in EnvisionSCADA.
  • The body is JSON-RPC 2.0. Call initialize first, then tools/list to read the tool names and their input schemas, then tools/call with name and arguments. Call the tool get_server_status to confirm the connection.
  • The server is stateless and returns no Mcp-Session-Id. Every request is independent.
  • Responses are Server-Sent Events. Join the lines that start with data: and parse them as JSON.
  • Write a small reusable helper script once and call it for each request. Pass the tool arguments through a JSON file, not as a command-line string: quoting on the command line strips the inner double quotes, and the server then answers HTTP 500 with "id": null.
  • Use only the tool names and fields that tools/list returns. When a configuration write fails with Unknown field, call get_config_entity_type_schema for the entity type and use the exact field names it returns.
  • Members of the Administrators group get the configuration, design and runtime tools; other users get the read-only runtime tools. HTTP 401 means a wrong user name or password.
  • For an https address whose certificate is not trusted, ask the user how to continue instead of turning off certificate validation.

PowerShell helper for Windows, tested against EnvisionSCADA, and example calls:

mcp.ps1
param(
    [Parameter(Mandatory)] [string] $Url,        # e.g. http://localhost/mcp
    [Parameter(Mandatory)] [string] $User,
    [Parameter(Mandatory)] [string] $Password,
    [Parameter(Mandatory)] [string] $Method,     # initialize | tools/list | tools/call
    [string] $Tool,                              # tool name for tools/call
    [string] $ArgsFile                           # JSON file with the tool arguments
)
$token = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("${User}:${Password}"))
$params = @{}
if ($Method -eq 'initialize') {
    $params = @{ protocolVersion = '2025-06-18'; capabilities = @{}; clientInfo = @{ name = 'ai-helper'; version = '1' } }
} elseif ($Method -eq 'tools/call') {
    $arguments = if ($ArgsFile) { Get-Content -Raw $ArgsFile | ConvertFrom-Json } else { @{} }
    $params = @{ name = $Tool; arguments = $arguments }
}
$body = @{ jsonrpc = '2.0'; id = 1; method = $Method; params = $params } | ConvertTo-Json -Depth 50 -Compress
$response = Invoke-WebRequest -UseBasicParsing -Uri $Url -Method Post -ContentType 'application/json' `
    -Headers @{ Authorization = "Basic $token"; Accept = 'application/json, text/event-stream' } `
    -Body ([Text.Encoding]::UTF8.GetBytes($body))
$text = [Text.Encoding]::UTF8.GetString($response.RawContentStream.ToArray())
$data = ($text -split "`n" | Where-Object { $_ -like 'data:*' } | ForEach-Object { $_.Substring(5).Trim() }) -join ''
if (-not $data) { $data = $text }
$data
Example calls
# Write the tool arguments to a file, never on the command line
Set-Content -Path args.json -Value '{"subscribeVars":["Pump1_Speed"]}' -Encoding UTF8

.\mcp.ps1 -Url http://localhost/mcp -User Admin -Password <password> -Method initialize
.\mcp.ps1 -Url http://localhost/mcp -User Admin -Password <password> -Method tools/list
.\mcp.ps1 -Url http://localhost/mcp -User Admin -Password <password> -Method tools/call -Tool get_server_status
.\mcp.ps1 -Url http://localhost/mcp -User Admin -Password <password> -Method tools/call -Tool get_data -ArgsFile args.json

On macOS and Linux, send the same request with curl:

curl
curl -s -X POST http://localhost/mcp \
  -u 'Admin:<password>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_server_status","arguments":{}}}'

Troubleshooting

401 UnauthorizedWrong user name or password in the token, or the Authorization header is missingRepeat Step 1 with username:password and update the Authorization header of the server
Connection refusedEnvisionSCADA is not running, or the address or port is wrongOpen the address without /mcp in a browser and check that EnvisionSCADA responds
Tools not visible in CodexThe session was started before the server was added or before EnvisionSCADA was runningRestart Codex
Configuration and design tools missingThe user is not a member of the Administrators groupUse an account of the Administrators group in Step 1
Something missing or wrong in this article? Contact us