MCP Tools

The Alchemist MCP server exposes six tools. All are read-only. Endpoint: https://api.askalchemist.com/mcp/
Auth: OAuth 2.0, or Authorization: Bearer alch_YOUR_KEY — see Add to Agents
Transport: Streamable HTTP (MCP 2025)

`search_insights`

The primary research tool. Use this first for any financial question. Why search_insights first? Insights are embedded with HyDE — each insight stores both its text and a set of hypothetical questions it can answer. This makes keyword-adjacent queries work surprisingly well. It’s faster and cheaper than a web search, and every result carries a verbatim source quote.

Parameters

Name	Type	Required	Description
`query`	`string`	Yes	Research query. One focused concept: a concise question or 3–8 keyword phrase.
`source_name`	`string`	No	Partial match filter on the publishing organization (e.g. `"Federal Reserve"`, `"USDA"`, `"BLS"`). Use `list_filter_options` to see all valid values.
`since`	`date`	No	Only return insights from documents published on or after this date (`YYYY-MM-DD`).
`limit`	`integer`	No	Max results. Default `20`.

Query format

Pattern	Example
Concise question	`"Did the March 2026 FOMC minutes signal a pause?"`
Keyword phrase	`"Fed dot plot 2026 rate path"`
Entity + metric	`"AAPL 2025 revenue guidance"`
Theme + source	`"corn ending stocks USDA"`

Avoid: conversational wrappers ("tell me about..."), question padding ("Can you explain..."), multi-theme lists ("Fed rates inflation energy corn").

Response

{
  "insights": [
    {
      "insight_id": "ins_01jwx...",
      "title": "Fed median dot unchanged at 3.875% for end-2026",
      "insight": "The March 2026 SEP showed the median federal funds rate projection for year-end 2026 held at 3.875%, unchanged from December 2025.",
      "excerpts": [
        "The median projection for the federal funds rate at the end of 2026 remained at 3.875 percent."
      ],
      "doc_id": "doc_01jww...",
      "doc_title": "FOMC SEP — March 2026",
      "source_url": "https://federalreserve.gov/monetarypolicy/files/...",
      "source_name": "Federal Reserve",
      "published_date": "2026-03-20",
      "score": 0.92
    }
  ]
}

`get_document`

Retrieve a full document and all its extracted insights by doc_id. Use this for deep research after search_insights has surfaced a relevant document — it gives you the complete set of insights extracted from that document, not just the ones that matched your query.

Parameters

Name	Type	Required	Description
`doc_id`	`string`	Yes	Document ID from `search_insights` or `list_documents` results.

Response

{
  "document": {
    "doc_id": "doc_01jww...",
    "document_url": "https://federalreserve.gov/...",
    "article_title": "FOMC Minutes — March 18–19, 2026",
    "summary": "The March 2026 FOMC minutes detail committee deliberations on the pace of rate adjustments...",
    "source_name": "Federal Reserve",
    "authors": [],
    "published_date": "2026-04-09",
    "extracted_at": "2026-04-09T14:23:00Z",
    "extraction_status": "complete"
  },
  "insights": [
    {
      "insight_id": "ins_01jwx...",
      "title": "...",
      "insight": "...",
      "excerpts": ["..."]
    }
  ]
}

`list_documents`

Browse available documents with optional filters.

Parameters

Name	Type	Required	Description
`source_name`	`string`	No	Partial match on publishing organization name.
`since`	`date`	No	Only documents published on or after this date (`YYYY-MM-DD`).
`limit`	`integer`	No	Max results. Default `50`.

Response

{
  "documents": [
    {
      "doc_id": "doc_01jww...",
      "document_url": "https://...",
      "article_title": "FOMC Minutes — March 18–19, 2026",
      "summary": "...",
      "source_name": "Federal Reserve",
      "published_date": "2026-04-09",
      "extraction_status": "complete"
    }
  ]
}

`list_filter_options`

Return all valid source_name values currently in the database. Call this before passing a source_name filter to search_insights or list_documents — source names must match exactly (case-insensitive partial match).

Parameters

None.

Response

