Quickstart

Two ways in. Pick MCP if you want Alchemist inside an AI assistant, and the REST API if you are building something yourself.

MCP
REST API

The MCP server supports OAuth 2.0, so there is no API key to copy. You add the server, sign in with your Alchemist account, and the assistant discovers the tools on its own.

Create an Alchemist account first. OAuth signs you in as an existing user, so if you have never signed in at app.askalchemist.com, do that once before connecting. Otherwise the server returns 401 even after a successful sign-in.

1. Add the server

claude mcp add --transport http alchemist https://api.askalchemist.com/mcp/

No key and no header. Alchemist advertises its authorization server via WWW-Authenticate, so the client registers itself automatically.Run /mcp inside Claude Code, pick alchemist, choose Authenticate, and complete sign-in in your browser. The server then shows as connected.From the shell instead:

claude mcp login alchemist

3. Ask a question

What did Freeport say about copper production guidance?

The assistant calls search_insights, and every result comes back with the excerpt, the document, and its source.

Add to other agents

Cursor, Codex, ChatGPT, OpenAI Agents and Responses, Hermes, OpenClaw, plus API-key setup, team-shared config, and troubleshooting.

1. Get an API key

Open app.askalchemist.com/settings/api-keys, click Create key, give it a name, and copy the raw key. It starts with alch_ and is shown only once, so save it now.

The raw key is never stored. If you lose it, revoke it and create a new one.

2. Run your first search

curl -X POST https://api.askalchemist.com/api/insights/search \
  -H "X-API-Key: alch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "copper production guidance"}'

import httpx

resp = httpx.post(
    "https://api.askalchemist.com/api/insights/search",
    headers={"X-API-Key": "alch_YOUR_KEY"},
    json={"query": "copper production guidance"},
)
for insight in resp.json()["insights"]:
    print(insight["title"])
    print(insight["insight"])
    print(insight["source_name"], insight["published_date"])
    print()

const res = await fetch("https://api.askalchemist.com/api/insights/search", {
  method: "POST",
  headers: {
    "X-API-Key": "alch_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "copper production guidance" }),
});

const { insights } = await res.json();
insights.forEach((i) => console.log(i.title, i.source_name));

Example response

{
  "insights": [
    {
      "insight_id": "ins_01jwx...",
      "title": "Freeport reaffirms 2026 copper sales volume guidance",
      "insight": "Freeport-McMoRan reaffirmed consolidated copper sales guidance for 2026, citing recovery of milling rates at Grasberg following the mud rush incident.",
      "excerpts": [
        "Consolidated sales volumes for 2026 are expected to approximate 4.1 billion pounds of copper."
      ],
      "doc_id": "doc_01jww...",
      "doc_title": "Freeport Reports First-Quarter 2026 Results",
      "source_url": "https://www.sec.gov/Archives/edgar/data/831259/...",
      "source_name": "SEC",
      "published_date": "2026-04-23",
      "score": 0.68
    }
  ]
}

3. Add filters (optional)

Call GET /api/documents/filters for the live source list, then narrow:

curl -X POST https://api.askalchemist.com/api/insights/search \
  -H "X-API-Key: alch_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "copper production guidance",
    "source_name": "SEC",
    "since": "2026-01-01",
    "limit": 10
  }'

API reference

Every endpoint: request shapes, response schemas, and error codes.

Get Started

Add to Agents

MCP Reference

API Reference

1. Add the server

3. Ask a question

Add to other agents

1. Get an API key

2. Run your first search

Example response

3. Add filters (optional)

API reference

​1. Add the server

​2. Sign in

​3. Ask a question

Add to other agents

​1. Get an API key

​2. Run your first search

​Example response

​3. Add filters (optional)

API reference

1. Add the server

2. Sign in

3. Ask a question

1. Get an API key

2. Run your first search

Example response

3. Add filters (optional)