Connect Codex and Claude Code

Connect your local agent to Screengaze: set up the MCP and optionally add the skill that guides recording, editing and exporting.

8 min read

Article contents

What each piece does
Choose your client and app location
Set up through chat
Set up manually
Check each state
Permissions and shared content
After setup
If something does not connect
Sources and verification scope

What each piece does

Screengaze captures, edits and renders in the native Mac app. Its local MCP lets Codex or Claude Code check status and use app tools through a helper bundled with Screengaze.

The included skill teaches the agent the workflow: prepare a take, check status, edit against the current revision, review the result and wait for an export to finish. The MCP works without it; installing it helps the agent use the tools correctly. You do not need to publish it in an official repository.

Choose your client and app location

You need Screengaze on an Apple Silicon Mac, with your chosen client installed on the same Mac. Beta compatibility is still under validation; check the exact versions and validated configurations on each release’s download page. The public Screengaze download is not available yet; this guide applies if you already have a copy of the app containing its helper and skill.

Choose Codex or Claude Code and confirm where Screengaze.app is located. The conventional path is /Applications/Screengaze.app; you can change it if you keep the app elsewhere. Commands and the prompt update with your choice.

You can set everything up through chat or follow the manual steps. Copying a prompt or command only puts text on the clipboard: review it and paste it into your agent or Terminal to run it.

Your client

Absolute Screengaze.app path

This path updates every command and the prompt. Changing it here does not install anything.

Set up through chat

Copy the complete prompt and paste it into a local session of your selected client with Terminal access. It authorizes the agent to register or update only Screengaze and install its personal skill while preserving the rest of your configuration.

The agent should check the app files and existing configuration, avoid duplicate entries and keep a backup before updating a different skill copy. If the client needs a new session, it should give you an exact continuation message and leave the real status query pending until it can run it.

Complete setup for Codex

Set up Screengaze on this Mac for use from Codex, including its MCP and the skill bundled in the application. I authorize you to register or update only Screengaze and install its skill for my user, preserving the rest of my configuration.

Locate Screengaze.app. The path selected in the guide is "/Applications/Screengaze.app"; check it and use the actual absolute path if different. Verify that it contains an executable Contents/Helpers/FrameStudioMCP and Contents/Resources/Automation/skills/screengaze/SKILL.md. Do not invent flags: the helper has no --install option.

Check whether screengaze is already registered using codex mcp get screengaze. Keep a correct configuration and avoid duplicates. Register or update only that integration using Codex's supported mechanism, stdio transport and user scope. For a new entry, the command with the selected path is:
codex mcp add screengaze -- '/Applications/Screengaze.app/Contents/Helpers/FrameStudioMCP'
Codex stores this personal configuration in ~/.codex/config.toml by default; respect any custom location. If the entry exists and differs, back up the configuration and update only [mcp_servers.screengaze].

Install the entire bundled skill folder in ~/.agents/skills/screengaze. If it exists, compare its contents and keep a backup outside skill directories before updating it. No official skill repository publication is required. Invoke it with $screengaze.

Verify registration using:
codex mcp list
codex mcp get screengaze
Also check the helper version and catalogue using --version and --list-tools with its actual path. The catalogue does not prove a connected session. If this conversation needs to reconnect or restart to load the integration, provide instructions and an exact, self-contained continuation message for the new session.

Open Screengaze and guide me to enable “Permitir conexiones MCP locales” under Edición y salida → Integraciones · Agentes, then approve “Permitir sesión” using its normal controls. The app buttons copy commands; they do not run installation. Do not enable frame or transcript sharing yourself. Distinguish client permissions, Screengaze approval and macOS permissions.

Once the tools are available, call only get_status with no arguments. It may return an unauthorized status: if approval is needed, tell me and repeat get_status after “Permitir sesión”. Do not open or modify projects, record or export.

Confirm separately: helper located, MCP registered, skill installed, session authorized and actual status query. Mark anything you could not verify as pending; do not confuse registration or the catalogue with an actual authorized call.

Do not download software or install other clients automatically. If the app, Codex, its CLI or local Terminal access is missing, explain the blocker and the specific next step.

You can also select and copy the text manually.

Set up manually

Follow these seven steps on the Mac where you will use Screengaze. The commands below match your selected client and path. Review an existing entry before registering another with the same name.

