Connect Codex, Claude or another AI assistant with MCP
Copy a setup prompt for Codex or Claude Code, sign in to Corthex and connect your workspace. Includes Claude web/Desktop setup and permission controls.
Connect your AI assistant
Choose your app, copy its setup prompt and sign in to Corthex.
Read and manage is selected by default: bot and widget settings, knowledge, workflows and documents. Choose Read only here or turn off changes during sign-in if you prefer.
- Paste the prompt in Codex
- Sign in and choose workspace
- Confirm the connection
Your assistant prepares the configuration; you complete browser sign-in. A new chat or MCP reload may be needed before the tools appear.
View or select the prompt
Manual setup & troubleshooting
Merge this entry into your user Codex configuration. Keep other settings intact.
[mcp_servers.corthex]
url = "https://www.corthex.app/api/mcp"
scopes = ["workspace:read", "bots:read", "knowledge:read", "conversations:read", "audit:read", "documents:read", "workflows:read", "bots:write", "knowledge:write", "workflows:write", "documents:write"]codex mcp get corthex
codex mcp login corthex --scopes "workspace:read,bots:read,knowledge:read,conversations:read,audit:read,documents:read,workflows:read,bots:write,knowledge:write,workflows:write,documents:write"Already connected? Ask your assistant to call get_workspace. Only consider setup complete when it confirms the intended workspace and actual permissions. Do not paste access tokens into chat.
In this article
Before you begin
Use a test environment and the smallest necessary access. Keep workspace API keys and signing secrets on your server, outside browser code and public screenshots.
Step by step
- 1
Check availability
Open Settings → AI connections as a workspace administrator. If MCP is being prepared, connections are disabled until the server operator applies the MCP database migration and enables the feature.
- 2
Copy your setup prompt
Choose Codex, Claude Code or Claude web/Desktop in Quick connect above. Read and manage is selected by default; choose Read only if preferred, then copy the prompt. In Codex or Claude Code, paste it into a local session so the assistant can prepare the configuration and browser sign-in. Claude web/Desktop adds remote connectors through Customize → Connectors; use the direct link, choose OAuth / Sign in now and Register automatically when offered. Team policies can require an owner to add the connector first. The server URL is https://www.corthex.app/api/mcp (Streamable HTTP).
- 3
Choose workspace and permissions
Sign in to Corthex, review the developer-supplied application name and select a workspace you administer. Open About this application to inspect the registered callback URL. Read permissions can include private prompts, knowledge content and customer messages. If the client requested write scopes, Also allow changes starts enabled; turn it off to grant read-only access. Otherwise reconnect with those scopes when needed.
- 4
Choose the intended assistant
Ask the assistant to use list_bots or resolve_bot and confirm the name, ID, slug or connected store. Similar names return candidates instead of choosing for you. Bot and widget changes always target a specific bot ID; workspace documents are separate and workflows list assigned bot IDs.
- 5
Review and apply changes
Read the current resource and use get_settings_schema to discover supported fields. update_bot supports start questions, prompts, models, branding, custom text, tools and handoff settings; get_widget_settings and update_widget_settings cover the appearance editor. update_workflow creates or edits a workflow, assignments and publication state. update_document edits an existing document's name or editor JSON. Writes default to dryRun=true. Applying uses dryRun=false, a unique operationId and the current revision; documents also require expectedVersion. Read again after a stale revision rather than overwriting someone else's change. Your AI application's approval controls still apply.
- 6
Review or revoke
Settings → AI connections shows status, expiration and a compact permissions summary with expandable details. Change expiration for active connections to 1 day, 7 days, 30 days, 1 year or Never; new durations start when saved. Expired or revoked connections must reconnect. Revoke access to stop subsequent tool calls. Removing administrator membership or disabling the user also blocks access.
Available permissions
Each connection is authorized independently. Tokens from the website widget or the public developer API cannot be used as MCP credentials.
| Scope | Access |
|---|---|
| workspace:read | Workspace and raw usage totals |
| bots:read | Bot identity, full editor settings, widget settings and model catalog |
| knowledge:read | Source metadata and extracted text |
| conversations:read | Customer messages and session state |
| audit:read | MCP activity |
| documents:read | Workspace documents and content |
| workflows:read | Workflow definitions and bot assignments |
| bots:write | Change bot settings, start questions, custom text and widget appearance |
| knowledge:write | Add knowledge sources |
| workflows:write | Create, edit, assign, publish or pause workspace workflows |
| documents:write | Edit existing document names and editor JSON with version history |
Good to know
Access is bound to one workspace. Choose 1 day, 7 days, 30 days, 1 year or Never; 30 days is the default. Access tokens still last at most 15 minutes with rotating refresh tokens.
This connection shares authorized data with your chosen AI application. It does not add that assistant to your public website widget.
Application names are self-reported. Corthex does not request or share your model-provider API keys.
Corthex records the action and resource in its MCP log, excluding prompt bodies, source content and tokens.
Check the result
Check the response, relevant delivery history and organisation scope. Use the Public REST API reference in this Help Center for the technical contract.
Questions & troubleshooting
Does pasting the prompt install the connector everywhere?
Codex and Claude Code can prepare a local MCP configuration when the session has access to your machine. You still complete browser login and consent. Claude web/Desktop uses its own Connectors menu; a chat prompt guides that process but does not install it by itself. Some clients need an MCP reload or a new chat before tools appear. Confirm the connection with get_workspace before calling setup complete.
Why are write tools missing?
The client must request the relevant write scopes and you must allow changes during consent. Bot and widget edits use bots:write; imports use knowledge:write; workflows use workflows:write; documents use documents:write. Existing grants are not silently expanded. Reconnect with the management prompt for new workflow/document permissions, then refresh the client's MCP tools or start a new chat. Client policies can also disable writing.
Can I update start questions and widget texts without opening the dashboard?
Yes. Read get_bot and get_settings_schema first. Use update_bot for icebreakerQuestions, branding.customTexts, locale and behavior. Use get_widget_settings and update_widget_settings for header, input, launcher, home/help and proactive texts, colors and appearance. Nested bot objects merge with existing settings; arrays replace completely. Only named widget fields change. Unknown fields fail validation rather than being silently ignored.
Can MCP change every platform feature?
MCP covers the supported bot and appearance editor fields, knowledge imports, workflow management and existing document editing. Billing, team permissions, credentials, external connector secrets, conversation deletion, customer replies and unsupported lifecycle operations remain outside MCP. The schema-discovery tool explains available operations instead of promising unrestricted access.
Which knowledge files can I add?
The MCP tool accepts extracted text, public URLs, and base64 PDF, TXT, Markdown, CSV or JSON files. Files are limited to 450KB decoded, 100,000 extracted characters and 200 chunks. Larger files and other formats can use the normal dashboard upload.
Why did a bot update fail?
A stale revision means someone changed the bot after your assistant read it. Read it again and preview the revised change. Reuse the same operationId only when retrying the identical applied request.
Can the assistant delete conversations or send customer replies?
These operations are not exposed. Billing, team permissions, live replies, deletion, arbitrary SQL and API-key management remain outside MCP.
Rate this guide on this device. Ratings are not sent to Corthex.