--- title: "Installation" canonical: https://workspace.socra.com/docs/cortex/installation --- # Install Cortex Connect Cortex to the agent you use, select your Socra Account, and verify that the agent can read your Modules. Follow one installation path for each agent you connect. This article includes all supported paths. Give an agent the [complete Markdown guide](https://workspace.socra.com/docs/cortex/installation.md) so it can select the path for its environment. You can also use [guided setup](https://cortex.socra.com/setup) for one step at a time. ## Before you start You need access to a Socra Account that can use Cortex. Use the same Account in your agent and the Cortex web app. Signing in to the website does not connect the agent. Check whether Cortex already works in the agent before installing anything. Ask it to list the Modules it can access. A successful Cortex call, including an empty list, confirms the connection. If that works, check the instructions and tool settings below without creating another connection. ## Suggested instructions These suggested instructions teach your agent to Flash the right knowledge before acting, without reminders. They also teach it to suggest creating or updating Modules when you share useful knowledge or preferences. You can edit or skip them. To adapt the instructions to your workflow, ask your agent: ```markdown Adapt https://workspace.socra.com/docs/cortex/instructions.md to how I already work, and help me save the result in my agent’s persistent instructions. ``` ```text Cortex is the single source of truth for a person or team’s specific knowledge, shared across agents, conversations, and tools. Its Modules define what should be and why. Dependencies identify prerequisite Modules. Flash loads a Module and all its Dependencies. Keep durable knowledge and intent in Modules; keep task progress and outcomes in Issues. Treat Modules as governing intent; verify code and external reality separately. Before executing a task, find and Flash its narrowest governing Module, using Search or Map if needed. If none exists, propose one. Reuse or create an Issue for that task under the same Module. Mark the Issue in progress when starting. Comment on progress and blockers. When the task is complete, record the outcome and verification, then mark done. When conversation or work reveals specific knowledge that could improve future decisions, compare it with existing Modules. Propose an update or new Module for missing or changed knowledge, preserving the decision and its reason. Show exact Before and After blocks for changed content and Dependencies; show full content and Dependencies for new Modules. Explain conflicts and recommend a resolution. Continue independent work while approval is pending. Save only after explicit owner approval, then Flash to verify. ``` The Codex, Claude Code, Cursor, and GitHub Copilot CLI plugins include these instructions through a session-start hook. ChatGPT’s plugin, CLI-only access, and direct MCP connections require saving them separately alongside your existing persistent instructions. Each provider section below shows where to save them. If your agent cannot save them itself, it should show you the text and the steps to save it. ## Choose an installation path | Environment | Installation path | Suggested instructions | | ------------------------------------------------- | ------------------------------ | --------------------------------------------------------------- | | Codex, Claude Code, Cursor, or GitHub Copilot CLI | Coding-agent plugin | Included. Trust the session-start hook and start a new session. | | ChatGPT | ChatGPT plugin store | Save separately in Custom instructions. | | An agent with terminal access | CLI-only access | Save separately in the agent’s persistent instructions. | | Grok | Custom MCP connector with PKCE | Save separately in Settings → Customize → Custom. | | Claude or another remote HTTP MCP client | Direct MCP connection | Save separately in the host’s persistent instructions. | “Plugin” refers to two different installation paths here. Coding-agent plugins include the instructions. The ChatGPT store plugin provides Cortex tools; save the instructions separately if you want the agent to use them. A direct MCP connection also needs instructions saved separately. Grok and direct MCP setup require a Socra Cloud Project and OAuth configuration. The ChatGPT store plugin and coding-agent plugins do not require creating your own OAuth client. Prefer a supported plugin when it is available. A custom MCP connection is an alternative, not an additional requirement for a working plugin. ### If you are an agent following this guide Inspect your available tools, host, operating system, and command execution capability. Do not infer terminal access from the fact that you can read this page. If you cannot identify the host or the user's intended environment, ask before selecting a path. Follow only the relevant path. Check which commands are available before running them. Preserve existing configuration and instructions. If a change requires a restart, explain how the user can resume setup in a new session. If the chosen path does not include instructions and they are not already saved, recommend reading the [Cortex instructions](https://workspace.socra.com/docs/cortex/instructions.md), adapting them to how the user already works, and saving the result in the agent’s persistent instructions. Use the full instructions above if you cannot open the link. Preserve existing instructions and save the adapted text so future sessions receive the guidance automatically. If you can’t save persistent instructions yourself, show your human the adapted text and where to save it. Explain that this teaches you to use Cortex proactively: Flash the right knowledge before acting and suggest knowledge updates without reminders. If they decline, continue without saving. Let the user complete browser sign-in and Account selection. Follow your host's approval requirements for installation and permission changes. Do not ask the user to paste passwords, access tokens, or client secrets into the conversation. For custom OAuth setup, the user enters credentials directly in the destination host. Verify the connection with a real Cortex call from the configured environment. Start a fresh conversation to check that it receives persistent Cortex guidance and can explain what that guidance requires. Report connection and guidance separately, including whether instructions were installed, saved, or skipped. If the user chose to save instructions but the new conversation did not receive them, help check their saved location and scope. Stop after verification; do not create a Module as an installation test. ## CLI access Use this path when your agent can execute shell commands. If the Socra CLI is absent, run the installer for your operating system. For macOS or Linux: ```bash curl -fsSL https://cli.socra.cloud/install.sh | sh ``` For Windows, run this in PowerShell: ```powershell irm https://cli.socra.cloud/install.ps1 | iex ``` Open a new terminal. Add the Cortex commands: ```bash socra install cortex ``` Sign in and select your Account in the browser that opens: ```bash socra account login ``` Wait for the terminal to confirm sign-in. If you selected the wrong Account, run `socra account switch`. Then verify access: ```bash socra cortex module list ``` Ask the agent to run that command itself. A returned list, including an empty list, confirms CLI access. A successful CLI call does not prove that a separate MCP connection works. CLI installation does not add persistent agent instructions. You can add the suggested instructions above to your host's persistent instructions, preserving existing text. Alternatively, tell the agent when to use Cortex as you work. Do not run `socra cortex setup` for CLI-only access; that command configures detected coding-agent plugins. If you saved instructions, start a new agent conversation and ask: ```text Run socra cortex map to list the Modules I can access (an empty list is valid). Separately, report whether this new conversation received persistent Cortex guidance and what it requires. Do not change anything. ``` Check both the command result and the agent's report about its guidance. If instructions are missing, check where they were saved and whether that location applies to this conversation. If you skipped instructions, CLI access can still work; report the guidance as skipped. ## Connect a coding agent Cortex plugins connect supported coding agents to your Account's knowledge and work. Each plugin loads Cortex guidance when a session starts and lets the coding agent use Cortex tools. Cortex supports [Codex](https://workspace.socra.com/docs/cortex/integrations/coding-agents#codex), [Claude Code](https://workspace.socra.com/docs/cortex/integrations/coding-agents#claude-code), [Cursor](https://workspace.socra.com/docs/cortex/integrations/coding-agents#cursor), and [GitHub Copilot CLI](https://workspace.socra.com/docs/cortex/integrations/coding-agents#github-copilot-cli). The plugin contains the SessionStart hook and [hosted MCP configuration](https://workspace.socra.com/docs/cortex/reference/mcp). You do not need to install either component separately. The hosted MCP surface includes operations that can create, update, and delete Cortex resources. Review the [security model](https://workspace.socra.com/docs/cortex/administration/security) before changing your agent host's approval policy. > **Required:** Approve or trust the Cortex SessionStart hook when a coding agent asks. Without the hook, Cortex tools remain available, but the coding agent does not receive Cortex guidance automatically when a session starts. [Open guided setup](https://cortex.socra.com/setup) to choose **Plugin (preferred)**, **CLI**, or **MCP** and follow one step at a time. For the store installation, follow [Connect ChatGPT](https://workspace.socra.com/docs/cortex/integrations/chatgpt). ### Install automatically Use the [Socra CLI](https://workspace.socra.com/docs/cortex/reference/cli) to detect and configure every supported coding agent installed on your computer. #### Install the Socra CLI ##### macOS and Linux Run these commands: ```bash curl -fsSL https://cli.socra.cloud/install.sh | sh ``` ##### Windows Run these commands in PowerShell: ```powershell irm https://cli.socra.cloud/install.ps1 | iex ``` Open a new terminal after the installer completes. Install Cortex, sign in to your Account, and configure every detected coding agent: ```bash socra install cortex socra account login socra cortex setup ``` The command detects supported coding agents, installs or updates each Cortex plugin, trusts the verified Codex SessionStart hook, and starts supported authentication flows. Follow the command's next steps to finish any authorization that the other hosts perform inside their own interfaces. > **Authentication required:** Each coding agent stores its own Cortex authorization. `socra cortex setup` may start a browser login or report that authorization needs to be completed in the host. If Codex authentication is incomplete, run: ```bash codex mcp login cortex ``` For Claude Code, start `claude`, run `/mcp`, select the Cortex server, and follow its browser sign-in. If setup reports an unsupported Claude login command, complete authentication this way. For Cursor, open **Customize → MCPs** (older versions: **Settings → Tools & MCP**), select Cortex, and connect. For GitHub Copilot CLI, start `copilot`, run `/mcp`, select Cortex, and sign in. Complete Account selection in the browser that opens. If setup already connected the intended Account, continue without signing in again. When a configured coding agent asks whether to allow the Cortex SessionStart hook, approve it. You can run `socra cortex setup` again. It updates outdated installations and does not create duplicate installations. ### Install manually Use the instructions for your coding agent when you do not want the Socra CLI to manage plugin installation. #### Codex Add the Socra marketplace and install Cortex: ```bash codex plugin marketplace add socra/agent-plugins --ref main codex plugin add cortex@socra ``` Authenticate the MCP connection: ```bash codex mcp login cortex ``` Approve the bundled Cortex SessionStart hook if Codex asks, then start a new Codex session. #### Claude Code Add the Socra marketplace and install Cortex for your user profile: ```bash claude plugin marketplace add socra/agent-plugins --scope user claude plugin install cortex@socra --scope user ``` Authenticate the MCP connection: Start `claude`, run `/mcp`, select the Cortex server, and follow the browser sign-in. Select the same Socra Account that you use in Cortex. Approve the bundled Cortex SessionStart hook if Claude Code asks, then start a new Claude Code session. #### Cursor Clone the [public plugin repository](https://github.com/socra/agent-plugins) and link the Cursor provider directory: ```bash git clone https://github.com/socra/agent-plugins.git mkdir -p ~/.cursor/plugins/local ln -s "$(pwd)/agent-plugins/providers/cursor/cortex" ~/.cursor/plugins/local/cortex ``` Restart Cursor or run **Developer: Reload Window**. Confirm that Cortex appears under **Customize**. Approve the bundled Cortex SessionStart hook if Cursor asks. Open **Customize → MCPs** (older versions: **Settings → Tools & MCP**), select Cortex, and sign in if prompted. Turn on every Cortex tool in the tools list above chat. #### GitHub Copilot CLI Add the Socra marketplace and install Cortex: ```bash copilot plugin marketplace add socra/agent-plugins copilot plugin install cortex@socra ``` Start `copilot`, approve the bundled Cortex SessionStart hook if GitHub Copilot CLI asks, then run `/mcp`. Select Cortex and sign in if prompted. Start a new session after authorization completes. #### Other coding agents Cortex does not currently provide a plugin for other coding agents. Configure the [hosted Cortex MCP server](https://workspace.socra.com/docs/cortex/guides/mcp) if the agent supports remote HTTP MCP. An MCP-only connection provides Cortex tools but does not install the Cortex SessionStart context. ### Allow the plugin instructions The plugin supplies the [suggested instructions](https://workspace.socra.com/docs/cortex/installation#suggested-instructions) at the start of a session. They teach your agent to Flash the right knowledge before acting and suggest creating or updating Modules when you share useful knowledge or preferences. You do not need to add them to an `AGENTS.md` file. Installing tools alone is not enough: a host can skip an untrusted hook. In **Codex**, type `/hooks`, open **SessionStart**, and select the hook whose source is **cortex@socra**. Review the command that reads the plugin's `hooks/session-start.md`, then press **t** to trust it. Confirm it is enabled and start a new session. Other supported hosts may ask to trust the Cortex SessionStart hook during installation or startup; approve that hook and restart the session. See [Codex hook review](https://learn.chatgpt.com/docs/hooks) and the [canonical Cortex instructions](https://github.com/socra/agent-plugins/blob/main/shared/cortex/session-start.md). ### Enable Cortex tools Make all Cortex tools available in your agent: - **Codex:** run `/mcp` and check that Cortex is connected with its tools available. The plugin enables all Cortex tools by default. - **Claude Code:** run `/mcp`, select Cortex, and check that its server and tools are enabled. - **Cursor:** open **Customize → MCPs** and confirm the connection. Turn on every Cortex tool in the tools list above chat. - **GitHub Copilot CLI:** run `/mcp` and check that Cortex is enabled. The plugin includes all Cortex tools. If its MCP server was disabled, run `copilot plugins enable cortex --mcp`. Next, allow Cortex tools to run without repeated approval buttons. Use the Cortex-scoped setting for your provider: - **Codex:** set `default_tools_approval_mode = "approve"` under `[plugins."cortex@socra".mcp_servers.cortex]` in your Codex config. If you previously restricted tools there, set `enabled = true`, clear `disabled_tools`, and remove an `enabled_tools` allowlist. - **Claude Code:** in `/permissions`, add the Allow rule `mcp__plugin_cortex_cortex__*` for the Cortex plugin to your user settings, so it applies in future sessions. Existing deny rules still apply. - **Cursor:** add `cortex:*` to the MCP allowlist under **Settings → Agents → Approvals & Execution**, preserving existing entries. - **GitHub Copilot CLI:** start with `copilot --allow-tool='cortex'` to allow Cortex tools for that session. Use this command each time you start Copilot, including the verification session below. These settings skip tool confirmations for Cortex. Agree on a knowledge change with the agent in the conversation; after your approval, it can save without another Cortex tool-permission button. The plugin's session instructions supply that agreement process without requiring an `AGENTS.md` file. Instructions guide behavior but do not enforce it, and existing deny rules or organization policy may still require confirmation or block a tool. You can retain normal confirmations instead. Current provider references: [Codex MCP](https://learn.chatgpt.com/docs/extend/mcp?surface=cli), [Claude Code permissions](https://code.claude.com/docs/en/permissions#mcp), [Cursor permissions](https://prod.cursor.com/docs/reference/permissions#mcp-allowlist-format), and [Copilot CLI](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference). ### Verify the installation Start a new session and ask: ```text Use Cortex to list the Modules I can access. Make a real Cortex tool call; an empty list is valid. Separately, report whether this new conversation received persistent Cortex guidance and what it requires. Do not change anything. ``` Check both results: the coding agent makes a real Cortex call and returns the Module list, and the new session reports receiving Cortex guidance and explains what it requires. A new Account can return an empty list. If the connection works but guidance is missing, check that the SessionStart hook is trusted and enabled, then start another session. Tool access alone does not confirm that the instructions loaded. ## Connect ChatGPT Install **Socra Cortex** from the ChatGPT plugin store, connect your Socra Account, and add the instructions that teach ChatGPT when to use Cortex. You do not need a terminal or a custom Cloud Project for this path. [Open guided setup](https://cortex.socra.com/setup?method=plugin&agent=chatgpt&step=store) to follow the preferred plugin path one step at a time. ### Install the plugin Open [Socra Cortex in ChatGPT](https://chatgpt.com/plugins/plugin_asdk_app_6a76351f23588191a3a3f5681f601042). Confirm the developer is **socra** and select **Install plugin**. If it is already installed, continue. If your workspace blocks installation, ask its administrator to enable Cortex or choose another supported agent in [guided setup](https://cortex.socra.com/setup). ### Connect your Account Installation or connection opens Socra sign-in in your browser. Select the same Account you use in Cortex, review access, and approve it there. If you already completed this during installation, continue without reconnecting. If ChatGPT waits until first use to connect, start a chat, type `@`, select **Socra Cortex**, and ask it to list your Modules. Follow the sign-in prompt. If no prompt appears, open **Settings → Plugins → Socra Cortex** and connect it. Signing in to the Cortex website alone does not authorize ChatGPT. ### Enable all Cortex tools Open **Settings → Plugins → Socra Cortex → Permissions** and select **Allow all actions**. Change the permission inside Cortex's settings, rather than the general Plugins setting. If it already says **Allow all**, continue. This allows ChatGPT to read and take actions in Cortex without repeated tool-confirmation buttons. The suggested instructions below introduce Cortex and how Module owners govern shared knowledge. They guide behavior but do not enforce it. You can keep **Always ask** to confirm each call; workspace policy may limit your choices. For Claude, open **Settings → Connectors → Socra Cortex → Tool permissions**. Set both **Read-only tools** and **Write/delete tools** to **Always allow** using each group's menu. With the Cortex instructions in place, agree on the knowledge change with Claude in the conversation; Claude can then save it without an extra tool-approval button. A custom connector may be named **Cortex**. In a new chat, make sure it is on under **+ → Connectors**. **Needs approval** retains tool confirmations, and organization policy still applies. Controls checked on September 5, 2026 against [ChatGPT permissions](https://learn.chatgpt.com/docs/permissions) and [Claude connector permissions](https://support.claude.com/en/articles/11176164-use-connectors-to-extend-claude-s-capabilities). ### Add instructions These suggested instructions teach your agent to Flash the right knowledge before acting, without reminders. They also teach it to suggest creating or updating Modules when you share useful knowledge or preferences. You can edit or skip them. Open **Settings → Personalization → Custom instructions**. You can also open **Personalization** from your profile menu. Add the following alongside your existing instructions and save if your host shows a Save action. On mobile, look for **Customize ChatGPT** and keep customization enabled. [Open just the Cortex instructions as Markdown](https://workspace.socra.com/docs/cortex/instructions.md). This link serves the current instructions without the installation guide. ```text Cortex is the single source of truth for a person or team’s specific knowledge, shared across agents, conversations, and tools. Its Modules define what should be and why. Dependencies identify prerequisite Modules. Flash loads a Module and all its Dependencies. Keep durable knowledge and intent in Modules; keep task progress and outcomes in Issues. Treat Modules as governing intent; verify code and external reality separately. Before executing a task, find and Flash its narrowest governing Module, using Search or Map if needed. If none exists, propose one. Reuse or create an Issue for that task under the same Module. Mark the Issue in progress when starting. Comment on progress and blockers. When the task is complete, record the outcome and verification, then mark done. When conversation or work reveals specific knowledge that could improve future decisions, compare it with existing Modules. Propose an update or new Module for missing or changed knowledge, preserving the decision and its reason. Show exact Before and After blocks for changed content and Dependencies; show full content and Dependencies for new Modules. Explain conflicts and recommend a resolution. Continue independent work while approval is pending. Save only after explicit owner approval, then Flash to verify. ``` These are the complete, unmodified instructions from the [canonical Cortex session-start instructions](https://github.com/socra/agent-plugins/blob/main/shared/cortex/session-start.md). If the full text does not fit, use a project's instructions and work with Cortex in that project. Do not replace your other instructions. A message in one conversation does not configure future conversations. For another MCP client, use its persistent or project instructions. For Claude, use **Settings → General → Instructions for Claude**. Supported coding-agent plugins include the full guidance in their SessionStart hook; approve the hook and start a new session. ### Check the connection Start a new conversation with Socra Cortex enabled. Send: ```text Use Cortex to list the Modules I can access. Make a real Cortex tool call; an empty list is valid. Separately, report whether this new conversation received persistent Cortex guidance and what it requires. Do not change anything. ``` Check that ChatGPT calls Cortex and returns the Module list. An empty list is normal for a new Account. An access error or a response without a tool call does not confirm the connection; follow [Troubleshoot Cortex](https://workspace.socra.com/docs/cortex/troubleshooting). Check the guidance report separately. If you saved instructions but the new conversation did not receive them, reopen Custom instructions to check the saved text and that customization is enabled. For project instructions, start the conversation inside that project. If you skipped instructions, the connection can still work; report the guidance as skipped. ## Connect Grok Connect Grok through a custom MCP connector, found under **Plugins → Connectors**. There is no Cortex plugin for Grok. Save the instructions below separately; this connection does not install a SessionStart hook. [Open guided Grok setup](https://cortex.socra.com/setup?method=mcp&agent=grok&step=project) for one action at a time. Keep Grok and the Socra Cloud Console open in separate tabs. ### 1. Prepare your Socra Project Open [Cloud Projects](https://platform.socra.com/projects). Choose a Project you can manage, or create one. In that Project, open **Enabled services → Enable service → Cortex**. Open **OAuth overview → Set up OAuth**, use **Cortex for Grok** as the application name, and save the consent information. All the settings below must belong to this same Project. If a newly created Project is not immediately available, wait a moment and retry. For a Grok Business or Enterprise team, an administrator may need to provision the connector before members connect it. ### 2. Register the Grok client Open [OAuth clients](https://platform.socra.com/oauth/clients) in your Project and register a client: - **Client name:** Cortex for Grok - **Application type:** Single-page app - **Redirect URLs:** the exact URL below, including its final slash - **JavaScript origins:** leave empty ```text https://grok.com/connectors-oauth-exchange-code/ ``` Select **Create client** and copy its client ID. This connection uses PKCE and does not require a client secret. Use your own client ID; this guide never asks you to paste credentials into Cortex onboarding. ### 3. Add the custom connector In [Grok](https://grok.com/connectors), open **Plugins → Connectors → New Connector → Custom**. Enter **Socra Cortex** as the name and use this **Server URL**: ```text https://cortex.socra.cloud/mcp ``` Select **Add Connector**. Grok discovers Cortex and displays **OAuth Credentials Required**. ### 4. Authorize your Account In Grok's OAuth form: | Field | Value | | ---------------------- | --------------------------------------------------------------- | | Client ID | Your new Socra client ID | | Client Secret | Leave empty | | Authorization Endpoint | Keep the discovered `https://account.socra.com/oauth/authorize` | | Token Endpoint | Keep the discovered `https://oauth.socra.cloud/oauth/token` | | Scopes | Leave empty | | Token Auth Method | **none (PKCE only, recommended)** | Select **Save & Connect**. In the popup, sign in to Socra, choose the Account you use in Cortex, and approve access. Allow the popup if your browser blocks it. Return to Grok: **Socra Cortex** should appear under **Connected**. If it is already connected to the intended Account, continue without reconnecting. If authorization fails, check the exact redirect URL, client ID, application type, and that Cortex is enabled in the same Project. Signing into the Cortex website alone does not connect Grok. ### 5. Enable all Cortex tools Open **Plugins → Connectors → Socra Cortex**. Check for **All tools enabled**. Selecting a tool toggles it, so select only tools that are off until all are enabled. Tool enablement is separate from approval. Grok's web connector currently has no verified **Always allow** control equivalent to ChatGPT or Claude. If Grok requests approval for an action, review it there. Do not use Grok Build, Grok Bot, or xAI API permission instructions for this web connection. ### 6. Save persistent Cortex instructions These suggested instructions teach your agent to Flash the right knowledge before acting, without reminders. They also teach it to suggest creating or updating Modules when you share useful knowledge or preferences. You can edit or skip them. Open your profile menu → **Settings → Customize → Custom**. Add the following alongside your existing instructions and select **Save**. Closing Settings before saving discards the edit. Reopen Customize to check the saved text. [Open just the Cortex instructions as Markdown](https://workspace.socra.com/docs/cortex/instructions.md). This link serves the current instructions without the installation guide. ```text Cortex is the single source of truth for a person or team’s specific knowledge, shared across agents, conversations, and tools. Its Modules define what should be and why. Dependencies identify prerequisite Modules. Flash loads a Module and all its Dependencies. Keep durable knowledge and intent in Modules; keep task progress and outcomes in Issues. Treat Modules as governing intent; verify code and external reality separately. Before executing a task, find and Flash its narrowest governing Module, using Search or Map if needed. If none exists, propose one. Reuse or create an Issue for that task under the same Module. Mark the Issue in progress when starting. Comment on progress and blockers. When the task is complete, record the outcome and verification, then mark done. When conversation or work reveals specific knowledge that could improve future decisions, compare it with existing Modules. Propose an update or new Module for missing or changed knowledge, preserving the decision and its reason. Show exact Before and After blocks for changed content and Dependencies; show full content and Dependencies for new Modules. Explain conflicts and recommend a resolution. Continue independent work while approval is pending. Save only after explicit owner approval, then Flash to verify. ``` These are the complete, unmodified [canonical Cortex instructions](https://github.com/socra/agent-plugins/blob/main/shared/cortex/session-start.md). They explain how Cortex connects knowledge and work, how understanding can carry across conversations, and how Module owners govern shared knowledge. They leave the agent room to use its judgment and do not enforce an approval boundary. Preserve any instructions you already use. ### 7. Verify in a new chat Start a new conversation and send: ```text Use Cortex to list the Modules I can access. Make a real Cortex tool call; an empty list is valid. Separately, report whether this new conversation received persistent Cortex guidance and what it requires. Do not change anything. ``` Check that Grok actually calls Cortex and returns a list. An empty list is valid for a new Account. A response without a tool call or an access error does not confirm the connection. If Grok asks for an account prerequisite such as age confirmation, complete it and retry the prompt. Do not create a Module just to test the connection. Check the guidance report separately. If you saved instructions but the new conversation did not receive them, reopen **Settings → Customize → Custom**, check the saved text, and start another conversation. If you skipped instructions, the connection can still work; report the guidance as skipped. ### Sources and verification The connector entry points follow [xAI's connector documentation](https://docs.x.ai/grok/connectors), with team restrictions in [connector management](https://docs.x.ai/grok/connector-management). The OAuth field values, connected status, tool toggles, saved Custom instructions, and a real read-only Cortex `context_map` call were checked in the signed-in Grok web interface on September 5, 2026. Provider interfaces can change; use the labels shown in your account and report differences through [troubleshooting](https://workspace.socra.com/docs/cortex/troubleshooting). ## Configure the Cortex MCP server Connect ChatGPT, Claude, or another MCP client to Cortex. Use this guide when you set up the connection yourself. The integration uses the [hosted Cortex MCP server](https://workspace.socra.com/docs/cortex/reference/mcp). You do not need to install a server on your computer. An MCP integration provides Cortex tools but does not install the SessionStart context included with a Cortex agent plugin. If you use a supported coding agent, follow [Agent plugins](https://workspace.socra.com/docs/cortex/integrations/coding-agents) instead. [Open guided MCP setup](https://cortex.socra.com/setup?method=mcp&step=agent) to follow these instructions one step at a time. For the preferred ChatGPT store installation, use [Connect ChatGPT](https://workspace.socra.com/docs/cortex/integrations/chatgpt). Grok uses a different, secret-free PKCE flow: follow [Connect Grok](https://workspace.socra.com/docs/cortex/integrations/grok). ### Before you start You need an Account and a Cloud Project that you can manage. If you do not have one, create a Cloud Project in the [Cloud Console](https://platform.socra.com/projects) at platform.socra.com. Your client must support remote HTTP MCP and follow the `resource_metadata` URL in Cortex's 401 OAuth challenge. Test the connection in your host. Use the [CLI](https://workspace.socra.com/docs/cortex/reference/cli) if the host cannot connect. The hosted MCP surface includes tools that can write and delete. Review the [Cortex security model](https://workspace.socra.com/docs/cortex/administration/security) and your client's approval policy before you connect. Review the discovered tools before you enable them in a conversation. ### Set up the integration Enable Cortex and configure OAuth on your Cloud Project. Then connect your MCP client. #### Enable Cortex ##### CLI Run: ```bash socra service enable cortex --project PROJECT_ID ``` Replace `PROJECT_ID` with your Cloud Project ID. ##### Cloud Console In the Cloud Console, open [Enabled services](https://platform.socra.com/service-usage/services). Select **Enable service**, then enable **Cortex** for the Cloud Project. #### Configure OAuth Configure the information that Socra shows when a user authorizes the integration. ##### CLI Configure the OAuth consent information: ```bash socra oauth config set PROJECT_ID --name "Cortex" ``` Replace `PROJECT_ID` with your Cloud Project ID. ##### Cloud Console In the Cloud Console, open [OAuth overview](https://platform.socra.com/oauth). Select **Set up OAuth**. Use **Cortex** as the application name. Add any policy information that users should see during authorization. #### Configure your MCP client Select the client that you want to connect to the Cortex MCP server. ##### ChatGPT ###### Register an OAuth client Developer mode availability depends on your ChatGPT account and workspace policy. In ChatGPT, open **Settings → Security and login**. Turn on **Developer mode**. Open [ChatGPT Plugins](https://chatgpt.com/plugins). Select the plus button and start a new connection. Enter **Cortex** as the name. Enter this MCP server URL: ```url https://cortex.socra.cloud/mcp ``` Copy the callback URL that ChatGPT shows. Keep the ChatGPT page open. In the Cloud Console, open [OAuth clients](https://platform.socra.com/oauth/clients). Register a **Web** client named **Cortex for ChatGPT**. Add the ChatGPT callback URL as a redirect URL. Leave JavaScript origins empty. Create the OAuth client. Then create a client secret. Copy the secret immediately. Socra shows it one time. ###### Connect ChatGPT Return to the new connection in ChatGPT. Select OAuth. Enter the client ID and client secret from Socra. Create the connection. Review the Cortex tools that ChatGPT finds. Then connect your Account and approve access. ##### Claude ###### Register an OAuth client In the Cloud Console, open [OAuth clients](https://platform.socra.com/oauth/clients). Register a **Web** client named **Cortex for Claude**. Add this redirect URL: ```url https://claude.ai/api/mcp/auth_callback ``` Leave JavaScript origins empty. Create the OAuth client. Then create a client secret. Copy the secret immediately. Socra shows it one time. ###### Connect Claude On Free, Pro, or Max, follow these steps. Free allows one custom connector: 1. Open **Customize → Connectors** in Claude. 2. Select the plus button, then select **Add custom connector**. 3. Enter **Cortex** as the name. 4. Enter `https://cortex.socra.cloud/mcp` as the remote MCP server URL. 5. Open **Advanced settings**. Enter the client ID and client secret from Socra. 6. Select **Add**, then select **Connect**. For a Team or Enterprise plan, an Owner must add Cortex from **Organization settings → Connectors**. Select **Add → Custom → Web**. Enter the same server URL and OAuth credentials. Each member can then open **Customize → Connectors** and select **Connect**. Select your Account and approve access. ##### Custom ###### Register an OAuth client Start the custom MCP setup in your client. Find the OAuth callback URL that the client provides. In the Cloud Console, open [OAuth clients](https://platform.socra.com/oauth/clients). Register a **Web** client. Add the callback URL as a redirect URL. Leave JavaScript origins empty. Create the OAuth client. Then create a client secret. Copy the secret immediately. Socra shows it one time. ###### Connect your client Enter these values in your MCP client: - **Name:** Cortex - **Server URL:** `https://cortex.socra.cloud/mcp` - **Authentication:** OAuth - **Client ID:** The OAuth client ID from Socra - **Client secret:** The OAuth client secret from Socra Connect your Account and approve access. ### Enable Cortex tools In ChatGPT, open **Settings → Plugins → Socra Cortex → Permissions** and select **Allow all actions** for Cortex. A custom connector may be named **Cortex**. In Claude, open **Settings → Connectors → Cortex → Tool permissions**. Set both **Read-only tools** and **Write/delete tools** to **Always allow**. In a new chat, check that Cortex is on under **+ → Connectors**. In another client, enable all Cortex tools and use its Cortex-scoped always-allow setting if available. These controls vary by host and organization policy. Keep unrelated permissions unchanged. The instructions below teach the agent to ask for your agreement in conversation before saving knowledge; they do not enforce an approval boundary. For Grok's different controls and PKCE connection, follow [Connect Grok](https://workspace.socra.com/docs/cortex/integrations/grok#5-enable-all-cortex-tools). ### Add persistent instructions Add the [suggested Cortex instructions](https://workspace.socra.com/docs/cortex/installation#suggested-instructions) to teach your agent to Flash the right knowledge before acting and suggest creating or updating Modules when you share useful knowledge or preferences. A direct MCP connection needs these saved separately. You can edit or skip them. In Claude, use **Settings → General → Instructions for Claude**. In other clients, use their persistent or project instructions. Keep existing instructions. ### Verify the connection Start a new conversation with Cortex enabled. Use this prompt: ```text Use Cortex to list the Modules I can access. Make a real Cortex tool call; an empty list is valid. Separately, report whether this new conversation received persistent Cortex guidance and what it requires. Do not change anything. ``` Verify that the agent makes a real Cortex call and returns a Module list. An empty list confirms access for a new Account. An error or an answer without a tool call does not confirm the connection. Check the guidance report separately. If you saved instructions but the new conversation did not receive them, check their saved location and scope in the host. Start the conversation inside the project if you used project instructions. If you skipped instructions, the connection can still work; report the guidance as skipped. Stop after verification. When you are ready to use Cortex, follow the [Cortex Quickstart](https://workspace.socra.com/docs/cortex/get-started/first-workflow). ## Troubleshoot Cortex Start with the observable failure, then verify the boundary immediately before it. ### The setup command detects no agents The [`socra cortex setup` command](https://workspace.socra.com/docs/cortex/integrations/coding-agents#install-automatically) detects Codex, Claude Code, Cursor, and GitHub Copilot CLI. Confirm that at least one supported host is installed for the same operating-system user. For command-line hosts, confirm that the executable is available on `PATH`. Cursor can be detected from its standard user installation even when its command-line launcher is unavailable. ### The plugin is installed but Cortex is unavailable Restart the agent host after `socra cortex setup` installs or updates a plugin. SessionStart hooks and MCP configuration load when the host starts a new session. Run `socra cortex setup` again. A current installation remains unchanged; an outdated installation is updated. ### OAuth does not open or complete Confirm that the host connected to `https://cortex.socra.cloud/mcp` and follows the `resource_metadata` URL in the server's `401` challenge. See the [Cortex MCP endpoint reference](https://workspace.socra.com/docs/cortex/reference/mcp#endpoint) for connection details. If you are configuring a custom client, verify its client type, redirect URL, and OAuth credentials against the [custom MCP guide](https://workspace.socra.com/docs/cortex/guides/mcp). A first-party plugin does not require you to create or enter a client secret. ### CLI commands fail or return incomplete data Update the [CLI and its installed namespaces](https://workspace.socra.com/docs/cortex/reference/cli): ```bash socra update ``` Retry the same command. A stale Cortex CLI can produce failures that resemble a backend outage, including incomplete [Module](https://workspace.socra.com/docs/cortex/concepts/modules-and-map) or [Issue](https://workspace.socra.com/docs/cortex/concepts/issues-and-coordination) results. ### The agent does not use Cortex knowledge Confirm that the agent called a Cortex tool and [flashed the relevant Module](https://workspace.socra.com/docs/cortex/concepts/flashing-context). Assignment, plugin installation, and session start do not preload the complete knowledge map. Cortex output remains tool context. Check the host's instruction precedence, approval policy, and repository instruction files when the agent retrieves the correct Module but does not apply it. ## After installation The connection is verified when the configured agent makes a real Cortex call and receives a result. A new Account can return an empty list. An access error or a response without a call is not verification. When you are ready to use Cortex, continue to the [quickstart](https://workspace.socra.com/docs/cortex/get-started/first-workflow). Installation alone does not require creating knowledge.