Install your copy of Screengaze and open the app. Check that your selected path contains the helper and skill described in this guide.
In Screengaze, open Editing and output → Integrations · Agents («Edición y salida → Integraciones · Agentes») and enable «Permitir conexiones MCP locales» to allow local MCP connections. You do not need an open project.
Register the screengaze server in your chosen client with the registration command. If it already exists, keep a correct configuration or update only its path, without duplicating the entry or replacing other integrations.
Optionally, copy the included skill to the client's personal directory. The command handles installation and updates: it keeps an identical copy and saves a backup if the content differs.
Reconnect the server in your client or open a new session to load the tools and skill. A saved registration does not guarantee that this conversation already has them available.
When Review connection («Revisar conexión») appears in Screengaze, check the client name and choose Allow session («Permitir sesión»). Enabling the integration does not automatically approve the session.
Ask the agent to query get_status without any other actions. If approval is pending, complete it in Screengaze and repeat the query. Confirm the real result before treating setup as complete.

Check Screengaze availability

Check bundled files

test -x '/Applications/Screengaze.app/Contents/Helpers/FrameStudioMCP' && test -f '/Applications/Screengaze.app/Contents/Resources/Automation/skills/screengaze/SKILL.md'

You can also select and copy the text manually.

The command exits with code 0 if it finds the executable helper and SKILL.md; success prints nothing. Open the app and enable the integration using its controls.

Open Screengaze

open '/Applications/Screengaze.app'

You can also select and copy the text manually.

Inspect existing registration

codex mcp get screengaze

You can also select and copy the text manually.

If missing, register the integration with the next command. If it already matches this path and stdio, keep it and proceed to verification.

Register MCP in Codex

codex mcp add screengaze -- '/Applications/Screengaze.app/Contents/Helpers/FrameStudioMCP'

You can also select and copy the text manually.

Codex uses ~/.codex/config.toml for personal registration by default; no --scope user flag is needed. Respect any custom configuration location.

If registration exists with an incorrect path

First back up the client configuration. Run this replacement only after confirming the personal screengaze entry is incorrect; it removes and re-adds only that entry. Preserve any extra settings you need to reapply and do not change other servers or scopes.

Replace only personal Screengaze registration

codex mcp remove screengaze &&
codex mcp add screengaze -- '/Applications/Screengaze.app/Contents/Helpers/FrameStudioMCP'

You can also select and copy the text manually.

Verify registration

codex mcp list
codex mcp get screengaze

You can also select and copy the text manually.

Check version, help and catalogue

'/Applications/Screengaze.app/Contents/Helpers/FrameStudioMCP' --version
'/Applications/Screengaze.app/Contents/Helpers/FrameStudioMCP' --help
'/Applications/Screengaze.app/Contents/Helpers/FrameStudioMCP' --list-tools

You can also select and copy the text manually.

These options do not modify projects. The catalogue does not prove connection or authorization. Without options the helper waits for stdio messages; it is not an installer and has no --install option.

Install or update the optional skill for Codex

(
  set -eu
  screengaze_app='/Applications/Screengaze.app'
  screengaze_source="$screengaze_app/Contents/Resources/Automation/skills/screengaze"
  screengaze_target="$HOME/.agents/skills/screengaze"
  test -f "$screengaze_source/SKILL.md" || { printf '%s\n' 'The bundled app skill was not found.' >&2; exit 1; }
  mkdir -p "$HOME/.agents/skills"
  if [ -e "$screengaze_target" ] || [ -L "$screengaze_target" ]; then
    if diff -qr "$screengaze_source" "$screengaze_target"; then
      printf '%s\n' 'The skill is already up to date.'
      exit 0
    fi
    mkdir -p "$HOME/.agents/skill-backups"
    screengaze_backup=$(mktemp -d "$HOME/.agents/skill-backups/screengaze.XXXXXX")
    mv "$screengaze_target" "$screengaze_backup/screengaze"
    printf 'Backup saved at: %s\n' "$screengaze_backup"
  fi
  cp -R "$screengaze_source" "$screengaze_target"
  printf '%s\n' 'Skill installed. Reconnect the client or open a new session.'
)

You can also select and copy the text manually.

Personal destination: ~/.agents/skills/screengaze. The command compares the entire folder. If different, it moves the previous copy to skill-backups beside skills, then installs the new one. Terminal displays the backup path. To restore it, close the client, preserve the current copy and return the backup's screengaze folder to the personal destination. Invoke the skill with $screengaze.

Check each state

Check registration with your client's CLI and inspect the catalog with the helper's diagnostics. Then verify the connection from the agent itself. Reading the catalog does not query Screengaze or prove that its session is authorized.

get_status takes no arguments and can diagnose the connection before approval. Check enabled, authorized and requires_approval. To finish setup, query it again after choosing Allow session and confirm authorized: true. This query does not modify the project.

