Skip to content

codex-setup.md

Latest commit

 

History

History
118 lines (76 loc) · 2.32 KB

codex-setup.md

File metadata and controls

118 lines (76 loc) · 2.32 KB

Codex Setup Guide

This guide explains how to use @zereight/mcp-gitlab with Codex.

Codex supports MCP in two main ways:

  1. codex mcp add from the CLI
  2. config.toml in ~/.codex/config.toml or project .codex/config.toml

Prerequisites

  • Codex installed
  • Node.js available in your shell
  • GitLab access via either:
    • Personal Access Token (PAT), or
    • OAuth for compatible remote MCP servers

For this local stdio server, PAT is the simplest path.

Use an API URL, not the web root:

  • https://gitlab.com/api/v4
  • https://your-gitlab.example.com/api/v4

Option 1 — Add with codex mcp add

PAT example:

codex mcp add gitlab \
  --env GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-token \
  --env GITLAB_API_URL=https://gitlab.com/api/v4 \
  -- npx -y @zereight/mcp-gitlab

Optional extra environment variables:

--env GITLAB_READ_ONLY_MODE=true
--env USE_GITLAB_WIKI=true
--env USE_MILESTONE=true
--env USE_PIPELINE=true

Option 2 — Configure with config.toml

Codex stores MCP config in:

  • ~/.codex/config.toml
  • or project-scoped .codex/config.toml

Example:

[mcp_servers.gitlab]
command = "npx"
args = ["-y", "@zereight/mcp-gitlab"]

[mcp_servers.gitlab.env]
GITLAB_PERSONAL_ACCESS_TOKEN = "glpat-your-token"
GITLAB_API_URL = "https://gitlab.com/api/v4"
GITLAB_READ_ONLY_MODE = "false"

Verifying the server

Useful commands:

codex mcp --help

In the Codex TUI, use:

/mcp

to see active MCP servers.

Recommended first prompt

List my GitLab projects and recent merge requests.

Common mistakes

1. Using the web URL instead of the API URL

Wrong:

  • https://gitlab.com

Correct:

  • https://gitlab.com/api/v4

2. Missing PAT scope

Use a token with at least:

  • read_api for read-only workflows
  • api for write workflows

3. Expecting OAuth flags to apply to stdio PAT mode

Codex supports OAuth for remote MCP flows, but for this local stdio GitLab setup, PAT is the most reliable starting point.

4. Shell command not found

If npx is not available in the environment where Codex launches subprocesses, use the full command path or ensure Node.js is on your PATH.

See also