Skip to content

codex.md

Latest commit

 

History

History
138 lines (88 loc) · 3.24 KB

codex.md

File metadata and controls

138 lines (88 loc) · 3.24 KB
Raw

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

Install the server once:

brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp
brew install zereight/gitlab-mcp/zereight-mcp-gitlab

Or with npm:

npm install -g @zereight/mcp-gitlab

If Codex cannot find zereight-mcp-gitlab, use the absolute path from which zereight-mcp-gitlab.

Option 1 — Add with codex mcp add

Read the token without echo, then export it. The shell history keeps the variable name.

read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN

--env KEY=VALUE is the Codex flag for a stdio server. The shell expands "$GITLAB_PERSONAL_ACCESS_TOKEN" before Codex stores the value.

codex mcp add gitlab \
  --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" \
  --env GITLAB_API_URL=https://gitlab.com/api/v4 \
  -- zereight-mcp-gitlab

Optional extra environment variables:

--env GITLAB_PERMISSION_MODE=readonly
--env GITLAB_TOOLSETS=core,wiki,milestones,pipelines
--env GITLAB_TOOLS=validate_ci_lint,validate_project_ci_lint

GITLAB_TOOLS keeps the two CI lint tools that deprecated USE_PIPELINE=true exposed; they live in the ci toolset, not pipelines. If you already set GITLAB_TOOLSETS, append wiki, milestones, and pipelines to your existing list instead of replacing it.

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 = "zereight-mcp-gitlab"

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

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 zereight-mcp-gitlab is not available in the environment where Codex launches subprocesses, use the full command path from which zereight-mcp-gitlab or ensure npm's global bin directory is on your PATH.

See also