Connect ChatGPT and Codex to your Hub workspace
The Radley Hub plugin lets you connect ChatGPT or Codex to a Hub workspace. Once connected, the plugin can discover your custom object types and read, create, and update records — subject to the workspace permissions your administrator has configured. Connections are personal: each team member connects their own account, and each connection is scoped to a specific workspace selected during Hub sign-in. OAuth grants are expiring and revocable at any time. ## Before you begin - You must have an active ChatGPT or Codex account. - Your workspace administrator must have enabled the ChatGPT integration in **Settings → Integrations**. - Linked-record and shared value-list fields are read-only through the plugin; all other writable fields follow your workspace permissions. ## Start the connection Open the **Radley Hub plugin** in ChatGPT or Codex and select **Connect** or **Authenticate**, or use the **Open Radley Hub plugin** button from **Settings → Integrations → ChatGPT & Codex** in Hub. The plugin manages the OAuth flow and redirects you to Hub to sign in and select a workspace. For a manually configured client, connect to `https://app.hub.radley.pro/mcp` using OAuth. Records and budgets have separate read and edit permissions. **Desktop clients (Codex and compatible MCP apps):** Desktop clients that listen on the IPv4 loopback interface (`http://127.0.0.1`) are also supported. Start the connection from the desktop app; Hub validates and returns the authorisation to the listener port you selected. > **Important:** Authorising the connection does not automatically load plugin tools into your current chat. After connecting, ask the plugin to identify your connected workspace — a successful reply confirms the connection is active. ## Authorise access in Hub 1. Sign in to your Hub account when prompted. 2. Select the workspace you want to give the plugin access to. 3. Review the permissions being requested: - **Read only** — the plugin can discover object types and read records. - **Read, create and update** — the plugin can also create new records and update existing ones. - **Budgets** — separate read and edit access for Finance budgets (Finance must be enabled). 4. Select **Allow access** to approve, or **Cancel** to deny without issuing a grant. Hub returns you to the plugin with the connection active. ## Connection status and expiry The **ChatGPT & Codex** panel in **Settings → Integrations** shows the status of each connection: - **Needs connection** — no active connection for this workspace yet. - **Awaiting first use** — authorised but no successful tool call has been recorded yet. - **Used successfully** — at least one successful tool call has been recorded, with the date of last use shown. - **Reconnect required** — the grant has lapsed; start the connection again from the plugin. Disconnected (revoked) connections are shown with a **Disconnected** badge. Previously approved permissions shown on a disconnected entry are no longer active. Reconnect to approve access again. Each connection entry shows the access level granted, expiry date, last successful use date, and whether budget access is included. If budget access is missing on an older connection, ask the plugin to read a budget and approve the additional access when prompted. **Grant lifetime:** New connections renew for up to 90 days of inactivity and require re-approval after one year. Older connections created before this update retain their original 30-day lifetime until reconnected. Hub refreshes the connection list automatically when you return focus to the page, so you do not need to manually refresh after completing a connection. ## What the plugin can access After connecting, the plugin can use the following tools: ### Workspace and records - **get_workspace_context** — Read connected workspace identity, capabilities and navigation links. A useful starting point for any workspace review. - **list_workspace_members** — Discover team members in the workspace. - **list_object_types** — Discover available record collections. - **list_records / get_record** — Read records, with subject filtering and direct Hub links included in results. Searches scan up to 500 records per call; follow `nextCursor` until `complete: true` — partial results are not an exhaustive search. - **create_record / update_record** — Write records if write access was approved. Updates are version-checked to reject stale edits. ### Budgets (Finance module required) - **list_budgets / get_budget** — Discover and read budget definitions. Note: `get_budget` returns source definitions, not calculated totals. - **get_budget_report** — Calculate plan, actual and variance for up to 12 explicit period keys, with coverage warnings. Use this for calculated results rather than `get_budget`. - **list_budget_sources** — Discover account IDs, object field definitions and shared drivers without needing to know IDs in advance. - **edit_budget_lines** — Make targeted changes to specific lines and periods without resubmitting the whole budget. Reads the existing budget version first; merges only the specified period values. - **create_budget / update_budget** — Create new budgets or replace entire budget definitions. Supplied arrays replace the whole array, so preserve unchanged lines. The plugin cannot access records in other workspaces through a single connection. Each workspace requires its own authorisation. ## Review your active connections You can view and manage your connections in two places: **From Settings → Integrations:** 1. Open **Settings** in your workspace. 2. Select **Integrations**. 3. Find the **ChatGPT & Codex** row and expand it. 4. Your connections for this workspace are listed with their status, access level, expiry and last use. 5. Use **Refresh status** to reload the connection list. **From the connections page:** 1. Select **Manage all connections** (or **Connection setup**) in the ChatGPT & Codex integration panel. 2. The connections page at `/connect/chatgpt` lists all connections across your workspaces. 3. Use **Refresh status** to reload the list. ## Disconnect a connection To stop the plugin from accessing a workspace: 1. Open the **ChatGPT & Codex** panel in **Settings → Integrations**, or go to the connections page at `/connect/chatgpt`. 2. Find the connection for the workspace you want to remove. 3. Select **Disconnect**. 4. Confirm the action. Disconnecting stops all future record access immediately. The button is disabled for connections that are already disconnected. To reconnect, start the process again from the plugin. ## Security and permissions - OAuth tokens are scoped, expiring, and stored server-side. They are never exposed in the Hub interface. - All record writes go through your workspace permissions — the plugin cannot perform actions your Hub account does not permit. - Stale updates are rejected to prevent conflicting edits. - Activity committed through the integration is recorded atomically. - Only successful tool calls update the last-use record. A failed diagnostic write does not mark a business operation as successful. - Selecting **Cancel** on the consent screen returns a validated denial to the plugin without issuing a grant or creating any codes.