Check	What it proves
Helper located	The executable exists inside your selected app.
MCP registered	The client has an entry pointing to the correct helper.
Catalog and tools	The helper provides its catalog; tools must also load in this client session.
Skill installed	The workflow is in the client's directory and loads in a compatible session.
Session authorized	Screengaze has approved this specific connection.
Real status query	The agent called get_status and received the app's state.

Message to continue after reconnecting

Continue verifying Screengaze in Codex on this Mac. Do not repeat installation. Discover the screengaze MCP tools and call only get_status with no arguments. If tools are missing, explain how to reconnect the client or open a new local session. If approval is missing, guide me to enable “Permitir conexiones MCP locales” and approve “Permitir sesión” under Edición y salida → Integraciones · Agentes; then repeat get_status. Do not enable frame or transcript sharing. Do not open or modify projects, record or export. Report connection, authorization and the actual get_status result separately; leave any unperformed check pending.

You can also select and copy the text manually.

Permissions and shared content

Your client may ask permission to run commands or use tools. Screengaze requires you to enable MCP and approve the session. macOS separately grants screen, microphone and camera permissions according to the sources you plan to record. Each approval has its own role.

Share frames («Compartir fotogramas») and Share transcript («Compartir transcripción») are independent options, initially off. The agent must not enable them on its own. A local MCP connection does not mean the client's model is local: shared images and words may reach its provider.

Session approval allows access to local projects and media, editing, recording and new exports. You can remove that access with Revoke access («Revocar acceso») or disable MCP connections in Screengaze. Do not share the private connection file, which contains a session token.

After setup

Once the status query is verified, you can request these actions separately. Start with a query that makes no changes; use test material for editing or recording and review the result before exporting.

An autonomous demo also needs browser or desktop tools operating a visible window on the same Mac. Screengaze captures and edits; the MCP does not itself control clicks, typing or navigation in the demonstrated app.

The skill helps track jobs and review edits. A completed start job means recording has begun: it must be stopped and allowed to finish saving. Creating a transcript does not automatically add visible captions either. Exports retain the app's licence rules and must use a new destination file.

Query without changes

$screengaze Call only Screengaze get_status with no arguments. Report actual connection and authorization. Do not open or modify projects, record or export.

You can also select and copy the text manually.

Edit the open project

$screengaze In Screengaze, query status and the open project. If authorized and longer than 2 seconds, trim the first output second. Use the live apply_edits schema, current project_id and revision; query the project again and summarize the change. If no project is open, stop. Do not export or enable frame or transcript sharing.

You can also select and copy the text manually.

Record a demo

$screengaze Prepare a 20-second demo in a visible window on this Mac that I choose. Use your browser or desktop tools to perform the demonstration. Query get_status and capture sources, then wait for my window choice and the required permissions. Record without microphone, camera or application audio, with a finite 20-second limit. Wait for the start job to succeed and confirm recording is active before demonstrating. Stop capture and wait for saving to finish; deliver the project. Do not export or enable frame or transcript sharing.

You can also select and copy the text manually.

If something does not connect

App moved: correct the Screengaze.app path and update only the screengaze entry. Reconnect the server and check status again.
CLI missing: open Terminal on this Mac and check that your chosen client is installed and available. Follow its official documentation to resolve this; you do not need to install a second client.
Existing configuration: inspect the entry and its scope before changing it. Preserve a correct configuration, avoid duplicates and keep a backup if you must edit settings manually. Do not replace the entire configuration file.
Existing skill: compare the personal copy with the bundled one. If identical, leave it unchanged. If different, keep a backup before updating only screengaze.
MCP disabled or approval pending: enable the integration and review the request in Screengaze. If you rejected or revoked the session, reconnect a new one and approve it.
Tools or skill not loaded: reconnect the server or open a new session. Use the continuation message and leave the real query pending until tools become available.
App restarted: session authorizations and jobs do not persist after restarting Screengaze. Reconnect, approve when needed and query status; projects and exported files are saved.
Remote agent: continue in a local agent with Terminal access and Screengaze on this Mac. A session in a remote container cannot directly access the local helper.

Sources and verification scope

Content reviewed on 25 October 2026 using the MCP guide, verification report and skill included in the Screengaze project. The report separates helper and app tests from real Codex and Claude Code sessions, which are listed as pending. This guide describes the workflow and expected results; it does not itself verify a real connection in your client.

Control names in quotation marks match the current Spanish app interface; English explanations describe the same controls.

Keep exploring

Your first recording Local processing and data Export an MP4 video