> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cxp.crescendo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect CXP to ChatGPT and Codex

> Set up the CXP Plugin to find and summarize Conversations, explore support trends, make updates, and improve Concierge Agents from ChatGPT or Codex.

# Connect CXP to ChatGPT and Codex

The CXP Plugin brings your customer support work into ChatGPT and Codex. Ask questions in plain language to find Conversations, prepare handoff briefs, compare support trends, check team workload, and discover Concierge Agents. With the appropriate permissions, you can also update Conversations and use the Optimization Agent to analyze transcripts or improve agent drafts.

You can connect up to 100 organizations that your CXP account can access. When you work across organizations, name the ones you want to include so the answer keeps their results clear.

<Note>
  The CXP Plugin is currently distributed as a private beta. Your ChatGPT or Codex workspace administrator must make the Plugin available before you can connect it.
</Note>

## Prerequisites

Before connecting, confirm that:

* you can sign in to CXP;
* your CXP role can read Conversations in each organization you want to connect;
* your membership is active; and
* your ChatGPT or Codex workspace allows development apps or plugins.

Agent workload also requires an owner or administrator role. Optimization Agent sessions require current Optimization access in CXP and the **Modify CXP data** permission.

**Coming soon:** Team Leads will also be able to request agent workload across
their organization's reportable teams using the existing **Read CXP data**
permission. No reconnect or new permission is required. Agent, User, and Viewer
will remain unable to use this workload tool.

You do not need to create an API key, OAuth client ID, or client secret. Connecting opens the normal CXP sign-in experience.

## Connect organizations

1. Add the CXP app or Plugin from the development interface supplied by your workspace administrator.
2. Select **Connect**.
3. Sign in on the CXP page using any method enabled for your account.
4. Select one or more available organizations. Your current organization is selected by default. You can select up to 100, or choose **Select all currently available** when no more than 100 are listed.
5. Confirm the consent page is labeled **CXP for AI Agents**, then review **Read CXP data**. When requested by the host, also review **Modify CXP data**. Expand **Analyst sessions**, **Conversations & notes**, and **Optimization workspace** to see the included actions. These groups explain one shared write permission; they are not separate permission switches.
6. Select **Allow**.

“Select all” includes only the organizations shown during this connection. It does not automatically include organizations added to your account later.

After the browser returns to ChatGPT or Codex, ask:

```text theme={null}
Confirm my connected CXP organizations and whether I have read and write access.
```

ChatGPT uses `get_my_cxp_context` to show your connected organizations and approved access. Your current CXP role still determines which actions you can perform in each organization.

## Choose the right permissions

| Permission                        | What you can do                                                                                                                                                                                                |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Read CXP data** (`cxp.read`)    | Find and count Conversations, read details and history, create charts, inspect agent workload, list Concierge Agents, and read Applied Insights dashboards and stored widget history/results                   |
| **Modify CXP data** (`cxp.write`) | Update Conversation fields and assignments, add internal notes, use Insight Analyst sessions to investigate data, and use Optimization Agent sessions to analyze transcripts or improve drafts and evaluations |

**Coming soon:** User joins Viewer in Conversation read access. Neither role can update or assign a Conversation or add an internal note, even with **Modify CXP data**. The role alignment leaves connection setup and already approved OAuth permissions unchanged; reconnecting is not required. See [Roles and permissions](../reference/roles-and-permissions).

Both permissions respect your current CXP role. The Plugin cannot send customer-visible replies, and the Optimization Agent cannot publish a Concierge Agent.

Deep transcript analysis uses the Optimization Agent and requires **Modify CXP data**, even when you request analysis alone. You can explicitly ask for findings without changes. That instruction defines the task; the session still has permission to make changes.

## What you can do in ChatGPT

The examples below also work in Codex. Include the organization, date range, time zone, and any specific Conversation or Concierge Agent when they matter to your request.

### Find a Conversation and prepare a brief

Search by contact, subject, status, priority, date, or keywords. Ask ChatGPT to read the Conversation details and history, summarize the issue, and identify unresolved questions or next steps.

```text theme={null}
In Northwind, find Jane Smith's Conversation about a damaged shipment.
Prepare a handoff brief with the issue, actions already taken, and next steps.
```

If several Conversations match, ChatGPT can help you choose the correct one. A brief should say whether the complete history or only part of it was reviewed. Preparing a brief does not save an internal note unless you ask for that too.

### Explore support trends and create charts

Count Conversations, compare statuses or priorities, and track keyword matches over time. You can compare connected organizations and ask for a chart alongside the written findings.

```text theme={null}
Compare daily customer Conversation volume for Northwind and Contoso over
the last 30 days. Show the results in one labeled chart and summarize the
main differences. Use Pacific time.
```

