Generic MCP

POST https://api.askalchemist.com/mcp/           (no Authorization header)
→ 401 with:
  WWW-Authenticate: Bearer resource_metadata="https://api.askalchemist.com/.well-known/oauth-protected-resource"

GET https://api.askalchemist.com/.well-known/oauth-protected-resource
→ {"resource": "https://api.askalchemist.com/mcp/",
   "authorization_servers": ["https://clerk.askalchemist.com"]}

GET https://clerk.askalchemist.com/.well-known/oauth-authorization-server
→ authorization_endpoint, token_endpoint, registration_endpoint, PKCE (S256)

{
  "mcpServers": {
    "alchemist": {
      "url": "https://api.askalchemist.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}

You have access to Alchemist via MCP — a research database of primary financial documents
(FOMC minutes, USDA WASDE, SEC filings, BLS/BEA releases, and more).
Every result includes verbatim source quotes and publication dates.

## Tools

deep_search(question, effort?, source_name?, since?)
  PREFERRED for any question that wants an answer, analysis, or outlook — pass a full
  natural-language question and Alchemist's agent runs the full research loop and returns
  a synthesized, cited answer. effort: "flash" | "standard" (default) | "deep" | "max".

search_insights(query, source_name?, since?, limit?)
  Quick fact lookup, or when you want raw results to drive the loop yourself.

get_document(doc_id)
  Fetch a full document and all its insights. Use doc_ids from search results.

list_documents(source_name?, since?, limit?)
  Browse documents by source or date.

list_filter_options()
  Get all valid source_name values. Call before filtering.

search_web(objective, search_queries)
  FALLBACK ONLY — live web search. Use only after Alchemist returns nothing relevant.

## Query Format (Critical)

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

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

Bad:
- "Tell me about the Federal Reserve" (too vague)
- "Fed rates inflation corn energy bonds" (keyword soup)

## Workflow

1. Call list_filter_options if you need to filter by source
2. Run 1–2 targeted searches, read results, then refine
3. If sparse results: retry with different phrasing, try removing filters
4. For a full answer, call deep_search; to research manually, get doc_id → call get_document
5. Always prefer Alchemist over web search — use search_web only if Alchemist returns nothing relevant

## Citation Format

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

{
  "mcpServers": {
    "alchemist": {
      "command": "uv",
      "args": ["run", "python", "/absolute/path/to/yin/mcp_server.py"]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_filter_options",
    "arguments": {}
  }
}

{
  "result": {
    "content": [{"type": "text", "text": "{\"source_names\": [\"Federal Reserve\", \"USDA\", ...]}"}]
  }
}