ChatGPT Connector

Connect Web AI to your local workstation through MCP and OAuth.

herdr-mcp gives ChatGPT access to a real development environment without exposing your machine directly.

CopyChatGPT
  │ OAuth + MCP
  ▼
Cloudflare Edge
  │ authenticated WSS
  ▼
herdr-link / herdr-mcp
  │
  ├─ files / Git / shell
  └─ Herdr workspaces / panes / agents

This page explains the ChatGPT side: connection, OAuth, tool snapshots and troubleshooting. For deployment, see Installation. For the complete architecture, see Architecture.

Three different meanings of "connected"#

A connector can be connected at one layer and still fail at another.

OAuth success#

ChatGPT knows the identity of the MCP service and has authorization.

MCP handshake success#

ChatGPT completes initialization and receives tools/list.

Workstation success#

Tool calls can travel through Edge and reach the actual Herdr workstation.

A green connector status only proves one layer. The reliable validation is a fresh conversation calling herdr_inspect.

Add the MCP Connector#

The exact ChatGPT UI evolves. The general flow is:

1. Open ChatGPT Settings → Account security & login and enable Developer mode.
2. Open Plugins → Browse plugins, click the + button in the top-right corner, choose Create APP, and create an MCP app. herdr is the recommended example App name, but a custom display name is supported.
3. Enter the complete MCP URL, including /mcp:

Copyhttps://<your-edge-origin>/mcp

4. Complete OAuth in the browser. On first authorization, Herdr selects Chinese, English, or Japanese from the browser language. Step 1 copies herdr-mcp connector approve <approval-request-id> for Terminal; that command checks the local herdr-mcp service and Herdr server before Step 2 asks for the six-digit approval code. An approved WebChat Connector remains ordinary MCP only and cannot approve another Connector.
5. Create or open a ChatGPT Project. On the first message that needs workstation data or a Herdr action, select/reference the App name you assigned to this Connector. The extension reads the provider-owned data-keyword from that real App pill and stores it on the existing conversation/Project binding. Herdr-generated Auto, Agent-result, recovery, handoff, and Browser Actuation turns reuse that observed identity, so the same conversation should stay tool-enabled without repeated mentions. If tools disappear later while Edge, Link, and runtime remain healthy, treat it as an attachment regression; selecting the App again is a recovery workaround, not the normal workflow.

Never paste HERDR_MCP_TOKEN into ChatGPT. Public ChatGPT access uses OAuth. Static bearer is for local clients such as curl or Cursor.

Organization policies may require administrator approval for custom apps. herdr-mcp does not bypass ChatGPT workspace governance.

Stable origin and OAuth issuer#

The public origin is an identity, not just a URL.

Recommended:

CopyHERDR_MCP_BASE_URL=https://herdr-edge.example.workers.dev
MCP URL=https://herdr-edge.example.workers.dev/mcp

HERDR_MCP_BASE_URL does not include /mcp.

Keep the Edge origin stable. Local runtime generations can upgrade behind it without changing the ChatGPT connector.

OAuth flow#

The Edge handles the OAuth boundary. Dynamic Client Registration (DCR) only registers client metadata; it is not authorization. Since v0.4.6, a new Connector cannot exchange for a token until an enrolled-device/operator control channel records an explicit approval:

CopyConnector
  │ metadata discovery + DCR
  │ authorize + PKCE
  ▼
Herdr pending approval page
  │ request id + short-lived 6-digit code
  └─ any enrolled computer:
       herdr-mcp connector approve <request-id>
  ▼
authorization code → token → MCP request

Devices enrolled in the same Worker have no owner/member hierarchy for this control plane. Worker/operator credentials administer the fleet; an approved Connector receives ordinary MCP access only and cannot approve/revoke other Connectors or pair/revoke devices. A pre-v0.4.6 OAuth token that was issued before explicit approval remains usable for ordinary MCP compatibility until an operator explicitly revokes its client grant. Use herdr-mcp connector list to inspect each current Connector by immutable connector_id; the inventory retains a stable Connector name, authorization time, and throttled last real MCP-use time. Use herdr-mcp connector revoke <connector-id> --confirm to revoke one instance independently. Legacy clients that predate Connector-instance records remain revocable through the compatibility grant tombstone.