{
  "source_names": [
    "Federal Reserve",
    "USDA",
    "Bureau of Labor Statistics",
    "Bureau of Economic Analysis",
    "U.S. Energy Information Administration",
    "SEC EDGAR"
  ]
}

`deep_search`

Agentic deep research in one call. Pass a full natural-language question and Alchemist’s own agent runs the multi-step loop for you — semantic search, entity-graph traversal, and full-document reads — then returns a synthesized, cited answer. Use deep_search when you want a researched answer. Use search_insights when you want to drive the loop yourself or just need a quick lookup.

Substantially slower and more expensive than search_insights — it runs many model rounds and multiple tool calls per request. Don’t put it on a latency-sensitive path, and don’t call it for lookups a single search_insights would answer.

Parameters

Name	Type	Required	Description
`question`	`string`	Yes	A complete natural-language research question. Do not compress it into keywords — this is the opposite of `search_insights`’s query format.
`effort`	`string`	No	Exploration budget. One of `flash`, `standard`, `deep`, `max`. Default `standard`. Unrecognized values fall back to `standard`.
`source_name`	`string`	No	Partial match to restrict publishing organizations.
`since`	`date`	No	Only use material published on or after this date (`YYYY-MM-DD`).

Effort tiers

Each tier up costs proportionally more, in both rounds and tool calls.

Tier	Max rounds	Max tool calls	Use for
`flash`	3	3	Fastest; minimal graph exploration
`standard`	10	8	Default — most questions
`deep`	16	12	Multi-entity questions needing real traversal
`max`	24	20	Genuine multi-hop graph walks across several entities

Example

{
  "question": "How exposed is TSMC to a Taiwan strait disruption, and which suppliers are single points of failure?",
  "effort": "max"
}

Response

{
  "answer": "TSMC's exposure concentrates in two places...",
  "citations": [
    {
      "doc_id": "doc_01jww...",
      "doc_title": "TSMC 2025 Annual Report",
      "source_url": "https://...",
      "source_name": "TSMC",
      "published_date": "2026-02-11",
      "insights": [
        {
          "insight_id": "ins_01jwx...",
          "insight": "...",
          "excerpts": ["..."],
          "score": 0.88
        }
      ]
    }
  ],
  "run_id": "..."
}

run_id identifies the persisted run, including its full tool trajectory. If the loop fails before producing an answer, the response carries an additional error field with answer set to "" and citations empty.

`search_web`

Live web search via Parallel.ai. Fallback only — use after search_insights returns zero or only tangentially-relevant results. search_insights is always preferred: faster, no per-call variable cost, and every result has citation provenance.

Parameters

Name	Type	Required	Description
`objective`	`string`	Yes	Self-contained sentence describing the research goal. Must name the key entity or topic.
`search_queries`	`string[]`	Yes	2–3 diverse keyword queries (3–6 words each). Vary entities, synonyms, and angles. Never use full sentences or `site:` operators.

Example

{
  "objective": "Find the latest consensus estimate for US core CPI in June 2026.",
  "search_queries": [
    "US core CPI June 2026 estimate",
    "CPI consensus forecast June 2026",
    "inflation expectations June 2026 Bloomberg"
  ]
}

Response

{
  "search_id": "ws_01abc...",
  "results": [
    {
      "url": "https://...",
      "title": "...",
      "publish_date": "2026-06-10",
      "excerpts": ["..."]
    }
  ]
}

Get Started

Add to Agents

MCP Reference

API Reference

`search_insights`

Parameters

Query format

Response

`get_document`

Parameters

Response

`list_documents`

Parameters

Response

`list_filter_options`

Parameters

Response

`deep_search`

Parameters

Effort tiers

Example

Response

`search_web`

Parameters

Example

Response

​search_insights

​Parameters

​Query format

​Response

​get_document

​Parameters

​Response

​list_documents

​Parameters

​Response

​list_filter_options

​Parameters

​Response

​deep_search

​Parameters

​Effort tiers

​Example

​Response

​search_web

​Parameters

​Example

​Response

`search_insights`

Parameters

Query format

Response

`get_document`

Parameters

Response

`list_documents`

Parameters

Response

`list_filter_options`

Parameters

Response

`deep_search`

Parameters

Effort tiers

Example

Response

`search_web`

Parameters

Example

Response