ScreenApp Legacy MCP Bridge

A small, local, read-only Model Context Protocol (MCP) server for people whose ScreenApp recordings live in a legacy, UUID-based workspace.

It solves three problems that can occur together:

1. Codex completes the browser authorization step but the token exchange fails.

2. ScreenApp's current MCP endpoint connects to a different or empty account while the recordings remain visible in the older ScreenApp dashboard.

3. The legacy MCP endpoint can read recordings and transcripts, but does not expose summaries that ScreenApp has already generated and stored.

The bridge runs on your computer. Codex or Claude talks to it over stdio; the bridge talks to ScreenApp's legacy endpoint using your OAuth token. No credential is put in the MCP client configuration, and no ScreenApp AI-generation tool is exposed.

[!Disclosure] A little obvious - I created this fix using Codex to solve the issues I personally experienced. Hpoe it helps some other punters. I have a paid ScreenApp subscription, the product is ok, a bit clunky definitely more features I'd love for my use case - may get to writing these down? Let me know what your experience is like.

I'm sporadic using this account. Send through any issues and I'll try to be responsive - not setting any expectations.

What this fixes

The failure is not one single bug. It is a compatibility gap between two generations of ScreenApp and one OAuth client behavior.

The relevant Codex behavior is tracked in openai/codex#40928. ScreenApp documents the current MCP endpoint. The legacy URL and response behavior in this project are compatibility observations and may change; they are not presented as ScreenApp's current public contract.

Related MCP server: gilbert-mcp

Architecture at a glance

Codex / Claude Desktop
        │ local stdio; no token in client config
        ▼
ScreenApp Legacy MCP Bridge
        ├── OAuth login + Keychain or owner-readable file credential store
        ├── legacy SSE client + mcp-session cookie preservation
        └── stored-summary compatibility reader
                │ HTTPS + Bearer token
                ▼
        api.screenapp.io/v2

This local boundary is intentional. It avoids hosting other people's OAuth tokens, keeps the bridge easy to audit, and works with desktop MCP clients that can start a local command.

Quick start

You need Node.js 20 or newer, Git, and a ScreenApp account that can see the legacy recordings in the browser.

git clone https://github.com/djOsh-03/screenapp-legacy-mcp.git
cd screenapp-legacy-mcp
npm install
npm run build
node dist/cli.js auth login
node dist/cli.js doctor

The login command registers a dedicated OAuth client, opens ScreenApp in your browser, and waits on a loopback-only callback. On macOS, the resulting credentials are stored in Keychain. The doctor command confirms the token, legacy SSE session, profile, team access, and upstream tools without printing profile or recording content.

To verify summary access too, use the UUID shown in a legacy recording URL:

node dist/cli.js doctor --recording-id 11111111-2222-4333-8444-555555555555

The example UUID is deliberately fake. Do not paste private recording IDs into issue reports.

Linux and Windows

The same clone, install, build, login, and doctor sequence works on Linux and Windows. In PowerShell, use node .\dist\cli.js auth login. Linux requires xdg-open to open the consent page; if browser launch fails on any platform, rerun with --no-open and open the printed URL manually.

PowerShell equivalents for the path and Codex steps are:

(Get-Command node).Source
(Get-Location).Path
codex mcp add screenapp_legacy -- "C:\absolute\path\to\node.exe" "C:\absolute\path\to\screenapp-legacy-mcp\dist\cli.js"

For file storage, set $env:SCREENAPP_CREDENTIAL_STORE = "file" before auth login. Pass the same non-secret setting to Codex with codex mcp add --env SCREENAPP_CREDENTIAL_STORE=file ....

macOS is the only platform with an integrated secret store in this release. Linux and Windows default to a plaintext credentials file under the user's configuration directory. Use a single-user machine, protect the account and filesystem, and revoke the OAuth token when the machine is shared or retired.

Add it to Codex

Find the absolute paths on your machine:

command -v node
pwd

The supported CLI path is:

codex mcp add screenapp_legacy -- \
  /absolute/path/to/node \
  /absolute/path/to/screenapp-legacy-mcp/dist/cli.js

The equivalent manual entry in ~/.codex/config.toml is:

[mcp_servers.screenapp_legacy]
command = "/absolute/path/to/node"
args = ["/absolute/path/to/screenapp-legacy-mcp/dist/cli.js"]

Restart Codex after changing its MCP configuration. There is no url, bearer token, client ID, or client secret in this block: Codex launches a local stdio server, and the bridge owns the upstream OAuth compatibility work.

Codex Desktop may not inherit environment variables from your interactive shell. If you use non-secret overrides such as a file-store location, add them explicitly with codex mcp add --env KEY=VALUE .... Never place SCREENAPP_ACCESS_TOKEN in Codex config; authenticate to the selected store before launching Codex.

