Skip to content

Commit 458caf9

Browse files
jamesmontemagnojamesmontemagno
committed
updates based on feedback
1 parent 17a449a commit 458caf9

File tree

1 file changed

+7
-141
lines changed

1 file changed

+7
-141
lines changed

‎docs/installation-guides/install-codex.md‎

Lines changed: 7 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -14,138 +14,31 @@ For security, avoid hardcoding your token. One common approach:
1414

1515
1. Store your token in `.env` file
1616
```
17-
GITHUB_PAT=ghp_your_token_here
17+
GITHUB_PAT_TOKEN=ghp_your_token_here
1818
```
1919

2020
2. Add to .gitignore
2121
```bash
22-
echo -e ".env\n.codex/config.toml" >> .gitignore
22+
echo -e ".env" >> .gitignore
2323
```
24-
2524
</details>
2625

2726
> The remote GitHub MCP server is hosted by GitHub at `https://api.githubcopilot.com/mcp/` and supports Streamable HTTP.
2827
29-
## Quick Remote Configuration (Recommended)
28+
## Remote Configuration
3029

3130
Edit `~/.codex/config.toml` (shared by CLI and IDE extension) and add:
3231

3332
```toml
3433
[mcp_servers.github]
3534
url = "https://api.githubcopilot.com/mcp/"
3635
# Replace with your real PAT (least-privilege scopes). Do NOT commit this.
37-
bearer_token = "ghp_your_token_here"
38-
39-
# Optional server-level timeouts (adjust if tools are long running)
40-
startup_timeout_sec = 30
41-
tool_timeout_sec = 300
42-
```
43-
44-
PAT scopes: start with `repo`; add `workflow`, `read:org`, `project`, `gist` only when needed.
45-
46-
If you prefer not to store the token directly in the file, you can:
47-
1. Use the collapsible "Storing Your PAT Securely" section above for `.env` file approach.
48-
2. Use the Codex IDE extension's config UI to paste it instead of editing the file manually.
49-
3. Regenerate and rotate frequently. (Codex config does not yet support an environment-variable reference for `bearer_token`.)
50-
51-
## Local Docker Configuration (STDIO)
52-
53-
Use this if you prefer a local, self-hosted instance instead of the remote HTTP server.
54-
55-
> The npm package `@modelcontextprotocol/server-github` is deprecated (April 2025). Use the official Docker image `ghcr.io/github/github-mcp-server`.
56-
57-
Add to `config.toml`:
58-
59-
```toml
60-
[mcp_servers.github]
61-
command = "docker"
62-
args = [
63-
"run", "-i", "--rm",
64-
"-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
65-
"ghcr.io/github/github-mcp-server"
66-
]
67-
startup_timeout_sec = 30
68-
tool_timeout_sec = 300
69-
70-
[mcp_servers.github.env]
71-
GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_your_token_here"
72-
```
73-
74-
Or use the Codex CLI to add it (see "Add via Codex CLI" section below).
75-
76-
### Binary (Alternative Local STDIO)
77-
Build the server (or download a release):
78-
79-
```bash
80-
go build -o github-mcp-server ./cmd/github-mcp-server
81-
```
82-
83-
`config.toml` entry:
84-
```toml
85-
[mcp_servers.github]
86-
command = "./github-mcp-server"
87-
args = ["stdio"]
88-
startup_timeout_sec = 30
89-
tool_timeout_sec = 300
90-
91-
[mcp_servers.github.env]
92-
GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_your_token_here"
93-
```
94-
95-
Or use the Codex CLI to add it (see "Add via Codex CLI" section below).
96-
97-
## Add via Codex CLI (STDIO)
98-
99-
The Codex CLI supports adding STDIO MCP servers with `codex mcp add`. This launches the server command when Codex starts. Remote (streamable HTTP) servers like the hosted GitHub MCP (`url = "https://api.githubcopilot.com/mcp/"`) must currently be added by editing `~/.codex/config.toml` directly (the CLI add flow does not set `url`).
100-
101-
### Binary (stdio) via CLI
102-
```bash
103-
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
104-
codex mcp add github -- ./github-mcp-server stdio
105-
```
106-
107-
With an inline env flag (alternative):
108-
```bash
109-
codex mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PERSONAL_ACCESS_TOKEN -- ./github-mcp-server stdio
110-
```
111-
112-
### Docker (stdio) via CLI
113-
```bash
114-
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
115-
codex mcp add github -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
116-
```
117-
118-
Inline env form:
119-
```bash
120-
codex mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PERSONAL_ACCESS_TOKEN -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
121-
```
122-
123-
### Verify (CLI)
124-
After adding:
125-
```bash
126-
codex # start Codex TUI
127-
/mcp # list active servers
128-
```
129-
You should see `github` in the list with tools available. If not:
130-
- Re-run with the PAT exported
131-
- Check that the binary is executable: `chmod +x ./github-mcp-server`
132-
- Confirm Docker can pull the image: `docker pull ghcr.io/github/github-mcp-server`
133-
134-
### Removing / Updating
135-
```bash
136-
codex mcp remove github
137-
codex mcp list
36+
bearer_token_env_var = "GITHUB_PAT_TOKEN"
13837
```
139-
Then re-add with updated scopes or a rotated token.
14038

