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

# Quickstart

> Connect Alchemist to your AI assistant, or call the REST API directly.

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

<Tabs>
  <Tab title="MCP">
    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.

    <Note>
      **Create an Alchemist account first.** OAuth signs you in as an existing user, so if you have never signed in at [app.askalchemist.com](https://app.askalchemist.com), do that once before connecting. Otherwise the server returns `401` even after a successful sign-in.
    </Note>

    ### 1. Add the server

    ```bash theme={null}
    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.

    ### 2. Sign in

    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:

    ```bash theme={null}
    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.

    <Card title="Add to other agents" icon="robot" href="/agents/overview">
      Cursor, Codex, ChatGPT, OpenAI Agents and Responses, Hermes, OpenClaw, plus API-key setup, team-shared config, and troubleshooting.
    </Card>
  </Tab>

  <Tab title="REST API">
    ### 1. Get an API key

    Open **[app.askalchemist.com/settings/api-keys](https://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.

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

    ### 2. Run your first search

    <CodeGroup>
      ```bash cURL theme={null}
      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"}'
      ```

      ```python Python theme={null}
      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()
      ```

      ```typescript TypeScript theme={null}
      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));
      ```
    </CodeGroup>

    ### Example response

    ```json theme={null}
    {
      "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:

    ```bash theme={null}
    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
      }'
    ```

    <Card title="API reference" icon="code" href="/api-reference/overview">
      Every endpoint: request shapes, response schemas, and error codes.
    </Card>
  </Tab>
</Tabs>


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