Browse documentation
Integrations
Give Codex Google Search and YouTube tools for coding and research.
On this page
Before you start
Have the Codex CLI installed and working. This hosted MCP setup uses OAuth for Google Search, YouTube Search, Metadata and Transcripts. You can create a FlashData account during sign-in.
1. Add the MCP server
Merge this entry into ~/.codex/config.toml (or config.toml under CODEX_HOME). Keep the registered client ID and callback URL as shown.
[mcp_servers.flashdata]
url = "https://data.flashdata.dev/mcp"
[mcp_servers.flashdata.oauth]
client_id = "flashdata-codex"
callback_url = "http://127.0.0.1/callback"2. Sign in
Run the login command. In the browser, sign in or create and verify an account, then approve access. Wait for the terminal to confirm login. Queries use that account's credits.
codex mcp login flashdata --scopes mcp:researchCheck the connection for free
Start a new Codex session and check /mcp for flashdata. Send this prompt; both calls should succeed. A zero balance still confirms a working connection.
Use the flashdata MCP connection.
Call get_balance with {} and get_pricing with {"source":"google_search","request_count":1}.
Report available credits and the estimated price. Do not run a search.3. Run your first task
Send this to your connected agent. The checks are free; the single search uses credits.
Use the flashdata MCP server. Check my balance and the price of one Google search.
If funded, call google_search once with query "site:docs.python.org/3/library/venv.html create virtual environment", num 5 and mode "realtime".
Explain how to create a Python virtual environment using the returned sources.
Cite sources and report actual credits used. Stop after this task.What you should see
Look for a completed google_search tool call with status: done, source links from results[].organic and an answer based on those sources. Usage comes from usage.credits; it is not the number of results. Empty results should be reported as empty.
What you can ask for
This OAuth connection covers research tools. YouTube Download uses an owner API key and destination storage through the API or CLI.
| Task | MCP tool |
|---|---|
| Find web sources for an answer or implementation | google_search |
| Find relevant YouTube videos | youtube_search |
| Read video titles, channels and metadata | youtube_metadata |
| Retrieve a video's transcript for a summary | youtube_transcript |
| Check available credits and request cost | get_balance · get_pricing |
Reuse access for recurring tasks
Use the same Codex profile, OS user and credential store. Create the schedule in your agent host or existing scheduler; FlashData supplies the data tools.
Verify saved access
Run this free check in a fresh session in the scheduled environment. Both calls should succeed without a new browser login.
Reuse the existing flashdata MCP connection.
Call get_balance with {} and get_pricing with {"source":"google_search","request_count":1}.
Report whether both succeeded. Do not search or create new access.Create the recurring task
In your host's scheduler, choose a time and time zone, for example daily at 09:00 Asia/Shanghai. Use this as the task body. Run it once there and check the saved report before enabling recurrence.
Reuse the existing flashdata MCP connection. Check get_balance and get_pricing for one Google search.
If permitted and funded, run google_search once for "site:docs.python.org/3/library/venv.html create virtual environment" with num 5 and mode "realtime".
Save a dated report with source URLs, excerpts and actual credits used.
Stop on revoked access or insufficient credits; respect Retry-After. Do not create a trial, request new authorization or repeat a request whose outcome is unknown.Credential storage and refresh
Codex keeps OAuth tokens in its configured credential store. A different OS user, profile or execution environment may need its own approved connection.
The host refreshes one-hour OAuth access tokens using rotating refresh tokens. Reconnect when the 90-day grant expires or is revoked. Each installation owns its token store; do not share refresh-token files between hosts.
Revoke or reconnect
- Pause scheduled tasks, then revoke the named OAuth connection in FlashData Settings → Connected apps.
- Ask the agent to call get_balance once with the saved connection. It should fail authentication or ask to reconnect. Do not approve a new login during this check.
- Remove the local OAuth credentials with the command below. To reconnect later, repeat step 2 with owner approval and run the free connection check.
codex mcp logout flashdataMore setup options
Add workflow skills to your MCP connection, or choose CLI access or a local MCP server.
Add the MCP skill
The flashdata-mcp skill teaches your agent how to use the connected tools. It reuses the connection above.
Run from your project. Choose the native FlashData CLI v1.2.1, or the skills installer with Node.js 22.20+ and npm. Start a new Codex session and ask to use flashdata-mcp.
flashdata skills install --agent codex --skill flashdata-mcp
flashdata skills verify --agent codex --skill flashdata-mcpnpx skills add flashdatadev/flashdata-skills --skill flashdata-mcp --agent codex --copyUse CLI skills or start a trial
Install FlashData CLI v1.2.1 and run from your project. Choose one access tab. Examples use the default CLI profile, separate from MCP OAuth; keep your existing --profile and --state-dir if you use custom ones.
Setup installs CLI skills into .agents/skills. Start a new Codex session after installation and ask to use google-search.
Paste a key with google_search permission at the hidden prompt. For unattended import, pipe it from your secret manager to auth login --api-key-stdin --non-interactive.
flashdata auth login
flashdata setup --agent codex --skip-auth --non-interactive
flashdata auth status --json --non-interactiveflashdata account balance --json --non-interactive
flashdata search "site:docs.python.org/3/library/venv.html create virtual environment" --num 5 --dry-run --json --non-interactive
# Continue only if accessVerified and estimateAvailable are true,
# google_search is permitted, and availableCredits covers estimatedCredits.flashdata search "site:docs.python.org/3/library/venv.html create virtual environment" --num 5 --run-id codex-first-search-001 --output codex-first-search.json --json --non-interactive
# Read the saved file: status, results[].organic, usage.credits.
# Terminal JSON reports the output path; keep the run ID for recovery.Reuse your existing key or trial. If FLASHDATA_API_KEY is set, it takes precedence over the saved key; verify the account shown by auth status.
flashdata setup --agent codex --skip-auth --non-interactive
flashdata auth status --json --non-interactiveflashdata account balance --json --non-interactive
flashdata search "site:docs.python.org/3/library/venv.html create virtual environment" --num 5 --dry-run --json --non-interactive
# Continue only if accessVerified and estimateAvailable are true,
# google_search is permitted, and availableCredits covers estimatedCredits.flashdata search "site:docs.python.org/3/library/venv.html create virtual environment" --num 5 --run-id codex-first-search-001 --output codex-first-search.json --json --non-interactive
# Read the saved file: status, results[].organic, usage.credits.
# Terminal JSON reports the output path; keep the run ID for recovery.Reuse an existing trial or register once. If expired, exhausted or revoked, recover or claim it. Before recurring CLI tasks, claim the account and confirm recurringAllowed: true in auth status.
flashdata setup --agent codex --non-interactive
flashdata auth status --json --non-interactiveflashdata account balance --json --non-interactive
flashdata search "site:docs.python.org/3/library/venv.html create virtual environment" --num 5 --dry-run --json --non-interactive
# Continue only if accessVerified and estimateAvailable are true,
# google_search is permitted, and availableCredits covers estimatedCredits.flashdata search "site:docs.python.org/3/library/venv.html create virtual environment" --num 5 --run-id codex-first-search-001 --output codex-first-search.json --json --non-interactive
# Read the saved file: status, results[].organic, usage.credits.
# Terminal JSON reports the output path; keep the run ID for recovery.Run local MCP with an API key
Requires Node.js 22.18+, npm and an API key with google_search permission for the first task. This runs @flashdata-dev/mcp 0.2.0; it does not read the FlashData CLI's saved key or MCP OAuth tokens.
Set the key in a terminal, replace the entire earlier flashdata entry (including its OAuth subsection) with the config below, then start Codex from that terminal. An agent can use an existing injected environment variable instead of the hidden prompt.
After setup, run the free connection-check prompt above in a new agent session. Once both checks pass, use the first-task prompt. API-key access does not require mcp login.
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY[mcp_servers.flashdata]
command = "npx"
args = ["--yes", "--package=@flashdata-dev/[email protected]", "flashdata-mcp"]
env_vars = ["FLASHDATA_API_KEY"]codex# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey[mcp_servers.flashdata]
command = "npx.cmd"
args = ["--yes", "--package=@flashdata-dev/[email protected]", "flashdata-mcp"]
env_vars = ["FLASHDATA_API_KEY"]codexTroubleshooting
| Problem | Try this |
|---|---|
| No FlashData tools | Run codex mcp list, then /mcp in a fresh session. Check the config file and finish login. |
| Skill missing | Check .agents/skills in this project. For a native MCP-skill install, run flashdata skills verify --agent codex --skill flashdata-mcp. Restart the session. |
| invalid_client / callback | Compare step 1 exactly. Complete authorization in a browser that can reach the initiating host's callback. |
| 401 | Check whether the connection or key was revoked or expired. For OAuth, repeat sign-in with owner approval; for CLI, run flashdata auth status. Adding credits will not repair authentication. |
| 403 | Check the requested source permission. Research OAuth does not include YouTube Download; use its API-key setup. Fix the permission before retrying. |
| 402 | Check get_balance or flashdata account balance. Add credits in Billing or stop the task; signing in again does not add credits. |
| 429 | Wait for Retry-After and reduce concurrency. Preserve the current profile and registration proof; do not create replacement trials. |
| Local MCP cannot read the key | Set FLASHDATA_API_KEY where the host process starts and restart it. A key saved by flashdata auth login is not automatically exported to local MCP. |
| CLI output file already exists | Read ./codex-first-search.json. To export the saved success again, use flashdata runs show codex-first-search-001 --result --output codex-first-search-copy.json with the original profile. Use a new run ID only for an intended new search. |
| Scheduled task fails | Run the free reuse check inside that environment. Match the OS user, host profile, credential store and tool permissions. |
| Timeout or unknown outcome | Keep the request or job ID and check History before resubmitting. Use get_result for returned continuation IDs. |
OAuth validation notes
OAuth login, callback, saved credentials, a free pricing call, refresh and revocation were verified on Windows with Codex 0.163.0-alpha.10.2 on 2026-10-21. That run did not validate paid queries or scheduled execution. Setup instructions were checked against the host documentation on 2026-11-05.