Overview

Alchemist exposes a full Model Context Protocol (MCP) server. Any MCP-compatible agent can call Alchemist’s search and document tools without writing any integration code — you just point the agent at the endpoint.

MCP endpoint

https://api.askalchemist.com/mcp/

Transport: Streamable HTTP (MCP 2025 spec) Authentication — two options, both on the Authorization: Bearer header:

Method	Use when	How
OAuth 2.0	Your client supports it — Claude Code, claude.ai, Claude Desktop, Cursor, Codex CLI, OpenClaw, and Hermes all do it out of the box	Point the client at the endpoint with no credential. Alchemist returns `WWW-Authenticate` with its authorization server, and clients register themselves via Dynamic Client Registration.
API key	Headless runs, CI, or clients without OAuth (ChatGPT, the OpenAI SDKs)	`Authorization: Bearer alch_YOUR_KEY`

OAuth signs you in as an existing Alchemist user, so sign in once at app.askalchemist.com before connecting. API keys come from Settings → API keys.

Available tools

Tool	What it does
`search_insights`	Primary search — semantic query over the full document database
`get_document`	Fetch a document and all its insights by `doc_id`
`list_documents`	Browse documents by source or date
`list_filter_options`	Get all valid `source_name` values
`deep_search`	Agentic research in one call — our agent runs the full loop and returns a synthesized, cited answer. Preferred when you want an answer, analysis, or outlook rather than raw results
`search_web`	Fallback live web search when the database has no results

Shared configs — configure once

Several agent surfaces share configuration, so you may not need to set things up more than once:

If you configure here	It also works in
Claude.ai Connectors UI	Claude Desktop, and Claude Code — but only when Claude Code’s active auth is that same claude.ai subscription login
`.mcp.json` in your project root	Claude Code CLI, Claude Code web, VS Code extension
Cursor `.cursor/mcp.json`	Roo Code, Continue, and other VS Code MCP agents (same format)

claude_desktop_config.json is not on this list. It holds local stdio servers only — a remote MCP server can’t be configured there, and claude mcp add-from-claude-desktop therefore won’t carry Alchemist into Claude Code. Add it with claude mcp add instead.

Choose your integration

Claude

Claude.ai web, Claude Desktop, and Claude Code — configure once, sync everywhere.

Cursor

Cursor IDE — one JSON block in .cursor/mcp.json.

Codex

OpenAI Codex — one command: codex mcp add --url … .

ChatGPT

ChatGPT Custom GPT Actions — REST-based, API key.

OpenAI Agents SDK

Python & JS — connect Alchemist as an MCP server in your agent.

OpenAI Responses API

Hosted mcp tool — OpenAI calls Alchemist server-side.

OpenClaw

OpenClaw personal AI assistant — OAuth via openclaw mcp add --auth oauth.

Hermes

Nous Research Hermes Agent — built-in MCP client, OAuth or API key.

Generic MCP

Any MCP-compatible client — copy-paste config and system prompt.

Manual integration (non-MCP)

If your agent doesn’t support MCP, integrate directly via the REST API:

You have access to Alchemist — a financial research database of primary source documents
(FOMC minutes, USDA WASDE, SEC filings, economic releases, etc.).

To search it, call:
  POST https://api.askalchemist.com/api/insights/search
  Header: X-API-Key: alch_YOUR_KEY
  Body: {"query": "<focused 3-8 word phrase or question>", "source_name": null, "since": null, "limit": 20}

To get a full document:
  GET https://api.askalchemist.com/api/documents/{doc_id}
  Header: X-API-Key: alch_YOUR_KEY

To list available sources:
  GET https://api.askalchemist.com/api/documents/filters
  Header: X-API-Key: alch_YOUR_KEY

Search guidance:
- Phrase queries as one focused concept (3–8 words or a concise question).
- Avoid keyword soup and conversational wrappers like "tell me about".
- Run 1–2 searches, read results, then refine.
- Retry with different phrasing before concluding the database has nothing.
- For deep research, find a doc_id via search, then fetch that document for full context.
- Call /api/documents/filters first when you need to filter by source.

Get Started

Add to Agents

MCP Reference

API Reference

MCP endpoint

Available tools

Shared configs — configure once

Choose your integration

Claude

Cursor

Codex

ChatGPT

OpenAI Agents SDK

OpenAI Responses API

OpenClaw

Hermes

Generic MCP

Manual integration (non-MCP)

​MCP endpoint

​Available tools

​Shared configs — configure once

​Choose your integration

Claude

Cursor

Codex

ChatGPT

OpenAI Agents SDK

OpenAI Responses API

OpenClaw

Hermes

Generic MCP

​Manual integration (non-MCP)

MCP endpoint

Available tools

Shared configs — configure once

Choose your integration

Manual integration (non-MCP)