fix(codex): stabilize awsknowledge MCP startup with codex-specific compatibility transport

docs/TROUBLESHOOTING.md

@@ -212,6 +212,42 @@ Replace `RUN_ID` with the workflow run ID from your pull request's **Checks** ta
 - **Repository collaborators** (write access) can re-run workflows directly.
 - **Fork contributors** cannot re-run workflows on the upstream repo. Ask a maintainer to re-run the failed jobs, or push an empty commit (`git commit --allow-empty -m "retry CI"`) to trigger a fresh run.
 
+## Codex
+
+### MCP Startup Failure: `awsknowledge`
+
+If Codex reports an `awsknowledge` startup error similar to:
+
+```text
+Transport channel closed, when send initialized notification
+```
+
+the plugin now uses a Codex-specific MCP configuration that proxies `awsknowledge` through local stdio using `uvx fastmcp run`.
+
+1. Verify Codex is using the Codex manifest and MCP file for your plugin:
+   - `.codex-plugin/plugin.json` points to `./.mcp.codex.json`
+2. Verify `uvx` is installed and available in `PATH`:
+
+   ```bash
+   uvx --version
+   ```
+
+3. Restart Codex and retry plugin startup.
+
+If the issue persists, collect the full startup error and open or comment on:
+
+- https://github.com/awslabs/agent-plugins/issues/130
+
+### Codex Debug Override: direct HTTP transport
+
+For diagnostics only, you can force the previous direct HTTP transport path:
+
+1. Edit the plugin's `.codex-plugin/plugin.json`
+2. Change `mcpServers` from `./.mcp.codex.json` to `./.mcp.json`
+3. Restart Codex
+
+Use this only for debugging and rollback. The Codex default should remain `./.mcp.codex.json`.
+
 ## Other AI Assistants
 
 Support for additional AI assistants will be added here as the plugin system expands.

plugins/databases-on-aws/.codex-plugin/plugin.json

@@ -26,7 +26,7 @@
     "sql"
   ],
   "skills": "./skills/",
-  "mcpServers": "./.mcp.json",
+  "mcpServers": "./.mcp.codex.json",
   "interface": {
     "displayName": "Databases on AWS",
     "shortDescription": "Design schemas, query data, and choose the right AWS database path.",

plugins/databases-on-aws/.mcp.codex.json

@@ -0,0 +1,27 @@
+{
+  "mcpServers": {
+    "awsknowledge": {
+      "args": [
+        "fastmcp",
+        "run",
+        "https://knowledge-mcp.global.api.aws"
+      ],
+      "command": "uvx",
+      "env": {
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      },
+      "timeout": 120000,
+      "type": "stdio"
+    },
+    "aurora-dsql": {
+      "command": "uvx",
+      "args": [
+        "awslabs.aurora-dsql-mcp-server@latest"
+      ],
+      "disabled": true,
+      "env": {
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      }
+    }
+  }
+}

plugins/deploy-on-aws/.codex-plugin/plugin.json

@@ -22,7 +22,7 @@
     "architecture"
   ],
   "skills": "./skills/",
-  "mcpServers": "./.mcp.json",
+  "mcpServers": "./.mcp.codex.json",
   "interface": {
     "displayName": "Deploy on AWS",
     "shortDescription": "Pick AWS services, estimate cost, and generate infrastructure.",

plugins/deploy-on-aws/.mcp.codex.json

@@ -0,0 +1,35 @@
+{
+  "mcpServers": {
+    "awsiac": {
+      "args": [
+        "awslabs.aws-iac-mcp-server@latest"
+      ],
+      "command": "uvx"
+    },
+    "awsknowledge": {
+      "args": [
+        "fastmcp",
+        "run",
+        "https://knowledge-mcp.global.api.aws"
+      ],
+      "command": "uvx",
+      "env": {
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      },
+      "timeout": 120000,
+      "type": "stdio"
+    },
+    "awspricing": {
+      "args": [
+        "awslabs.aws-pricing-mcp-server@latest"
+      ],
+      "command": "uvx",
+      "disabled": false,
+      "env": {
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      },
+      "timeout": 120000,
+      "type": "stdio"
+    }
+  }
+}

plugins/migration-to-aws/.codex-plugin/plugin.json

@@ -20,7 +20,7 @@
     "fargate"
   ],
   "skills": "./skills/",
-  "mcpServers": "./.mcp.json",
+  "mcpServers": "./.mcp.codex.json",
   "interface": {
     "displayName": "Migration to AWS",
     "shortDescription": "Discover GCP workloads and plan a migration path to AWS.",

plugins/migration-to-aws/.mcp.codex.json

@@ -0,0 +1,28 @@
+{
+  "mcpServers": {
+    "awsknowledge": {
+      "args": [
+        "fastmcp",
+        "run",
+        "https://knowledge-mcp.global.api.aws"
+      ],
+      "command": "uvx",
+      "env": {
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      },
+      "timeout": 120000,
+      "type": "stdio"
+    },
+    "awspricing": {
+      "args": [
+        "awslabs.aws-pricing-mcp-server@latest"
+      ],
+      "command": "uvx",
+      "env": {
+        "FASTMCP_LOG_LEVEL": "ERROR"
+      },
+      "timeout": 120000,
+      "type": "stdio"
+    }
+  }
+}