Basic Usage Examples

This guide provides practical examples of using Codex MCP Tool for common development tasks.

Getting Started

Test Connection

First, verify the tool is working:

javascript

// Simple ping test
{
  "name": "ping",
  "arguments": {
    "prompt": "Hello from Codex!"
  }
}

// Check available commands
{
  "name": "help",
  "arguments": {}
}

File Analysis

Analyze a Single File

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "explain what this code does @src/main.ts"
  }
}

Review Multiple Files

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "compare the implementations in @src/old-api.ts and @src/new-api.ts"
  }
}

Analyze Directory Structure

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "describe the architecture of @src/ and how components interact"
  }
}

Code Generation

Generate Unit Tests

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "create comprehensive unit tests for @src/utils/calculator.ts",
    "model": "gpt-5.6-terra",
    "sandboxMode": "workspace-write"
  }
}

Create Documentation

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "generate JSDoc comments for all functions in @src/api/",
    "changeMode": true
  }
}

Implement Features

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "add error handling and retry logic to @src/services/api-client.ts",
    "model": "gpt-5.6-terra",
    "sandboxMode": "workspace-write",
    "approvalPolicy": "on-request"
  }
}

Code Review

Security Audit

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "audit @src/ for OWASP top 10 vulnerabilities and security best practices",
    "model": "gpt-5.6-sol",
    "sandboxMode": "read-only"
  }
}

Performance Review

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "identify performance bottlenecks in @src/api/ and suggest optimizations",
    "sandboxMode": "read-only"
  }
}

Code Quality Check

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "review @src/components/ for React best practices and anti-patterns",
    "model": "gpt-5.6-terra"
  }
}

Refactoring

Modernize Code

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "refactor @src/legacy.js to use modern ES6+ syntax and async/await",
    "changeMode": true,
    "sandboxMode": "workspace-write"
  }
}

Extract Components

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "extract reusable components from @src/pages/dashboard.tsx",
    "changeMode": true,
    "model": "gpt-5.6-sol"
  }
}

Optimize Imports

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "organize and optimize imports in @src/**/*.ts using path aliases",
    "changeMode": true,
    "fullAuto": true
  }
}

Brainstorming

Feature Ideas

javascript

{
  "name": "brainstorm",
  "arguments": {
    "prompt": "innovative features for a code editor",
    "methodology": "divergent",
    "domain": "product",
    "ideaCount": 15
  }
}

Problem Solving

javascript

{
  "name": "brainstorm",
  "arguments": {
    "prompt": "ways to reduce build time from 5 minutes to under 1 minute",
    "methodology": "scamper",
    "constraints": "cannot change build tool, limited to current tech stack",
    "includeAnalysis": true
  }
}

Architecture Decisions

javascript

{
  "name": "brainstorm",
  "arguments": {
    "prompt": "microservices vs monolith for our e-commerce platform",
    "domain": "software",
    "existingContext": "Team of 5, expecting 10x growth, current monolith is 100k LOC",
    "methodology": "convergent"
  }
}

Debugging

Find Bugs

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "find the bug causing null pointer exception in @src/auth/login.ts",
    "model": "gpt-5.6-sol"
  }
}

Trace Execution

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "trace the execution flow when user clicks submit in @src/forms/contact.tsx"
  }
}

Analyze Error

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "explain this error and how to fix it: [paste error message]. Related files: @src/api/handler.ts"
  }
}

Documentation

API Documentation

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "generate OpenAPI/Swagger documentation for @src/api/routes/",
    "sandboxMode": "workspace-write"
  }
}

README Generation

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "create a comprehensive README.md based on @package.json @src/",
    "model": "gpt-5.6-terra"
  }
}

Code Comments

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "add explanatory comments to complex logic in @src/algorithms/",
    "changeMode": true
  }
}

Migration Tasks

Framework Migration

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "migrate @src/components/ from React class components to functional components with hooks",
    "changeMode": true,
    "model": "gpt-5.6-sol",
    "approvalPolicy": "on-request"
  }
}

Library Updates

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "update @src/ to use the new v5 API from library X (breaking changes in @CHANGELOG.md)",
    "changeMode": true,
    "sandboxMode": "workspace-write"
  }
}

TypeScript Migration

javascript

{
  "name": "ask-codex",
  "arguments": {
    "prompt": "convert @src/utils/*.js to TypeScript with proper type definitions",
    "changeMode": true,
    "model": "gpt-5.6-sol"
  }
}

Working with Large Codebases

Chunked Analysis

javascript

// Analyze in parts
{
  "name": "ask-codex",
  "arguments": {
    "prompt": "analyze @src/modules/auth/",
    "model": "gpt-5.6-luna"
  }
}

// Then continue with next module
{
  "name": "ask-codex",
  "arguments": {
    "prompt": "analyze @src/modules/payments/",
    "model": "gpt-5.6-luna"
  }
}

