cxporter-mcp

name	cxporter-mcp
description	Use when Codex needs to list, inspect, or directly call MCP servers through the local cxporter CLI using the user's existing Codex sign-in/auth. Covers registered MCP servers, internal codex_apps connectors/apps, tool schemas, resources, direct tool calls, and guarded MCP HTTP auth inspection/export without implementing OAuth flows or Codex LLM threads.

cxporter MCP

Overview

Use cxporter to operate MCP servers through Codex-owned config and auth. Treat cxporter as a direct MCP client: it loads Codex config/auth, lists servers and tools, shows schemas, and calls tools without creating a Codex LLM thread. It can also run as a stdio MCP server that re-exports those downstream tools with stable namespace-style names.

auth inspect and auth export --reveal are the only token/header inspection exceptions. Use them only when the user explicitly asks to inspect or export MCP HTTP auth material. inspect redacts secrets; export requires --reveal.

Invocation

Prefer the bundled wrapper so the skill works from arbitrary working directories:

skills/cxporter-mcp/scripts/cxporter.sh <cxporter-args>

If the skill is installed elsewhere, use the installed skill's scripts/cxporter.sh. The wrapper resolves cxporter in this order:

1. CXPORTER_BIN
2. cxporter on PATH
3. cargo run --manifest-path "$CXPORTER_DIR/Cargo.toml"

Set CXPORTER_DIR when the repository lives outside the installed skill's source checkout, or run cargo install --path . --force --locked so cxporter is available on PATH.

Core Workflow

1. List available MCP servers or apps before assuming a target exists.
2. Inspect the tool schema before calling a tool unless the exact schema is already known from the current session.
3. Call the tool with a JSON object matching that schema.
4. Treat local preflight errors as argument-shape errors to fix before calling the connector.
5. Interpret connector errors as remote/auth/schema errors, not as proof that cxporter failed to connect.

Commands

List registered MCP servers and synthesized codex_apps:

skills/cxporter-mcp/scripts/cxporter.sh list

List only the internal apps/connectors exposed by codex_apps:

skills/cxporter-mcp/scripts/cxporter.sh apps

Inspect one server's tools:

skills/cxporter-mcp/scripts/cxporter.sh list --server codex_apps

Filter large connector tool lists:

skills/cxporter-mcp/scripts/cxporter.sh list --server codex_apps --connector atlassian --name-contains confluence
skills/cxporter-mcp/scripts/cxporter.sh list --server codex_apps --name-contains updateconfluencepage --format text

Show one tool's input schema:

skills/cxporter-mcp/scripts/cxporter.sh schema codex_apps github_fetch_pr

Call a tool:

skills/cxporter-mcp/scripts/cxporter.sh call codex_apps github_fetch_pr '{"repo_full_name":"openai/codex","pr_number":123}'

Call a tool with arguments from a file, or stdin:

skills/cxporter-mcp/scripts/cxporter.sh call codex_apps github_fetch_pr --args-file args.json
printf '%s\n' '{"repo_full_name":"openai/codex","pr_number":123}' | skills/cxporter-mcp/scripts/cxporter.sh call codex_apps github_fetch_pr --args-file -

Bypass local required-property preflight only when the remote connector must see the raw JSON:

skills/cxporter-mcp/scripts/cxporter.sh call --no-preflight codex_apps github_fetch_pr '{"repo_full_name":"openai/codex","pr_number":123}'

Quote tool names that contain spaces:

skills/cxporter-mcp/scripts/cxporter.sh schema codex_apps 'google drive_search'

Read a resource:

skills/cxporter-mcp/scripts/cxporter.sh resource <server> <uri>

Run multiple tool calls from JSONL:

skills/cxporter-mcp/scripts/cxporter.sh batch --server codex_apps --input calls.jsonl --concurrency 1 --retry 3

Each JSONL input line is:

{"tool":"codex_apps.github.fetch_pr","arguments":{"repo_full_name":"openai/codex","pr_number":123}}

batch writes JSONL results with line, server, tool, success, attempts, and either result or error. It continues after per-line failures and exits non-zero if any line fails.

For write-heavy connector batches, keep --concurrency 1 unless every selected tool advertises parallel call support. Use --force-parallel only when duplicate or overlapping side effects are acceptable.

Inspect MCP HTTP auth metadata without revealing secret values:

skills/cxporter-mcp/scripts/cxporter.sh auth inspect <server> --format json

Export MCP HTTP auth headers only when the user explicitly needs secret values and has accepted that they will be printed to stdout:

skills/cxporter-mcp/scripts/cxporter.sh auth export <server> --format json --reveal
skills/cxporter-mcp/scripts/cxporter.sh auth export <server> --format env --reveal
skills/cxporter-mcp/scripts/cxporter.sh auth export <server> --format curl --reveal

Auth export supports HTTP MCP auth sources such as bearer_token_env_var, http_headers, env_http_headers, and stored MCP OAuth access tokens. It does not support stdio MCP servers or codex_apps runtime auth export. Refresh tokens must never be requested, printed, logged, copied into fixtures, or stored in notes.

Run as an MCP server:

skills/cxporter-mcp/scripts/cxporter.sh serve --server codex_apps

Direct call and schema accept both the raw downstream tool name and the cxporter-exported alias. When serving, cxporter loads downstream tools at startup and exposes them as MCP tools named <server>.<connector>.<tool> for apps, or <server>.<tool> for ordinary registered MCP servers. For example, raw codex_apps tool github_fetch_pr is exported as codex_apps.github.fetch_pr. Use list --server <server> --name-contains <text> to inspect raw and exported names.

Register an installed cxporter binary in another MCP client with stdio transport:

[mcp_servers.cxporter]
command = "cxporter"
args = ["serve", "--server", "codex_apps"]

Claude Code registration:

claude mcp add --transport stdio cxporter -- cxporter serve --server codex_apps
claude mcp get cxporter

Error Handling

• INVALID_ARGUMENT: the JSON arguments do not match the connector schema. Run schema <server> <tool> and retry with the required property names.
• missing required properties: cxporter rejected the arguments before calling the connector. Use the listed known properties or run schema.
• notLoggedIn: the user is not signed in through Codex for that MCP path. Ask them to sign in with Codex; do not implement auth or ask for tokens.
• NOT_FOUND, permission, or workspace policy messages: the connector was reached, but the remote service or workspace policy rejected the request.
• unknown MCP server: list servers and verify the server is registered or that codex_apps is enabled for the current Codex auth/config.
• Batch output with success:false: inspect the line, tool, and error fields. Other lines may still have succeeded.

Guardrails

• Do not read, print, transform, or store Codex tokens except through the explicit auth inspect / auth export --reveal commands above.
• Prefer auth inspect; use auth export --reveal only when the user explicitly needs actual header values. Never run it speculatively.
• Do not print refresh tokens. cxporter auth export is allowed to reveal only access-token/header values needed for HTTP requests.
• Do not implement OAuth login, OAuth refresh, bearer-token plumbing, or custom connector auth outside cxporter's existing guarded commands.
• Confirm before using mutating tools such as send, create, update, delete, merge, transition, archive, or label operations.
• Prefer schema over guessing argument names. Connector schemas can differ from public API names; for example github_fetch_pr expects repo_full_name and pr_number.
• Use --retry only for operations that are safe to repeat or where duplicate side effects are acceptable. The default is no retry.