Complete written walkthrough for adding the Gryz MCP server to OpenAI Codex with OAuth, copyable CLI and TOML, troubleshooting, and an optional video demo.

Before you start

You need a free Gryz account and OpenAI Codex (CLI, desktop app, or IDE extension). This guide is complete on its own — follow every step below even if you skip the video.

Watch the full video on YouTube: How to Connect Codex to an MCP Server (Step-by-Step) | Gryz.

Prerequisites

Gryz account (sign up)
Codex CLI or the Codex app (MCP config is shared)
MCP server URL (always use www):

https://www.gryz.ai/api/mcp/

Step 1 — Add the Gryz server

From a terminal:

codex mcp add gryz --url https://www.gryz.ai/api/mcp/

Codex stores MCP servers in ~/.codex/config.toml. The CLI, desktop app, and IDE extension read the same file.

Equivalent TOML if you prefer to edit the file yourself:

[mcp_servers.gryz]
url = "https://www.gryz.ai/api/mcp/"

OAuth avoids storing an API key on disk.

codex mcp login gryz

Codex opens a browser window to Gryz
Sign in with Google, GitHub, magic link, or password
Approve access on the Allow screen
Return to the terminal — the login command should complete

Step 3 — API key alternative

If OAuth is unavailable in your environment, generate a key on the API keys page. Codex reads the token from an environment variable — it does not write the secret into config.toml.

export GRYZ_API_KEY=gryz_YOUR_KEY_HERE
codex mcp add gryz --url https://www.gryz.ai/api/mcp/ --bearer-token-env-var GRYZ_API_KEY

Replace gryz_YOUR_KEY_HERE with your key. Keep GRYZ_API_KEY in your shell profile or secret manager, not in git.

Equivalent TOML:

[mcp_servers.gryz]
url = "https://www.gryz.ai/api/mcp/"
bearer_token_env_var = "GRYZ_API_KEY"

Step 4 — Confirm the connection

codex mcp list
codex mcp get gryz --json

The list should show gryz as enabled. The JSON transport.url must be https://www.gryz.ai/api/mcp/.

Then start a new Codex session (restart if one was already open) and run /mcp to see Gryz tools.

Step 5 — Verify with a prompt

Try these prompts in Codex:

List my Gryz documents
Publish this markdown to Gryz as a private doc titled "Codex MCP test"

A successful publish returns a URL in the assistant reply. Open it to confirm the document rendered.

Example prompts

Publish this spec to Gryz as a public doc titled "Q3 roadmap"
Get my Gryz document with slug "q3-roadmap"
Delete my Gryz test document with slug "codex-mcp-test"

Troubleshooting

Issue	Fix
OAuth login fails / wrong resource	Re-add with `codex mcp add gryz --url https://www.gryz.ai/api/mcp/ --oauth-resource https://www.gryz.ai/api/mcp` (no trailing slash on the resource), then `codex mcp login gryz`
Magic link on another device	Start OAuth on desktop; open the email link on the same machine
401 / connection failed	Confirm `www` and trailing slash on the MCP URL; apex redirects strip auth headers
Tools not appearing	Start a new Codex session after `mcp add` / `mcp login`. Run `/mcp` to confirm the server loaded
Duplicate `gryz` entry	`codex mcp remove gryz`, then add again

Reference

For Claude, ChatGPT, and Cursor setup, plus the tools table and API details, see the MCP setup reference.

Connect Gryz MCP in Codex