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

[faishal882]

Summary

This PR fixes Codex startup failures for awsknowledge MCP by introducing a Codex-specific compatibility transport path.

Issue: #130

Problem

Users running Codex could hit MCP startup failure for awsknowledge with:

Transport channel closed, when send initialized notification

Observed behavior from reproduction:

• POST JSON-RPC initialize to https://knowledge-mcp.global.api.aws returns valid MCP init response.
• GET/stream path behavior can redirect/close, which can break Codex streamable-http startup flow.

This caused handshake failure during the initialized notification phase.

What changed

1) Added Codex-specific MCP configs in affected plugins

New files:

• plugins/deploy-on-aws/.mcp.codex.json
• plugins/migration-to-aws/.mcp.codex.json
• plugins/databases-on-aws/.mcp.codex.json

In these Codex-specific files, awsknowledge uses a local stdio proxy transport:

{
  "type": "stdio",
  "command": "uvx",
  "args": ["fastmcp", "run", "https://knowledge-mcp.global.api.aws"],
  "env": { "FASTMCP_LOG_LEVEL": "ERROR" },
  "timeout": 120000
}

2) Pointed Codex manifests to Codex-specific MCP configs

Updated:

• plugins/deploy-on-aws/.codex-plugin/plugin.json
• plugins/migration-to-aws/.codex-plugin/plugin.json
• plugins/databases-on-aws/.codex-plugin/plugin.json

Change:

• from "mcpServers": "./.mcp.json"
• to "mcpServers": "./.mcp.codex.json"

3) Added Codex troubleshooting and rollback guidance

Updated:

• docs/TROUBLESHOOTING.md

Added:

• Codex-specific awsknowledge startup failure section
• verification steps for Codex MCP file wiring
• debug override instructions to temporarily revert Codex to direct HTTP mode
• explicit reference to issue MCP Client awsknowledge Fails to Start Due to Transport Channel Closure During Handshake #130

Why this approach

• Limits risk: scoped to Codex only; non-Codex behavior remains unchanged.
• Deterministic startup path: avoids direct streamable-http fragility for this endpoint in Codex.
• Provides operator escape hatch: direct HTTP override path is documented.

Validation

Ran full project build requirements via mise run build:

• markdown lint
• manifest/schema validation
• cross-reference validation
• formatting check
• reference/size validation
• security scans (bandit, semgrep, gitleaks, checkov, grype)

All checks passed.

Notes

• This PR intentionally does not include unrelated untracked planning docs from local workspace.
• No changes were made to Claude plugin manifests or shared .mcp.json files.

[Copilot]

Pull request overview

This PR addresses Codex startup failures for the awsknowledge MCP server by routing Codex to a compatibility transport that proxies awsknowledge over local stdio, avoiding fragile streamable-http behavior for that endpoint.

Changes:

• Added .mcp.codex.json MCP configurations for three Codex-packaged plugins, switching awsknowledge to a local uvx fastmcp run ... stdio transport.
• Updated the affected plugins’ Codex manifests to reference ./.mcp.codex.json instead of ./.mcp.json.
• Added Codex troubleshooting and rollback guidance to docs/TROUBLESHOOTING.md.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
plugins/migration-to-aws/.mcp.codex.json	New Codex MCP config using stdio proxy for awsknowledge
plugins/migration-to-aws/.codex-plugin/plugin.json	Points Codex manifest to ./.mcp.codex.json
plugins/deploy-on-aws/.mcp.codex.json	New Codex MCP config using stdio proxy for awsknowledge
plugins/deploy-on-aws/.codex-plugin/plugin.json	Points Codex manifest to ./.mcp.codex.json
plugins/databases-on-aws/.mcp.codex.json	New Codex MCP config using stdio proxy for awsknowledge
plugins/databases-on-aws/.codex-plugin/plugin.json	Points Codex manifest to ./.mcp.codex.json
docs/TROUBLESHOOTING.md	Adds Codex-specific awsknowledge startup failure guidance and debug override steps

[github-actions]

This pull request is now marked as stale because it hasn't seen activity for a while. Add a comment or it will be closed soon. If you wish to exclude this issue from being marked as stale, add the "backlog" label.

[github-actions]

Closing this pull request as it hasn't seen activity for a while. Please add a comment @mentioning a maintainer to reopen. If you wish to exclude this issue from being marked as stale, add the "backlog" label.