MCP server — connect any AI client

OculiX ships an MCP server (oculixmcp) that exposes the visual-automation engine — click, type, find, OCR, screenshot — to any Model Context Protocol client. Every action is signed (Ed25519) and written to a hash-chained audit journal, so the server is built for controlled, auditable environments rather than free-form consumer use.

Start the server

The runnable artifact is oculix-mcp-server.jar. Two transports:

stdio (local clients)
HTTP (Streamable)

# Default transport — used by Claude Desktop, Cursor, VS Code, Gemini CLI…
java -jar oculix-mcp-server.jar run

# Binds to loopback by default. --host / --port are optional.
java -jar oculix-mcp-server.jar serve --host 127.0.0.1 --port 7337

Environment variables:

Variable	Effect
`OCULIX_MCP_TOKEN`	Pre-shared client token gating `initialize` (recommended for any non-loopback bind)
`OCULIX_MCP_MODE`	`open` or `confidential` — confidential mode lands sensitive output in a vault dir
`OCULIX_MCP_VAULT`	Path of the confidential landing directory
`OCULIX_MCP_TRUST_TLS_TERMINATION`	Acknowledge upstream TLS for non-loopback binds (otherwise plain HTTP on a public interface is refused)

Audit / key management: verify, rotate-key, rotate-session-key, recover.

Connect your client

Almost every MCP client uses one of four config shapes. Pick your client below.

File: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "oculix": {
      "command": "java",
      "args": ["-jar", "/absolute/path/oculix-mcp-server.jar", "run"]
    }
  }
}

Restart Claude Desktop. The tools appear behind the MCP indicator.

Project file .mcp.json, or:

claude mcp add oculix -- java -jar /absolute/path/oculix-mcp-server.jar run

File: ~/.cursor/mcp.json (global) · .cursor/mcp.json (project)

{
  "mcpServers": {
    "oculix": {
      "command": "java",
      "args": ["-jar", "/absolute/path/oculix-mcp-server.jar", "run"]
    }
  }
}

File: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "oculix": {
      "command": "java",
      "args": ["-jar", "/absolute/path/oculix-mcp-server.jar", "run"]
    }
  }
}

File: ~/.gemini/settings.json (or project .gemini/settings.json)

{
  "mcpServers": {
    "oculix": {
      "command": "java",
      "args": ["-jar", "/absolute/path/oculix-mcp-server.jar", "run"]
    }
  }
}

File: .vscode/mcp.json — note the top-level key is servers, not mcpServers.

{
  "servers": {
    "oculix": {
      "command": "java",
      "args": ["-jar", "/absolute/path/oculix-mcp-server.jar", "run"]
    }
  }
}

File: settings.json — Zed uses the context_servers key.

{
  "context_servers": {
    "oculix": {
      "command": "java",
      "args": ["-jar", "/absolute/path/oculix-mcp-server.jar", "run"],
      "env": {}
    }
  }
}

File: ~/.config/goose/config.yaml — YAML, and the field is cmd (not command). Easiest path is the wizard: goose configure → Add Extension → Command-line (stdio).

extensions:
  oculix:
    enabled: true
    type: stdio
    cmd: java
    args:
      - "-jar"
      - "/absolute/path/oculix-mcp-server.jar"
      - "run"

Drive the server from your own code over stdio or Streamable HTTP. The SDK accepts a Bearer token, so OculiX’s HTTP mode works directly:

# Pseudocode — point the SDK at the HTTP transport
server_url = "http://127.0.0.1:7337/mcp"
headers = {"Authorization": f"Bearer {OCULIX_MCP_TOKEN}"}

The vast majority of MCP clients use the mcpServers shape shown above (Claude Desktop / Cursor / Windsurf / Gemini). Point command at java, args at your jar plus run for stdio, or connect to the HTTP endpoint http://host:7337/mcp with a Bearer token.

A note on consumer cloud assistants (ChatGPT, etc.)

You cannot add the OculiX server to a consumer ChatGPT account as a connector, and that is on purpose.

A visual-automation server can move the mouse, type, and read the screen — it is, by definition, a remote-control surface. Wiring it to a third-party cloud assistant would turn the host machine into a backdoor reachable by anyone who controls that assistant account — a phished login, a hijacked session, a compromised browser. We refuse that exposure by design:

Loopback-first — the server binds to 127.0.0.1 by default. A cloud service has no route to your localhost.
No OAuth Dynamic Client Registration — consumer ChatGPT connectors require OAuth 2.1 + DCR and reject Bearer tokens. OculiX deliberately does not implement that flow, so a public connector cannot register itself.
TLS enforced on public interfaces — binding plain HTTP on a non-loopback address is refused unless the operator explicitly acknowledges upstream TLS.

Drive OculiX locally, or from your own audited gateway — never from a third-party cloud assistant. The initialize handshake states this posture in-band, so any client or auditor sees it immediately.

Exposed tools

Ten tools in the default (open) mode:

Tool	Does
`oculix_find_image`	Locate an image on screen
`oculix_click_image`	Find an image, then click it
`oculix_click_at_point`	Click at explicit coordinates
`oculix_exists_image`	Test whether an image is present (no failure thrown)
`oculix_wait_for_image`	Wait for an image to appear
`oculix_type_text`	Type a string
`oculix_key_combo`	Send a key combination (e.g. `Ctrl+S`)
`oculix_find_text`	Locate text on screen via OCR
`oculix_screenshot`	Capture the screen
`oculix_read_text_in_region`	OCR a region and return the text

Every call is gated (ActionGate), signed with Ed25519, and appended to a SHA-256-chained JSONL journal you can replay and verify with oculix-mcp-server.jar verify.

CLI reference All oculix-mcp subcommands and flags.