Useful first prompts are:

• “Use get_profile and tell me which ScreenApp account is connected.”

• “List my ScreenApp teams, then list five recordings in the relevant team.”

• “Get the stored summary for recording UUID …. Do not generate a new summary.”

• “Retrieve the complete transcript, following nextOffset until hasMore is false.”

See Codex setup for validation and removal steps.

Add it to Claude Desktop

Build the project, complete auth login, then add a local server to Claude Desktop's configuration:

{
  "mcpServers": {
    "screenapp-legacy": {
      "command": "/absolute/path/to/node",
      "args": [
        "/absolute/path/to/screenapp-legacy-mcp/dist/cli.js"
      ]
    }
  }
}

Save this as ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows, then restart Claude Desktop. This bridge is mainly needed when the official remote connector cannot see an older UUID library; current ScreenApp accounts should use the official connector.

Tools

All tools are annotated read-only, non-destructive, and idempotent.

The upstream assistant_search, ask_recording, and ask_multiple_recordings tools are not exposed. This prevents an apparently read-only archival workflow from silently turning into paid or quota-consuming AI generation.

How get_summary behaves

For a UUID recording, the bridge reads the legacy file payload and checks:

data.postProcess.systemPromptResponses.CHAPTERS.responseText

That value is itself JSON containing chapter titles, timestamps, and notes. If chapters are absent, the bridge falls back to data.file.description. It can return structured JSON or readable Markdown:

{
  "fileId": "11111111-2222-4333-8444-555555555555",
  "title": "Planning session",
  "available": true,
  "source": "postProcess.systemPromptResponses.CHAPTERS",
  "chapters": [
    {
      "title": "Delivery risks",
      "start": "12:40",
      "end": "18:05",
      "paragraph": "The group compares schedule, supplier, and acceptance risks."
    }
  ],
  "description": "",
  "warnings": []
}

It never asks ScreenApp to create a summary. If processing is still underway, the tool returns available: false; retry after ScreenApp's dashboard shows that processing has finished.

Real-world scenarios

Archive a meeting library into Markdown

An organisation wants one Markdown file per historical recording, including title, source, author, duration, transcript, and ScreenApp's existing summary. An MCP client can page through list_recordings, call metadata/transcript/summary for each UUID, and write the files locally. get_transcript pagination prevents long meetings from being truncated; get_summary reuses stored work rather than spending AI credits.

Diagnose the “connected but empty” account

OAuth can succeed against the current ScreenApp endpoint while returning a new or empty workspace. Call get_profile, then list_teams, before assuming data was deleted. If the browser dashboard uses UUID recording URLs and the current endpoint sees no recordings, the legacy bridge may be the correct connection boundary.

Search historical interviews without generating an answer

Use search_recordings for exact transcript evidence, then retrieve the relevant transcript segments. Because assistant-search and question-answering tools are absent, the model cannot accidentally substitute a fresh generated answer for source evidence.

Wait for a newly uploaded video

A new upload may exist before transcription and post-processing finish. Metadata can be available while the transcript or summary is not. Treat that as eventual consistency: wait until the ScreenApp UI reports completion, then retry the read-only tool.

More worked prompts and automation patterns are in Examples.

Credential options

The default is macOS Keychain on macOS and a plaintext, owner-readable file elsewhere. On POSIX systems the file is created with mode 0600; Windows relies on the user's filesystem access controls. Prefer Keychain or an equivalent OS secret manager where available.

The application reads the process environment directly and does not load .env files. Do not put real values in .env files committed to Git. The included .gitignore blocks common credential files, but secret hygiene remains your responsibility.

Development and verification

npm install
npm run check
node dist/cli.js doctor

npm run check performs strict type checking, linting, tests with coverage thresholds, and a production build. The test suite covers OAuth request placement, refresh behavior, credential permissions, same-origin cookie forwarding, summary parsing, and MCP tool registration. Live tests are opt-in because they require a private ScreenApp account:

SCREENAPP_TEST_RECORDING_ID="your-private-uuid" npm run test:live

The live smoke test starts the built server over stdio, lists its MCP tools, and calls get_summary. It prints only counts and availability, not the UUID or recording content.

Limits

• This project targets legacy UUID-based ScreenApp workspaces. It does not replace the official current ScreenApp connector.

• The legacy HTTP+SSE transport is deprecated in MCP, but remains necessary for the old ScreenApp endpoint. The public-facing local server uses current stdio MCP APIs.

• Stored-summary access depends on an observed legacy response field that may change.

• The bridge is deliberately read-only. It cannot upload, edit, delete, share, or create ScreenApp content.

• It does not expose ScreenApp tools that generate AI answers.

For deeper detail, read Architecture, OAuth compatibility, and Troubleshooting.

License

MIT. See LICENSE.