141-
## Configuration Details
39+
## Local Docker Configuration
14240

143-
- **File path**: `~/.codex/config.toml`
144-
- **Scope**: Global configuration shared by both CLI and IDE extension
145-
- **Format**: Must be valid TOML (use a linter to verify)
146-
- **Editor access**:
147-
- CLI: Edit directly or use `codex mcp add` commands
148-
- IDE: Click gear icon → MCP settings → Open config.toml
41+
Use this if you prefer a local, self-hosted instance instead of the remote HTTP server, please refer to the [OpenAI documentaiton for configuration](https://developers.openai.com/codex/mcp).
14942

15043
## Verification
15144

@@ -155,8 +48,6 @@ After starting Codex (CLI or IDE):
15548
3. If tools are missing:
15649
- Check token validity & scopes.
15750
- Confirm correct table name: `[mcp_servers.github]`.
158-
- For stdio: ensure env var `GITHUB_PERSONAL_ACCESS_TOKEN` is set before launching Codex.
159-
4. For long-running operations, consider increasing `tool_timeout_sec`.
16051

16152
## Usage
16253

@@ -180,7 +71,7 @@ After setup, Codex can interact with GitHub directly. Try these example prompts:
18071
- "Create a gist with this code snippet"
18172
- "List my gists"
18273

183-
> **Tip**: Use `/mcp` in the Codex TUI to see all available GitHub tools and their descriptions.
74+
> **Tip**: Use `/mcp` in the Codex UI to see all available GitHub tools and their descriptions.
18475
18576
## Choosing Scopes for Your PAT
18677

@@ -206,41 +97,16 @@ Use the principle of least privilege: add scopes only when a tool request fails
20697
| Timeouts on large operations | Default too low | Increase `tool_timeout_sec` (e.g. 600) |
20798
| Token in file risks leakage | Committed accidentally | Rotate token; add file to `.gitignore` |
20899

209-
### Debug Tips
210-
- Mask token: `printf '%s\n' "$GITHUB_PERSONAL_ACCESS_TOKEN" | head -c 4`
211-
- Validate TOML: `python -c 'import tomllib; tomllib.load(open("$HOME/.codex/config.toml","rb"))'`
212-
- Inspect tools: use `/mcp` then expand server details.
213-
- Manual Docker test:
214-
```bash
215-
docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
216-
```
217-
218100
## Security Best Practices
219101
1. Never commit tokens into version control
220102
2. Prefer environment variables or secret managers
221103
3. Rotate tokens periodically
222104
4. Restrict scopes up front; expand only when required
223105
5. Remove unused PATs from your GitHub account
224106

225-
## Important Notes
226-
227-
- **npm package deprecation**: The npm package `@modelcontextprotocol/server-github` is deprecated as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` or build from source.
228-
- **Remote server**: GitHub's hosted MCP server at `https://api.githubcopilot.com/mcp/` is the recommended setup for most users (no Docker needed).
229-
- **Token security**: Never commit `config.toml` with embedded tokens to version control. Use `.gitignore` and rotate tokens regularly.
230-
- **CLI help**: Run `codex mcp --help` to see all available MCP management commands.
231-
- **Configuration sharing**: The `~/.codex/config.toml` file is shared between Codex CLI and IDE extension—configure once, use everywhere.
232-
- **Advanced features**: See the [main README](../../README.md) for toolsets, read-only mode, and dynamic tool discovery options.
233-
234107
## References
235108
- Remote server URL: `https://api.githubcopilot.com/mcp/`
236109
- Docker image: `ghcr.io/github/github-mcp-server`
237110
- Release binaries: [GitHub Releases](https://github.com/github/github-mcp-server/releases)
238111
- OpenAI Codex MCP docs: https://developers.openai.com/codex/mcp
239112
- Main project README: [Advanced configuration options](../../README.md)
240-
241-
## Notes on Host Configuration
242-
Codex MCP server tables live under `[mcp_servers.<name>]`. Supported keys relevant here:
243-
- STDIO: `command`, `args`, `env`, `startup_timeout_sec`, `tool_timeout_sec`
244-
- Streamable HTTP: `url`, `bearer_token`, `startup_timeout_sec`, `tool_timeout_sec`
245-
246-
We intentionally omit OAuth configuration because it requires the experimental RMCP client and is not applicable to the GitHub MCP server in this guide.

0 commit comments

Comments
 (0)