superpower-codex-mcp

A TypeScript MCP server that coordinates Codex and Antigravity CLI with a Superpowers-style software development workflow.

Codex handles planning, review, debugging, and verification. Antigravity CLI handles coding execution. The server adds workspace authorization, Git-based change verification, acceptance criteria, compact task reports, and persisted diagnostics.

Requirements

• Node.js 20 or newer

• Codex CLI installed and authenticated

• Antigravity CLI (agy) installed and authenticated

• Git

Related MCP server: Spec MCP Server

Install

git clone https://github.com/Pushplayhero/superpower-codex-mcp.git
cd superpower-codex-mcp
npm.cmd install
npm.cmd run build
npm.cmd test

On macOS or Linux, use npm instead of npm.cmd.

Codex Desktop configuration

Add the server to your Codex MCP configuration. Replace the paths with your local clone and the workspaces the server may access.

[mcp_servers.superpower-codex]
command = "node"
args = ["C:\\path\\to\\superpower-codex-mcp\\dist\\src\\index.js"]

[mcp_servers.superpower-codex.env]
SUPERPOWER_CODEX_ALLOWED_ROOTS = "C:\\path\\to\\projects"

Restart Codex Desktop after changing MCP configuration.

Antigravity configuration

In a project that should use this MCP server, add .agents/mcp_config.json:

{
  "mcpServers": {
    "superpower-codex": {
      "command": "node",
      "args": [
        "C:\\path\\to\\superpower-codex-mcp\\dist\\src\\index.js"
      ],
      "env": {
        "SUPERPOWER_CODEX_ALLOWED_ROOTS": "C:\\path\\to\\projects"
      }
    }
  }
}

The default Antigravity executable is:

%LOCALAPPDATA%\agy\bin\agy.exe

Set SUPERPOWER_ANTIGRAVITY_COMMAND when it is installed elsewhere:

$env:SUPERPOWER_ANTIGRAVITY_COMMAND = "C:\custom\path\agy.exe"

Available tools

Recommended workflow

1. Call validate_workspace.

2. Call summarize_repo_context.

3. Use plan_with_codex for broad or risky changes.

4. Execute the approved task with run_antigravity_coding_task.

5. Use review_code_quality as a token-free pre-filter.

6. Call review_with_codex.

7. Send review corrections back to Antigravity when required.

8. Call verify_with_codex before declaring completion.

For an automated version of this sequence, use run_development_workflow.

Coding task example

{
  "workspacePath": "C:\\path\\to\\project",
  "prompt": "Implement the approved task using test-driven development.",
  "allowExecution": true,
  "timeoutSeconds": 1800,
  "model": "Gemini 3.5 Flash (Medium)",
  "mode": "execute",
  "planApproved": true,
  "requireCommit": true,
  "requireCleanWorkspace": true,
  "acceptanceCriteria": [
    {
      "id": "AC-1",
      "description": "The new behavior is covered by a regression test."
    }
  ],
  "allowedFiles": [
    "src/example.ts",
    "tests/example.test.ts"
  ],
  "responseDetail": "summary"
}

Supported model names:

• gemini-3.5-flash

• Gemini 3.5 Flash (Medium)

• Gemini 3.1 Pro (High)

Unsupported legacy Gemini model names are rejected. The server does not automatically retry with a stronger model.

Workspace safety

By default, only the MCP process working directory and its descendants are allowed. Additional roots must be explicitly configured:

$env:SUPERPOWER_CODEX_ALLOWED_ROOTS = "C:\projects;D:\work"

Use ; as the delimiter on Windows and : on macOS or Linux.

Additional safeguards:

• Coding execution requires allowExecution: true.

• Verification commands require allowCommandExecution: true.

• Verification commands run without a shell; pipes, redirects, and command separators are rejected.

• Strict execution compares reported files and commits with Git metadata.

• allowedFiles accepts only repository-relative paths.

• Antigravity does not recursively call the coding-task MCP tool.

Development

npm.cmd install
npm.cmd run typecheck
npm.cmd test
npm.cmd run build

The verified baseline is 126 passing tests across 9 test files.

License

MIT