Charts can also use values you provide directly. If your ChatGPT or Codex app cannot display a chart, use the accompanying text or table. Ask explicitly for a downloadable file if you need one; CXP does not save or export the embedded chart.

Chart cards display the Crescendo logo in your app's light or dark theme. Titles
are shortened when needed to avoid the logo; narrow or custom layouts use a
separate logo row. Standard charts fill the available card width and request
enough height for the chart and sources. Your app controls the final embedded
size and may still require scrolling. Explicit chart sizes and multi-panel
layouts keep their specified sizing.

Counts and keyword matches answer questions about known criteria. To understand recurring themes or what customers said before a handoff, ask for transcript analysis as described below.

### Check team workload

Ask for agent availability, active Conversation backlog, and work waiting in the routing queue. You can specify a team and time zone.

```text theme={null}
Show the Billing team's current workload in Northwind, including agent
availability, active Conversation backlog, and routing queue depth.
```

Backlog and queue depth measure different things and can overlap, so they should not be added together. Unavailable information should be identified as unavailable, rather than treated as zero.

### Update Conversations

With **Modify CXP data** and the corresponding CXP role permissions, you can change a Conversation's status, priority, Pending On, or Pending Reason; assign it to yourself, an agent, or a team; clear its assignment; or add an internal note as yourself.

```text theme={null}
Assign Conversation CX123 in Northwind to me, set its priority to high,
and add an internal note: "I will follow up with the shipping team today."
```

Internal notes are visible to your team and are not sent to the customer. Normal CXP status and permission rules apply; for example, reopen a Closed Conversation before assigning it or adding a note. See [Manage conversations](./conversation-operations) for supported changes.

Review the reported outcome. If a request times out, ask ChatGPT to check whether the change happened before repeating it, especially when adding a note.

### Find Concierge Agents and review their details

Ask for an inventory or narrow the list by agent name, description, latest update date, or updater. You can request an exact name or names containing a phrase, and combine criteria.

```text theme={null}
List all Concierge Agents in Northwind whose names contain "Support".
Include their descriptions, versions, and release notes.
```

```text theme={null}
Which Concierge Agents in Northwind were last updated in June 2026,
and who updated them? Use Pacific time.
```

`list_concierge_agents` returns each agent's `id`, `name`, `description`, `version`, `releaseNotes`, `updated`, and `updatedBy`. You can ask questions about these details without starting an Optimization Agent session. Missing values are reported as unavailable.

Exact text matching is case-sensitive; phrase matching ignores case. The supported filters are name, description, update time, and updater. Version and release notes are included in results but are not additional search filters.

Update dates describe each agent's **most recent update**, not every edit in its history. An agent updated in June and again in July will not appear in a search for latest updates in June. Updater names are reported as recorded in CXP.

Large lists arrive in pages. When you ask for all matches, ChatGPT should continue through the remaining pages and tell you if it cannot finish. Recent agent changes may take up to five minutes to appear. If a listing expires before it finishes, ask ChatGPT to restart the search.

### Analyze transcripts in depth

Use the Optimization Agent to review full Conversation transcripts and identify recurring topics, questions associated with handoffs, or opportunities to improve support.

```text theme={null}
Review customer Conversation transcripts from the past week in Northwind.
Identify recurring topics and questions that most often preceded handoff.
Include examples and explain how many Conversations were reviewed.
Analyze only; do not change configuration, drafts, or evaluations.
```

An organization needs at least one configured Concierge Agent to start an Optimization Agent session. For organization-wide analysis, you do not need to choose one; ChatGPT can arrange the session while keeping the analysis focused on the full population you requested. Name a particular Concierge Agent when you want to analyze its Conversations specifically.

The answer should distinguish how many Conversations were selected and reviewed, identify missing or incomplete transcripts, and support findings with examples.

### Improve a Concierge Agent

Ask the Optimization Agent to use its findings to improve a selected agent's draft, instructions, or evaluations. It can also update requirements or skills shared by Concierge Agents in the same organization, so describe the changes you want clearly.

```text theme={null}
Analyze recent billing Conversations handled by Northwind's Billing
Concierge Agent. Improve its draft instructions for explaining payment
options, run the relevant evaluations, and summarize the verified changes.
Do not publish.
```

If an agent name is ambiguous, ChatGPT asks you to choose the intended agent. During the session, it reports progress, relays questions, and summarizes completed changes and evaluation results. Review the draft in CXP before publishing it yourself.

<Warning>
  Optimization Agent work can continue after you disconnect or revoke Plugin access. Ask ChatGPT to stop the session when needed. Stopping can take time and does not undo completed changes.
</Warning>

### Continue or stop an Optimization Agent session

You can answer a session's follow-up questions, request additional work after it finishes, or ask it to stop. Keep the session details and CXP link from the answer so you can return to the same work later.

```text theme={null}
Continue the Billing Concierge Agent session. Focus the next revision on
customers who need a payment extension.
```

