Codex CLI

Step 1: Add your Alchemist API key to the environment

Run this in your terminal (add it to ~/.zshrc or ~/.bashrc to persist):

export ALCHEMIST_API_KEY="alch_YOUR_KEY"


Step 2: Add Alchemist to your Codex MCP config

Add this to ~/.codex/config.toml (create the file if it doesn't exist):

[mcp_servers.alchemist]
url = "https://api.askalchemist.com/mcp/"
bearer_token_env_var = "ALCHEMIST_API_KEY"


Step 3: Add the Alchemist skill

Save this file to ~/.codex/skills/alchemist-research/SKILL.md

---
name: alchemist-research
description: Financial research using the Alchemist database. Searches thousands of pre-processed primary source documents — FOMC minutes, USDA WASDE reports, SEC filings, BLS/BEA data releases — and returns citable insights with verbatim source quotes. Use for any macro, earnings, regulatory, or commodity research question.
context: fork
---

# Alchemist Financial Research

## Primary Tool

Always use `search_insights` first for any financial research question.
Do NOT jump to web search before trying `search_insights`.

## Query Format (Critical)

Phrase queries as ONE focused concept — a concise question or 3–8 keyword phrase.

Good:
- "Did the March 2026 FOMC minutes signal a rate pause?"
- "Fed dot plot rate path 2026"
- "AAPL Q3 2025 revenue guidance"
- "corn ending stocks USDA WASDE"

Bad:
- "Tell me about the Federal Reserve and interest rates" (conversational wrapper)
- "Fed rates inflation corn energy bonds" (multi-theme keyword soup)

## Workflow

1. Call `list_filter_options` if you need to filter by source name
2. Run 1–2 targeted searches, read results, then refine
3. If sparse results: retry with different phrasing or remove filters
4. For deep research: get `doc_id` from search results → call `get_document`
5. Fall back to web search ONLY after `search_insights` returns nothing relevant

## Token Isolation

Never run large searches in the main context. Spawn a subagent:
- Subagent runs the search internally
- Subagent distills results into compact output
- Subagent returns findings to main context

## Citation Format

Always cite source_name and published_date for every insight surfaced:
"Per the Federal Reserve FOMC Minutes (March 2026)..."

## Output Format

Return:
1. Key findings — one insight per line, attributed to source + date
2. Sources — document URL + publication date
3. Notes — gaps, conflicts, or uncertainty


Step 4: Restart Codex

Quit and reopen Codex to apply the new MCP connection.

[mcp_servers.alchemist]
url = "https://api.askalchemist.com/mcp/"
bearer_token_env_var = "ALCHEMIST_API_KEY"

[mcp_servers.alchemist]
url = "https://api.askalchemist.com/mcp/"
bearer_token_env_var = "ALCHEMIST_API_KEY"
default_tools_approval_mode = "auto"

codex mcp list
# → alchemist   https://api.askalchemist.com/mcp/   connected