Skip to content

Use in Codex

Deprecated: MCP-for-Stata's built-in agent mode is marked with FutureWarning since v1.16.x and will be removed in a future release. New workflows should use MCP server mode (stata-mcp server or stata-mcp install -c <client>) and rely on the host AI client's native agent capabilities instead.

This document explains how to use MCP-for-Stata with Codex, OpenAI's coding agent available as a CLI and as a VS Code extension.

Requirements: - Stata 17+ - uv or Python 3.11+ - Codex CLI or the Codex VS Code extension

Quick Start

First, check whether MCP-for-Stata is compatible with your device:

uvx stata-mcp doctor

Then add the MCP server to Codex. The installer uses the Codex CLI when it is available and falls back to editing ~/.codex/config.toml otherwise.

stata-mcp install -c codex

The resulting TOML configuration looks like this:

[mcp_servers.stata-mcp]
command = "uvx"
args = ["stata-mcp"]
env = { STATA_MCP__CWD = "/path/to/project", STATA_CLI = "/Applications/Stata/StataMP" }

Advice: Please make sure the working directory path does not contain special characters such as whitespace, emoji, or Chinese characters.

After adding the server, restart Codex so the new MCP tool becomes available.

Manual Configuration

If the automatic installer does not work, create or edit ~/.codex/config.toml directly:

[mcp_servers.stata-mcp]
command = "uvx"
args = ["stata-mcp"]
env = { STATA_MCP__CWD = "/absolute/path/to/project" }

Codex-specific notes:

  • The top-level key is mcp_servers (underscore), not mcpServers.
  • The configuration file is ~/.codex/config.toml.
  • Environment variables are written inline in TOML table syntax.

Project Structure

We suggest keeping all projects in the same directory, for example ~/Documents/StataProjects. After setting STATA_MCP__CWD, MCP-for-Stata generates project files under that directory:

my_first_project/            # Project directory
├── .statamcp/               # All files generated by MCP-for-Stata
│   ├── stata-mcp-dofile/    # do-files
│   ├── stata-mcp-log/       # Log files
│   ├── stata-mcp-result/    # Results from commands like `outreg2`
│   └── stata-mcp-tmp/       # Temporary files such as data info descriptions
│   └── .gitignore           # Git ignore file
└── CLAUDE.md                # Project global instructions

Command Variations

Pin a specific version:

[mcp_servers.stata-mcp]
command = "uvx"
args = ["stata-mcp==1.16.2"]

Use a custom project directory:

[mcp_servers.stata-mcp]
command = "uvx"
args = [
  "--directory",
  "/absolute/path/to/project",
  "stata-mcp"
]
env = { STATA_MCP__CWD = "/absolute/path/to/project" }

Troubleshooting

  • Configuration not detected: Verify that ~/.codex/config.toml exists and uses valid TOML syntax, then restart Codex.
  • Wrong working directory: Use an absolute path for STATA_MCP__CWD; relative paths may be resolved relative to Codex's runtime directory.
  • Stata not found: Set STATA_CLI to the absolute path of your Stata executable.