0
# MCP Management
1
2
Model Context Protocol (MCP) server management allows you to add, remove, and configure external tools and capabilities for Codex CLI.
3
4
## Usage
5
6
```bash { .api }
7
codex mcp [OPTIONS] [SUBCOMMAND]
8
```
9
10
## Subcommands
11
12
### Serve
13
14
Run Codex as an MCP server for integration with other tools.
15
16
```bash { .api }
17
codex mcp serve
18
```
19
20
### List Servers
21
22
List all configured MCP servers.
23
24
```bash { .api }
25
codex mcp list [OPTIONS]
26
```
27
28
#### Options
29
30
```bash { .api }
31
--json # Output server list as JSON
32
```
33
34
### Get Server Details
35
36
Show details for a specific MCP server.
37
38
```bash { .api }
39
codex mcp get [OPTIONS] <NAME>
40
```
41
42
#### Arguments
43
44
```bash { .api }
45
<NAME> # Name of the MCP server to display
46
```
47
48
#### Options
49
50
```bash { .api }
51
--json # Output server configuration as JSON
52
```
53
54
### Add Server
55
56
Add a new MCP server configuration.
57
58
```bash { .api }
59
codex mcp add [OPTIONS] <NAME> -- <COMMAND>...
60
```
61
62
#### Arguments
63
64
```bash { .api }
65
<NAME> # Name for the MCP server configuration
66
<COMMAND>... # Command to launch the MCP server
67
```
68
69
#### Options
70
71
```bash { .api }
72
--env <KEY=VALUE> # Environment variables to set when launching (can be used multiple times)
73
```
74
75
### Remove Server
76
77
Remove an MCP server configuration.
78
79
```bash { .api }
80
codex mcp remove <NAME>
81
```
82
83
#### Arguments
84
85
```bash { .api }
86
<NAME> # Name of the MCP server configuration to remove
87
```
88
89
## Examples
90
91
### Serving as MCP Server
92
93
```bash
94
# Run Codex as an MCP server
95
codex mcp serve
96
```
97
98
### Managing Server Configurations
99
100
```bash
101
# List all configured servers (table format)
102
codex mcp list
103
104
# List all configured servers (JSON format)
105
codex mcp list --json
106
107
# Add a simple server
108
codex mcp add docs-server -- python -m http.server 8000
109
110
# Add a server with environment variables
111
codex mcp add database-tool \
112
--env DATABASE_URL=postgresql://localhost/mydb \
113
--env API_KEY=secret123 \
114
-- db-mcp-server --port 3000
115
116
# Add a complex server with multiple args
117
codex mcp add file-processor \
118
--env WORKDIR=/tmp/processing \
119
--env MAX_WORKERS=4 \
120
-- python /path/to/processor.py --mode server --timeout 30
121
122
# Get server details (human-readable)
123
codex mcp get docs-server
124
125
# Get server details (JSON)
126
codex mcp get docs-server --json
127
128
# Remove a server
129
codex mcp remove docs-server
130
```
131
132
### Working with Server Lists
133
134
The list command shows configured servers in table format:
135
136
```
137
Name Command Args Env
138
docs-server python -m http.server 8000 -
139
database-tool db-mcp-server --port 3000 DATABASE_URL=postgresql://localhost/mydb, API_KEY=secret123
140
```
141
142
### JSON Output Format
143
144
When using `--json` flag, output follows this structure:
145
146
```json
147
[
148
{
149
"name": "docs-server",
150
"command": "python",
151
"args": ["-m", "http.server", "8000"],
152
"env": null,
153
"startup_timeout_ms": null
154
},
155
{
156
"name": "database-tool",
157
"command": "db-mcp-server",
158
"args": ["--port", "3000"],
159
"env": {
160
"API_KEY": "secret123",
161
"DATABASE_URL": "postgresql://localhost/mydb"
162
},
163
"startup_timeout_ms": null
164
}
165
]
166
```
167
168
## Configuration Storage
169
170
MCP server configurations are stored in `~/.codex/config.toml` under the `[mcp_servers]` section:
171
172
```toml
173
[mcp_servers.docs-server]
174
command = "python"
175
args = ["-m", "http.server", "8000"]
176
177
[mcp_servers.database-tool]
178
command = "db-mcp-server"
179
args = ["--port", "3000"]
180
[mcp_servers.database-tool.env]
181
DATABASE_URL = "postgresql://localhost/mydb"
182
API_KEY = "secret123"
183
```
184
185
## Server Name Validation
186
187
Server names must:
188
- Not be empty
189
- Contain only ASCII alphanumeric characters, hyphens (-), and underscores (_)
190
- Valid examples: `my-server`, `tool_v2`, `server123`
191
- Invalid examples: `my server`, `tool@home`, `über-tool`
192
193
## Environment Variable Format
194
195
Environment variables must be specified in `KEY=VALUE` format:
196
197
```bash
198
# Valid formats
199
--env DATABASE_URL=postgresql://localhost/mydb
200
--env PORT=3000
201
--env ENABLE_DEBUG=true
202
203
# Multiple environment variables
204
codex mcp add myserver \
205
--env VAR1=value1 \
206
--env VAR2=value2 \
207
-- command args
208
```
209
210
## Error Handling
211
212
Common error scenarios:
213
214
- **Invalid server name**: Contains invalid characters
215
- **Server not found**: No server with specified name exists
216
- **Invalid environment format**: Environment variables not in KEY=VALUE format
217
- **Command required**: Add command requires at least one command argument
218
219
## Integration with Codex
220
221
Once configured, MCP servers are automatically available in Codex sessions:
222
223
1. Servers start automatically when referenced
224
2. Tools and resources become available in conversations
225
3. Servers shut down when session ends
226
227
## Best Practices
228
229
1. **Use descriptive names**: Choose clear, descriptive names for your servers
230
2. **Set appropriate timeouts**: Configure startup timeouts for slow-starting servers
231
3. **Secure environment variables**: Use environment variables for sensitive configuration
232
4. **Test server configurations**: Verify servers start correctly after adding
233
5. **Regular cleanup**: Remove unused server configurations to keep setup clean