> ## Documentation Index
> Fetch the complete documentation index at: https://docs.askalchemist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Connect Alchemist to your AI agent in two minutes via MCP or REST.

Alchemist exposes a full [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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](https://app.askalchemist.com) before connecting. API keys come from [Settings → API keys](https://app.askalchemist.com/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)                                                      |

<Note>
  `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.
</Note>

## Choose your integration

<CardGroup cols={2}>
  <Card title="Claude" icon="message-circle" href="/agents/claude">
    Claude.ai web, Claude Desktop, and Claude Code — configure once, sync everywhere.
  </Card>

  <Card title="Cursor" icon="code-2" href="/agents/cursor">
    Cursor IDE — one JSON block in `.cursor/mcp.json`.
  </Card>

  <Card title="Codex" icon="square-terminal" href="/agents/codex">
    OpenAI Codex — one command: `codex mcp add --url … `.
  </Card>

  <Card title="ChatGPT" icon="bot" href="/agents/chatgpt">
    ChatGPT Custom GPT Actions — REST-based, API key.
  </Card>

  <Card title="OpenAI Agents SDK" icon="braces" href="/agents/openai-agents">
    Python & JS — connect Alchemist as an MCP server in your agent.
  </Card>

  <Card title="OpenAI Responses API" icon="server" href="/agents/openai-responses">
    Hosted `mcp` tool — OpenAI calls Alchemist server-side.
  </Card>

  <Card title="OpenClaw" icon="terminal" href="/agents/openclaw">
    OpenClaw personal AI assistant — OAuth via `openclaw mcp add --auth oauth`.
  </Card>

  <Card title="Hermes" icon="cpu" href="/agents/hermes">
    Nous Research Hermes Agent — built-in MCP client, OAuth or API key.
  </Card>

  <Card title="Generic MCP" icon="plug" href="/agents/generic">
    Any MCP-compatible client — copy-paste config and system prompt.
  </Card>
</CardGroup>

## 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.
```