skills.rest
diazMelgarejo
diazMelgarejoCOMMUNITY
Explore all skills by this author →
Website𝕏@Melgarejo_yDiazGitHub

codex-mcp-debugging

Diagnose Codex CLI MCP config.toml transport and auth field mismatches.

Updated Mar 22, 2026
Search Tags:#debugging#codex#mcp#config.toml#stdio transport#github mcp#cli configuration
One-click install
npx skills add https://github.com/diazMelgarejo/orama-system --skill codex-mcp-debugging-diazmelgarejo
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: codex-mcp-debugging
Source: https://github.com/diazMelgarejo/orama-system/tree/main/bin/orama-system/skills/codex-mcp-debugging
Command: npx skills add https://github.com/diazMelgarejo/orama-system --skill codex-mcp-debugging-diazmelgarejo

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codex CLI MCP servers fail with cryptic invalid transport errors when config.toml blocks mix stdio and HTTP field families, such as applying bearer_token_env_var to a local stdio subprocess. This Skill guides systematic diagnosis of transport shape and auth field mismatches before any config edits. ## Core Features & Use Cases - Transport Classification: Distinguishes stdio servers (command, args, env) from HTTP servers (url, bearer_token_env_var) so credentials land in the correct field family. - GitHub MCP Pattern: Provides the correct stdio configuration for the local npm GitHub MCP server, plus the remote Streamable HTTP exception where bearer tokens are valid. - Exa Wrapper Setup: Configures Exa as a stdio wrapper on OpenClaw machines with a JSON-RPC smoke test that verifies web_search_exa and web_fetch_exa tools. - Use Case: When codex mcp list reports invalid transport for a GitHub MCP entry, classify the transport, move the token into [mcp_servers.github.env], and re-run the parser to confirm the fix. ## Quick Start Ask the assistant to debug why codex mcp list fails with an invalid transport error on the GitHub MCP server in config.toml.

Frequently Asked Questions about codex-mcp-debugging

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix invalid transport errors in Codex CLI MCP config?▼

Classify the server transport first: stdio servers need command, args, and env fields, while HTTP servers need url and optionally bearer_token_env_var. The invalid transport error usually means fields from one family were applied to the other, not missing credentials.

How do I configure GitHub MCP server in Codex config.toml?▼

For the local npm GitHub MCP server, use stdio transport with command npx, args containing @modelcontextprotocol/server-github, and GITHUB_PERSONAL_ACCESS_TOKEN under [mcp_servers.github.env]. Only the remote api.githubcopilot.com/mcp endpoint uses bearer_token_env_var.

Why does bearer_token_env_var fail on my local MCP server?▼

bearer_token_env_var only applies to remote HTTP MCP servers, not stdio subprocesses. Applying it to a local server like the npm GitHub MCP creates a schema mismatch that triggers invalid transport errors.

How do I verify a Codex MCP server configuration works?▼

Run codex mcp list to confirm the config parses without invalid transport errors, then codex mcp get <name> to inspect the resolved transport, command, and env. For stdio wrappers, pipe JSON-RPC initialize and tools/list messages directly into the wrapper script as a smoke test.

When should I use stdio vs HTTP transport for MCP servers?▼

Use stdio for local subprocess servers launched via command and args, with secrets passed through the env block. Use HTTP transport with url and bearer_token_env_var only for remote endpoints such as the GitHub Copilot MCP API.

Related Skills

Explore More Software Engineering Skills→
thisismynewfmail-uithisismynewfmail-ui

github-auth

Configure GitHub authentication across git and gh using HTTPS tokens or SSH keys.

Community
Intermediate
chanhee-kangchanhee-kang
2

mcp-setup

Configure MCP servers for Gemini CLI via the claude mcp add workflow.

Community
Advanced
AradotsoAradotso
7

mcp-server-bash-sdk

Build Bash MCP servers exposing tool_ functions over stdio JSON-RPC.

Official
Intermediate
tinywasmtinywasm
1

tinywasm-app

Orchestrate a persistent MCP daemon with REST/SSE endpoints for tinywasm projects.

Official
Advanced