```text theme={null}
Stop the current Optimization Agent work and tell me what completed before
it stopped.
```

A stop request is not confirmation that work has finished. ChatGPT should keep checking progress and report whether the session stopped, completed, failed, or has an unknown outcome. You can also find the session in the Optimization Agent workspace in CXP; select the same organization first.

## Available MCP tools

ChatGPT and Codex select these tools for your request. You do not need to write tool calls to use the Plugin.

### Read, analyze, and visualize

These tools require **Read CXP data**, along with any applicable CXP role permissions.

| Tool                                      | What it does                                                                                                           |
| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `get_my_cxp_context`                      | Shows connected organizations and your approved read/write access                                                      |
| `query_conversations`                     | Finds Conversations by criteria or keywords and calculates counts, comparisons, and trends                             |
| `get_conversation`                        | Retrieves details for one Conversation, such as its subject, status, priority, and assignment                          |
| `get_conversation_history`                | Retrieves pages of Conversation messages and activity for review or a case brief                                       |
| `get_agent_workload`                      | Reports agent availability, workload, and routing queue depth; requires Owner/Admin, with Team Lead access Coming soon |
| `list_concierge_agents`                   | Finds Concierge Agents by name, description, latest update date, or updater, and returns pages of agent details        |
| `render_chart`                            | Displays data already available in the conversation as a chart; display depends on your app's support                  |
| `list_applied_insights_dashboards`        | Lists accessible dashboards and widgets; requires Applied Insights read access                                         |
| `list_applied_insights_widget_executions` | Finds stored widget runs by execution date, including their reporting-period keys and status                           |
| `get_applied_insights_widget_result`      | Reads a widget's latest stored result or one exact historical result                                                   |

### Change Conversations

These tools require **Modify CXP data** and the corresponding Conversation permissions in CXP.

| Tool                             | What it does                                                                      |
| -------------------------------- | --------------------------------------------------------------------------------- |
| `update_conversation`            | Changes status, priority, Pending On, or Pending Reason                           |
| `assign_conversation`            | Assigns a Conversation to yourself, an agent, or a team, or clears its assignment |
| `add_conversation_internal_note` | Adds an internal text note as you, without sending a customer reply               |

### Work with the Optimization Agent

All four session tools require **Modify CXP data** and Optimization access in CXP, including for analysis-only sessions.

| Tool                                      | What it does                                                                                 |
| ----------------------------------------- | -------------------------------------------------------------------------------------------- |
| `start_optimization_agent_session`        | Starts an analysis or improvement session for a Concierge Agent selected by exact name or ID |
| `get_optimization_agent_session_progress` | Retrieves progress updates, questions, results, and the session's current status             |
| `send_optimization_agent_message`         | Sends a follow-up answer or request to an idle session                                       |
| `stop_optimization_agent_session`         | Requests that the current work in a session stop                                             |

### Investigate with Insight Analyst

| Tool                                   | What it does                                    |
| -------------------------------------- | ----------------------------------------------- |
| `start_insight_analyst_session`        | Starts a creator-owned data investigation       |
| `get_insight_analyst_session_progress` | Reads the exact turn's status and saved answer  |
| `send_insight_analyst_message`         | Sends a follow-up to an idle Analyst session    |
| `stop_insight_analyst_session`         | Requests cancellation of the exact Analyst turn |

Insight Analyst is the data-insight agent, separate from the Optimization Agent.
Its session tools require **Modify CXP data** (`cxp.write`) and your current
Analyst access. A read-only connection needs fresh consent; refreshing its token
does not add permission. Each session belongs only to its creator in the
selected organization.

Use `start_insight_analyst_session` with `tenantId`, a UUID `requestId`, and your
`prompt`. Optional `timeFrame` is `P7D`, `P30D`, or `P90D` (default `P30D`);
optional `model` is `gpt-5.4`, `gpt-5.4-mini`, or `gpt-5.4-nano`.
Start returns `sessionId` and `generationId` while analysis continues.
Use `get_insight_analyst_session_progress` with that exact pair to read status
and the saved answer. Answers are capped at 64 KiB and explicitly marked when
truncated. Leaving the chat does not cancel analysis; execution limits still apply.

Use `send_insight_analyst_message` with the same session ID and a new request ID
for an intended follow-up once the session is idle. If a start or follow-up
response is lost, retry the original input with the **same** request ID. A busy
session rejects a different request rather than queueing it.
When interactive capacity is full, start/send can return `analyst_unavailable`;
wait and retry with the same request ID. Progress and Stop remain available.
This also applies to retries while capacity is full; it does not mean an
earlier admitted run was cancelled.

`outcome_unknown` means completion could not be established after execution
was interrupted or expired. Do not assume success or automatically restart.
`stop_insight_analyst_session` requests cancellation of one exact generation;
it does not undo work or stop a newer turn. Poll progress to confirm completion
or cancellation. A `required_action` result reports an Optimization proposal;
these session tools cannot approve it or start Optimization on your behalf.

