How to Add a YouTube MCP Server to Codex

OpenAI's Codex CLI lives in your terminal and edits code well, but it has no concept of YouTube. No search, no transcripts, no channel data. You add capabilities to Codex by registering MCP servers in ~/.codex/config.toml, and the Stophy server drops in as one block. After that, Codex can search videos, fetch transcripts, read comments, and walk channels and playlists, all from structured JSON.

Prerequisites

• Codex CLI installed and authenticated
• A Stophy API key (see below)
• Node.js, only for the local stdio option

Get an API key

Sign up at stophy.dev/dashboard. Keys start with st_ and are active immediately. Copy one for the config below.

Each data tool costs one credit, stophy_get_credits is free, and credits don't expire. No Google quota forms, no scraper to babysit.

Add the server to ~/.codex/config.toml

Codex reads MCP servers from its TOML config (config reference). Open or create ~/.codex/config.toml and add one of the blocks below. Replace st_YOUR_API_KEY either way.

Local stdio server

Codex spawns the npm package as a subprocess and hands it your key through env.

1[mcp_servers.stophy]
2command = "npx"
3args = ["-y", "@stophy/mcp"]
4env = { STOPHY_API_KEY = "st_YOUR_API_KEY" }

Hosted HTTP

No local process or Node, since Codex connects to api.stophy.dev over HTTPS.

1[mcp_servers.stophy]
2type = "http"
3url = "https://api.stophy.dev/v1/mcp"
4headers = { Authorization = "Bearer st_YOUR_API_KEY" }

Note the inline-table syntax ({ ... }) for env and headers. TOML is strict about this, and a malformed table is the most common reason the server silently fails to load.

Confirm it loaded

Codex reads MCP servers at startup, so an open session won't see the change. Start a fresh session and ask Codex to list its tools, or just run a YouTube query. If the stophy_* tools answer, you're connected.

Run your first query

In a new session, try a search.

Codex calls stophy_search_videos and gets back an array at data.items[], each entry carrying videoUrl, viewCount, durationText, and publishedAt.

1{
2  "success": true,
3  "creditsRemaining": 994,
4  "data": {
5    "query": { "q": "python data engineering", "type": "video", "sortBy": "relevance" },
6    "items": [
7      {
8        "type": "video",
9        "videoUrl": "https://www.youtube.com/watch?v=kGT4PcTEPP8",
10        "title": "Data Engineering with Python (Full Course)",
11        "author": "freeCodeCamp.org",
12        "viewCount": 451000,
13        "viewCountText": "451K views",
14        "durationText": "1:23:45",
15        "publishedAt": "2025-01-15T00:00:00Z"
16      }
17    ]
18  }
19}

Then pull a transcript by URL.

That's stophy_get_video with type="transcript", which returns timestamped segments Codex can read straight through. Values above are illustrative, and real results depend on the query.

The tools you just added

What that unlocks

• Research agents. Search a topic, pull transcripts from the top results, and have Codex synthesize them into a brief.
• Content audits. Pull a channel's uploads with view counts to see what performs.
• Comment analysis. Fetch threaded comments and surface recurring themes or sentiment.
• Playlist extraction. Dump every video in a playlist into structured data for downstream processing.

Troubleshooting

Server not connecting? Confirm the file is ~/.codex/config.toml and the TOML parses. The usual culprit is env or headers written as a block table instead of an inline { ... } table.

Tools not appearing? Codex loads MCP servers at session start. Restart it, because an already-running session won't pick up a newly added server.

HTTP transport rejected? Check the header value is exactly Bearer st_..., with one space and no extra quotes.

FAQ

Does this use the official YouTube Data API? No. Stophy reads YouTube without Google quota or approval forms, so there's nothing to apply for and no daily cap to hit.

What does each call cost? One credit per data tool. stophy_get_credits is free and credits don't expire. New accounts start with a free balance.

Where does Codex read the config? From ~/.codex/config.toml. Add the [mcp_servers.stophy] block, restart Codex, and the tools load at startup.

Hosted or local transport? Both work. The hosted HTTP block needs no Node, while the local stdio block runs @stophy/mcp as a subprocess.

Related guides

• Add the YouTube MCP server to Claude Code
• Add the YouTube MCP server to Cursor
• Add the YouTube MCP server to Hermes Agent
• The Stophy CLI and MCP server, side by side

Get your API key at stophy.dev/dashboard →

Full reference for every client and tool lives at docs.stophy.dev/mcp.

Related posts