The approval code is single-purpose, short-lived, attempt-bounded, and is entered interactively rather than accepted on CLI argv. Real ChatGPT UAT on 2026-09-08 confirmed that removing/Disconnecting a custom Connector in ChatGPT does not currently send a reliable RFC 7009 revocation request to Herdr. Therefore provider-side Disconnect is not treated as a server-side revocation signal. Operators can revoke a specific conn_* manually at any time, and the Worker automatically revokes active Connector instances after 30 days without Connector activity. Automatic cleanup deletes only that instance's active access/refresh credentials and retains the non-secret audit row, including Connector name, authorization time, last-use time, revocation time, and inactive_30d reason. Real MCP use updates last_used_at at most once per 24 hours to avoid unnecessary Durable Object writes.

Troubleshoot:

• public origin consistency;
• OAuth issuer configuration;
• authorization/token exchange;
• audience/resource matching;
• workstation link availability after authentication.

OAuth success does not prove that the workstation is online.

Tool snapshots and new conversations#

ChatGPT uses a reviewed/frozen snapshot of MCP action definitions. A runtime or Edge deployment does not automatically enable newly added actions in an already approved workspace app.

Herdr 0.4.3 introduced the intentional separation of the two contracts:

public ChatGPT contract (first-party DEV/PROD): epoch 8 / 19 actions; workstation runtime execution contract: epoch 5 / 18 tools. The extra public action is Edge-local herdr_devices; it is never forwarded to a workstation. The immediately previous frozen epoch-4 contract and the frozen epoch-2 catalog are retained only as bounded rollback/compatibility baselines; epoch 3 is historical only, and the public Edge epoch-3 identity remains a bounded non-DEV/PROD baseline.

Example:

CopyServer: public epoch 8 / 19 actions

Refreshed action set   ✓ can expose epoch 8
Old/frozen action set  → may remain on an older action set

After runtime upgrades:

1. verify Edge/runtime version. Current releases expose Worker drift through herdr-mcp update check|status; interactive herdr-mcp update reconciles a safe same-contract existing Worker after Runtime activation, and herdr-mcp worker update is the direct repair path;
2. do not disconnect/delete/re-add the Connector merely because either Runtime or the existing Worker was upgraded in place; Worker reconciliation preserves the public OAuth origin and Connector credentials;
3. when the Herdr public action catalog changed, refresh/review/publish the app actions through the workspace controls available on the account, and explicitly enable new actions when required;
4. use a fresh conversation after the action snapshot changes. Updating Worker code is necessary for new Edge-provided descriptions, but an already-reviewed ChatGPT action snapshot can still remain frozen until the app actions are refreshed.

Epoch 8 acceptance: check publicContract.epoch=8 in /info at the Worker's URL used by the Connector. After refreshing Herdr actions, use a new conversation to verify 19 tools (11 read, 8 write) and the Browser actions require an explicit device and shell scripts, pipes, or redirects descriptions. Exercise a read-only file/Git query and a short command. Reloading the browser extension does not refresh MCP tool snapshots.

Do not reinstall the workstation for a stale tool snapshot. Existing v0.4.2 runtimes continue to execute the epoch-2 18-tool workstation contract; they simply do not gain the v0.4.3 multi-device runtime features until upgraded.

Why the catalog is intentionally small#

Herdr exposes many native Socket API methods. Registering every method as an MCP tool would consume context and make selection harder.

The public catalog focuses on common remote work:

• herdr_inspect
• herdr_since
• herdr_fs_*
• herdr_git
• herdr_exec*
• herdr_prompt

Advanced native capabilities remain available through dynamic discovery.

First validation request#

Use a safe first request:

CopyInspect the current Herdr workspaces and Git state. Read only; do not modify anything.

Expected:

1. herdr_inspect returns real workstation data;
2. herdr_skill can provide current guidance;
3. managed Git roots are visible;
4. file/Git operations work.

Permission confirmations#

ChatGPT may show confirmation UI for actions. Those controls belong to ChatGPT's safety layer.

The browser extension can handle clearly identifiable page-level Allow actions under strict conditions, but cannot bypass workspace policy or browser/system permission dialogs.

See Browser continuity and Extension wake.

Why browser continuity exists#

MCP is request-driven. After ChatGPT sends a task to a local Agent, the browser conversation does not automatically wake when the Agent finishes later.

CopyChatGPT → MCP → Herdr Agent

Agent finishes later

(no automatic browser turn without another channel)

The extension provides the reverse direction:

CopyHerdr events → browser → ChatGPT conversation

Connector solves Web AI reaching the workstation. Browser continuity solves the workstation reaching the conversation.

Troubleshooting map#

Minimum acceptance#

A real ChatGPT integration should satisfy:

• OAuth completes;
• a fresh conversation receives the current catalog;
• herdr_inspect sees the workstation;
• a managed project can be read;
• a safe command can execute;
• permissions behave as expected;
• browser continuity works for long-running tasks when installed.