## Read Applied Insights dashboard results

Ask: “Find our weekly support dashboard and explain its latest widget results.
Show the reporting period and a chart if it helps.” The connected agent uses
`list_applied_insights_dashboards` to identify widgets and
`get_applied_insights_widget_result` to read their stored results. Ambiguous
dashboard or widget names need clarification.

All three stored-data tools require **Read CXP data** and current Applied Insights read access
in the selected organization. They do not require write permission or the
native Analyst workspace to be enabled. Existing read connections need no new
OAuth scope; each tool still checks your current access independently.

These tools do not run widgets, execute new queries or start Analyst sessions.
The latest result can cover a different period from the dashboard setting.
Exact reads require both an execution timestamp and reporting-period key;
there is no automatic history fallback. Unknown legacy periods remain unknown,
and current widget presentation is not guaranteed to match its historical run.
A failed execution or missing result is not a zero value.

For comparisons, ask: “Find this widget's runs from yesterday and today, then
compare their stored results.” The agent can use
`list_applied_insights_widget_executions` to discover executions before reading
the selected results. You do not need to know their exact timestamps first.
Optional `executedFrom` (inclusive) and `executedTo` (exclusive) select when a
run executed, not the period it analyzed. Include your timezone when asking
about relative days. A run from yesterday may contain a rolling 30-day total.

History pages contain timestamps, reporting-period keys when known, success or
failure status, and duration when available—not the full results. Pages default
to 20 entries, with a maximum of 100. The agent follows `nextCursor` with unchanged
filters and page size until null, or tells you it reviewed only part of history.
An expired cursor requires fresh discovery. New runs may appear in that fresh
snapshot. Unknown legacy period keys prevent exact rereads, and retained history
is not a guarantee that every past run is still available.

The complete directory is limited to 100 dashboards, and each complete result
to 256 KiB. Over-limit requests fail rather than return partial data. Optional
charts reuse the existing visualization tool; text/table answers remain useful
if your host cannot display a chart. Existing restricted tool diagnostics and
your external host may retain results; deleting a source does not remove those
copies.

## Change the connected organizations or permissions

Disconnect and reconnect to add or remove organizations or grant **Modify CXP data**. Your connection includes only the organizations and permissions you approved.

Changes to your CXP membership or role affect subsequent requests. Disconnecting prevents new Plugin access but does not cancel Optimization Agent work already in progress; request a stop separately.

## Troubleshooting

### The organization is not available

Confirm that your membership is active and that you use the same verified email address for the CXP organizations you want to connect. If an organization was added after you connected, disconnect and reconnect to select it. You can select up to 100 organizations per connection.

### CXP says to restart the connection

Return to ChatGPT or Codex and start **Connect** again. The previous connection attempt may have expired or already been used.

### An action is not authorized

**Coming soon:** Concierge discovery and Optimization Agent tools become
Owner/Admin-only through CXP. Existing Insights reads remain available to every
role; Analyst tools retain Owner/Admin/Team Lead/User access with **Modify CXP
data**. Agent and Viewer do not gain Analyst access. This role update changes no
OAuth scope and requires no reconnection. Legacy-app and shared native
Optimization permissions remain unchanged.

Check both the Plugin's approved permissions and your current role in the selected CXP organization. Reconnect if you need to grant **Modify CXP data**. For workload, confirm that you are an Owner/Admin, or a Team Lead after the Coming soon access update is deployed; general Settings access is not required by that update. For Optimization Agent sessions, confirm your Optimization access.

### Results look incomplete or differ from Conversation History

Recent changes may take a moment to appear in search results or Conversation details. Ask ChatGPT to review the relevant history and confirm whether it read every page. A partial review should be labeled as partial; unavailable information should not be described as absent.

### An agent listing cannot finish

Ask ChatGPT to report what it was able to retrieve and the error it received. If the listing expired, restart it. If the tool reports a capacity problem, contact support rather than assuming there are no agents. You can still request an Optimization Agent session for a known exact agent name or ID.

### An Optimization Agent session is missing

Select the same organization in CXP, then refresh the Optimization Agent workspace. You can also use the CXP link and session details returned by ChatGPT.

### Stop was requested but work still changed

Stopping takes time, and some work may finish before the stop takes effect. Check progress until the session reports an outcome, then review the draft. Completed changes are not rolled back.

### A chart does not appear

Use the text or table in the answer. Your ChatGPT or Codex app may not support embedded charts. If the chart is too large, ask for a simpler chart or a summary by category or time period.

When contacting Crescendo support, include the support reference shown by the Plugin and a short description of the problem. Do not share access tokens, authorization URLs, browser cookies, or API keys.