Skip to content

Codex mcp instructions #719

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
coleam00 merged 2 commits into from
Sep 20, 2025
Merged

Codex mcp instructions #719

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3e9d812
Add Codex MCP configuration instructions
coleam00 Sep 20, 2025
ed8451b
Finalizing Codex instructions
coleam00 Sep 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 83 additions & 27 deletions archon-ui-main/src/features/mcp/components/McpConfigSection.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ const ideConfigurations: Record<
steps: string[];
configGenerator: (config: McpServerConfig) => string;
supportsOneClick?: boolean;
platformSpecific?: boolean;
}
> = {
claudecode: {
Expand Down Expand Up @@ -56,6 +57,42 @@ const ideConfigurations: Record<
2,
),
},
codex: {
title: "Codex Configuration",
steps: [
"Step 1: Install mcp-remote globally: npm install -g mcp-remote",
"Step 2: Add configuration to ~/.codex/config.toml",
"Step 3: Find your exact mcp-remote path by running: npm root -g",
"Step 4: Replace the path in the configuration with your actual path + /mcp-remote/dist/proxy.js",
],
configGenerator: (config) => {
const isWindows = navigator.platform.toLowerCase().includes("win");

if (isWindows) {
return `[mcp_servers.archon]
command = 'node'
args = [
'C:/Users/YOUR_USERNAME/AppData/Roaming/npm/node_modules/mcp-remote/dist/proxy.js',
'http://${config.host}:${config.port}/mcp'
]
env = {
APPDATA = 'C:\\Users\\YOUR_USERNAME\\AppData\\Roaming',
LOCALAPPDATA = 'C:\\Users\\YOUR_USERNAME\\AppData\\Local',
SystemRoot = 'C:\\WINDOWS',
COMSPEC = 'C:\\WINDOWS\\system32\\cmd.exe'
}`;
} else {
return `[mcp_servers.archon]
command = 'node'
args = [
'/usr/local/lib/node_modules/mcp-remote/dist/proxy.js',
'http://${config.host}:${config.port}/mcp'
]
env = { }`;
}
},
platformSpecific: true,
},
Comment on lines +60 to +95
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Sep 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Guard navigator usage and unify platform detection.

Direct navigator access can break under SSR/tests and detection is duplicated. Add a small helper and reuse it here.

Add once near the top (outside the component):

const isWindowsPlatform = (): boolean =>
  typeof navigator !== "undefined" && /win/i.test(navigator.userAgent || navigator.platform || "");

Then update this block:

-      const isWindows = navigator.platform.toLowerCase().includes("win");
+      const isWindows = isWindowsPlatform();

Also use isWindowsPlatform() where you render the platform label/note (see comments below).

🤖 Prompt for AI Agents 
In archon-ui-main/src/features/mcp/components/McpConfigSection.tsx around lines
60 to 95, replace the direct navigator.platform usage with a guarded helper to
avoid SSR/test failures and centralize platform detection: add a top-level
isWindowsPlatform helper that checks typeof navigator !== "undefined" and tests
navigator.userAgent or navigator.platform for "win", then use
isWindowsPlatform() here (and wherever the component renders platform
labels/notes) instead of navigator.platform.toLowerCase().includes("win") so
detection is safe and unified across the file.

cursor: {
title: "Cursor Configuration",
steps: [
Expand Down Expand Up @@ -144,27 +181,6 @@ const ideConfigurations: Record<
2,
),
},
augment: {
title: "Augment Configuration",
steps: [
"Open Augment settings",
"Navigate to Extensions > MCP",
"Add the configuration shown below",
"Reload configuration",
],
configGenerator: (config) =>
JSON.stringify(
{
mcpServers: {
archon: {
url: `http://${config.host}:${config.port}/mcp`,
},
},
},
null,
2,
),
},
};

