> ## 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 research database of primary source documents across filings,
policy, energy and commodities, and independent analyst research.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.