Progressive Refactoring

javascript

// Start with critical paths
{
  "name": "ask-codex",
  "arguments": {
    "prompt": "refactor critical performance paths in @src/core/",
    "changeMode": true,
    "sandboxMode": "workspace-write"
  }
}

Handling Large Responses

javascript

// Initial request
{
  "name": "ask-codex",
  "arguments": {
    "prompt": "refactor all components in @src/components/",
    "changeMode": true
  }
}
// Returns: { cacheKey: "abc123", totalChunks: 5 }

// Get remaining chunks
{
  "name": "fetch-chunk",
  "arguments": {
    "cacheKey": "abc123",
    "chunkIndex": 2
  }
}

Common Patterns

Pre-Analysis Pattern

Always analyze before modifying:

javascript

// Step 1: Understand current state
{
  "name": "ask-codex",
  "arguments": {
    "prompt": "analyze current implementation of @src/auth/",
    "sandboxMode": "read-only"
  }
}

// Step 2: Plan improvements
{
  "name": "brainstorm",
  "arguments": {
    "prompt": "improvements for authentication system",
    "existingContext": "[analysis results]"
  }
}

// Step 3: Implement changes
{
  "name": "ask-codex",
  "arguments": {
    "prompt": "implement the top 3 improvements",
    "changeMode": true,
    "sandboxMode": "workspace-write"
  }
}

Safe Refactoring Pattern

javascript

// Use incremental approach
{
  "name": "ask-codex",
  "arguments": {
    "prompt": "refactor @src/utils/helper.ts - start with pure functions only",
    "changeMode": true,
    "approvalPolicy": "on-request"
  }
}

Review-First Pattern

javascript

// Review for issues
{
  "name": "ask-codex",
  "arguments": {
    "prompt": "review @src/ for bugs, security issues, and performance problems",
    "sandboxMode": "read-only"
  }
}

// Then fix identified issues
{
  "name": "ask-codex",
  "arguments": {
    "prompt": "fix the critical issues identified in the review",
    "changeMode": true,
    "approvalPolicy": "never"
  }
}

Tips for Effective Usage

1. Start Small

Begin with single files or small directories before processing entire codebases.

2. Use Appropriate Models

gpt-6-luna: Quick analysis, simple tasks
gpt-6.1-sol: Standard coding tasks, refactoring, comprehensive generation
gpt-6-astra: Hard, open-ended problems

3. Leverage Change Mode

For any code modifications, use changeMode: true to get structured edits.

4. Set Clear Boundaries

Use sandbox modes to control what the tool can access and modify.

5. Provide Context

Include relevant background information for better results.

Basic Usage Examples ​

Getting Started ​

Test Connection ​

File Analysis ​

Analyze a Single File ​

Review Multiple Files ​

Analyze Directory Structure ​

Code Generation ​

Generate Unit Tests ​

Create Documentation ​

Implement Features ​

Code Review ​

Security Audit ​

Performance Review ​

Code Quality Check ​

Refactoring ​

Modernize Code ​

Extract Components ​

Optimize Imports ​

Brainstorming ​

Feature Ideas ​

Problem Solving ​

Architecture Decisions ​

Debugging ​

Find Bugs ​

Trace Execution ​

Analyze Error ​

Documentation ​

API Documentation ​

README Generation ​

Code Comments ​

Migration Tasks ​

Framework Migration ​

Library Updates ​

TypeScript Migration ​

Working with Large Codebases ​

Chunked Analysis ​

Progressive Refactoring ​

Handling Large Responses ​

Common Patterns ​

Pre-Analysis Pattern ​

Safe Refactoring Pattern ​

Review-First Pattern ​

Tips for Effective Usage ​

1. Start Small ​

2. Use Appropriate Models ​

3. Leverage Change Mode ​

4. Set Clear Boundaries ​

5. Provide Context ​

Next Steps ​

Basic Usage Examples

Getting Started

Test Connection

File Analysis

Analyze a Single File

Review Multiple Files

Analyze Directory Structure

Code Generation

Generate Unit Tests

Create Documentation

Implement Features

Code Review

Security Audit

Performance Review

Code Quality Check

Refactoring

Modernize Code

Extract Components

Optimize Imports

Brainstorming

Feature Ideas

Problem Solving

Architecture Decisions

Debugging

Find Bugs

Trace Execution

Analyze Error

Documentation

API Documentation

README Generation

Code Comments

Migration Tasks

Framework Migration

Library Updates

TypeScript Migration

Working with Large Codebases

Chunked Analysis

Progressive Refactoring

Handling Large Responses

Common Patterns

Pre-Analysis Pattern

Safe Refactoring Pattern

Review-First Pattern

Tips for Effective Usage

1. Start Small

2. Use Appropriate Models

3. Leverage Change Mode

4. Set Clear Boundaries

5. Provide Context

Next Steps