export const McpConfigSection: React.FC<McpConfigSectionProps> = ({ config, status, className }) => {
Expand Down Expand Up @@ -240,25 +256,47 @@ export const McpConfigSection: React.FC<McpConfigSectionProps> = ({ config, stat
value={selectedIDE}
onValueChange={(value) => setSelectedIDE(value as SupportedIDE)}
>
<TabsList className="grid grid-cols-4 lg:grid-cols-7 w-full">
<TabsList className="grid grid-cols-3 lg:grid-cols-7 w-full">
<TabsTrigger value="claudecode">Claude Code</TabsTrigger>
<TabsTrigger value="gemini">Gemini</TabsTrigger>
<TabsTrigger value="codex">Codex</TabsTrigger>
<TabsTrigger value="cursor">Cursor</TabsTrigger>
<TabsTrigger value="windsurf">Windsurf</TabsTrigger>
<TabsTrigger value="cline">Cline</TabsTrigger>
<TabsTrigger value="kiro">Kiro</TabsTrigger>
<TabsTrigger value="augment">Augment</TabsTrigger>
</TabsList>

<TabsContent value={selectedIDE} className="mt-6 space-y-4">
{/* Configuration Title and Steps */}
<div>
<h4 className="text-lg font-semibold text-gray-800 dark:text-white mb-3">{selectedConfig.title}</h4>
<ol className="list-decimal list-inside space-y-2 text-sm text-gray-600 dark:text-zinc-400">
{selectedConfig.steps.map((step) => (
<li key={step}>{step}</li>
))}
{selectedConfig.steps.map((step) => {
// Highlight npm install command for Codex
if (selectedIDE === "codex" && step.includes("npm install -g mcp-remote")) {
const parts = step.split("npm install -g mcp-remote");
return (
<li key={step}>
{parts[0]}
<code className="font-mono font-semibold bg-zinc-800 text-cyan-400 px-1.5 py-0.5 rounded">
npm install -g mcp-remote
</code>
{parts[1]}
</li>
);
}
return <li key={step}>{step}</li>;
})}
</ol>
{/* macOS note for Codex */}
{selectedIDE === "codex" && (
<p className="mt-2 text-sm text-gray-600 dark:text-zinc-400 italic">
Note: On macOS with Homebrew on Apple Silicon, the path might be{" "}
<code className="text-xs font-mono bg-zinc-800 px-1 rounded">
/opt/homebrew/lib/node_modules/mcp-remote/dist/proxy.js
</code>
</p>
)}
</div>

{/* Special Commands for Claude Code */}
Expand All @@ -280,10 +318,28 @@ export const McpConfigSection: React.FC<McpConfigSectionProps> = ({ config, stat
</div>
)}

{/* Platform-specific note for Codex */}
{selectedIDE === "codex" && (
<div className={cn("p-3 rounded-lg", glassmorphism.background.yellow, glassmorphism.border.yellow)}>
<p className="text-sm text-yellow-700 dark:text-yellow-300">
<span className="font-semibold">Platform Note:</span> The configuration below shows{" "}
{navigator.platform.toLowerCase().includes("win") ? "Windows" : "Linux/macOS"} format. Adjust paths
according to your system. This setup is complex right now because Codex has some bugs with MCP currently.
</p>
</div>
)}
Comment on lines +321 to +330
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Sep 20, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

glassmorphism.yellow is undefined — styles won’t apply.

styles.ts defines cyan/blue/purple/orange but not yellow. Use an existing color to avoid “undefined” classes.

-            <div className={cn("p-3 rounded-lg", glassmorphism.background.yellow, glassmorphism.border.yellow)}>
+            <div className={cn("p-3 rounded-lg", glassmorphism.background.orange, glassmorphism.border.orange)}>

Also replace navigator usage here with isWindowsPlatform():

-                {navigator.platform.toLowerCase().includes("win") ? "Windows" : "Linux/macOS"} format.
+                {isWindowsPlatform() ? "Windows" : "Linux/macOS"} format.

Committable suggestion skipped: line range outside the PR's diff.

🤖 Prompt for AI Agents 
In archon-ui-main/src/features/mcp/components/McpConfigSection.tsx around lines
321 to 330, replace the undefined glassmorphism.yellow classes with an existing
color (for example glassmorphism.background.orange and
glassmorphism.border.orange) so the styling resolves, and replace the direct
navigator.platform usage with a call to isWindowsPlatform() (and ensure that
helper is imported/available) when choosing the displayed platform string and
the conditional rendering check.


{/* Configuration Display */}
<div className={cn("relative rounded-lg p-4", glassmorphism.background.subtle, glassmorphism.border.default)}>
<div className="flex items-center justify-between mb-2">
<span className="text-xs font-medium text-zinc-500 dark:text-zinc-400">Configuration</span>
<span className="text-xs font-medium text-zinc-500 dark:text-zinc-400">
Configuration
{selectedIDE === "codex" && (
<span className="ml-2 text-xs text-yellow-600 dark:text-yellow-400">
({navigator.platform.toLowerCase().includes("win") ? "Windows" : "Linux/macOS"})
</span>
)}
</span>
<Button variant="outline" size="sm" onClick={handleCopyConfig}>
<Copy className="w-3 h-3 mr-1" />
Copy
Expand Down
2 changes: 1 addition & 1 deletion archon-ui-main/src/features/mcp/types/mcp.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ export interface McpSessionInfo {
}

// we actually support all ides and mcp clients
export type SupportedIDE = "windsurf" | "cursor" | "claudecode" | "cline" | "kiro" | "augment" | "gemini";
export type SupportedIDE = "windsurf" | "cursor" | "claudecode" | "cline" | "kiro" | "codex" | "gemini";

export interface IdeConfiguration {
ide: SupportedIDE;
Expand Down