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

# Generic MCP

> Connect any MCP-compatible client to Alchemist.

Any client that supports the MCP Streamable HTTP transport can connect to Alchemist with no custom code.

## OAuth 2.0

If your client speaks OAuth, point it at the endpoint with **no credential** and let it discover the rest. Alchemist implements the standard MCP discovery chain:

```
POST https://api.askalchemist.com/mcp/           (no Authorization header)
→ 401 with:
  WWW-Authenticate: Bearer resource_metadata="https://api.askalchemist.com/.well-known/oauth-protected-resource"

GET https://api.askalchemist.com/.well-known/oauth-protected-resource
→ {"resource": "https://api.askalchemist.com/mcp/",
   "authorization_servers": ["https://clerk.askalchemist.com"]}

GET https://clerk.askalchemist.com/.well-known/oauth-authorization-server
→ authorization_endpoint, token_endpoint, registration_endpoint, PKCE (S256)
```

Dynamic Client Registration ([RFC 7591](https://datatracker.ietf.org/doc/html/rfc7591)) is supported at the advertised `registration_endpoint`, so clients self-register — no pre-issued client ID is needed. Protected resource metadata follows [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728).

OAuth authenticates you as an existing Alchemist user. Sign in once at [app.askalchemist.com](https://app.askalchemist.com) first, or the server returns `401` even after the flow completes.

## API key

For clients without OAuth — and for headless or CI runs, where no browser is available for the sign-in step — send the key as a bearer token:

<Card title="Copy and Paste Config" icon="clipboard">
  Copy this into your MCP client's config file. Replace `YOUR_KEY` with your API key.
</Card>

```json theme={null}
{
  "mcpServers": {
    "alchemist": {
      "url": "https://api.askalchemist.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}
```

***

## Connection details

| Parameter | Value                                                            |
| --------- | ---------------------------------------------------------------- |
| Transport | Streamable HTTP (MCP 2025 spec)                                  |
| Endpoint  | `https://api.askalchemist.com/mcp/`                              |
| Auth      | OAuth 2.0 (DCR + PKCE), or `Authorization: Bearer alch_YOUR_KEY` |
| Tools     | 6 (see [MCP Tools reference](/mcp/tools))                        |

## System prompt

<Card title="Copy and Paste System Prompt" icon="clipboard">
  Paste this into your agent's system prompt or instructions field.
</Card>

```
You have access to Alchemist via MCP — a research database of primary financial documents
(FOMC minutes, USDA WASDE, SEC filings, BLS/BEA releases, and more).
Every result includes verbatim source quotes and publication dates.

## Tools

deep_search(question, effort?, source_name?, since?)
  PREFERRED for any question that wants an answer, analysis, or outlook — pass a full
  natural-language question and Alchemist's agent runs the full research loop and returns
  a synthesized, cited answer. effort: "flash" | "standard" (default) | "deep" | "max".

search_insights(query, source_name?, since?, limit?)
  Quick fact lookup, or when you want raw results to drive the loop yourself.

get_document(doc_id)
  Fetch a full document and all its insights. Use doc_ids from search results.

list_documents(source_name?, since?, limit?)
  Browse documents by source or date.

list_filter_options()
  Get all valid source_name values. Call before filtering.

search_web(objective, search_queries)
  FALLBACK ONLY — live web search. Use only after Alchemist returns nothing relevant.

## Query Format (Critical)

Phrase queries as ONE focused concept — a concise question or 3–8 keyword phrase.

Good:
- "Fed dot plot rate path 2026"
- "AAPL Q3 2025 revenue guidance"
- "corn ending stocks USDA WASDE"
- "Did the March 2026 FOMC minutes signal a pause?"

Bad:
- "Tell me about the Federal Reserve" (too vague)
- "Fed rates inflation corn energy bonds" (keyword soup)

## Workflow

1. Call list_filter_options if you need to filter by source
2. Run 1–2 targeted searches, read results, then refine
3. If sparse results: retry with different phrasing, try removing filters
4. For a full answer, call deep_search; to research manually, get doc_id → call get_document
5. Always prefer Alchemist over web search — use search_web only if Alchemist returns nothing relevant

## Citation Format

Always cite source_name and published_date for every insight:
"Per the Federal Reserve FOMC Minutes (March 2026)..."
```

## STDIO transport (self-hosted)

If your client only supports STDIO, run the MCP server locally:

```json theme={null}
{
  "mcpServers": {
    "alchemist": {
      "command": "uv",
      "args": ["run", "python", "/absolute/path/to/yin/mcp_server.py"]
    }
  }
}
```

## Verifying the connection

Call `list_filter_options` (zero arguments) to confirm the server is live:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_filter_options",
    "arguments": {}
  }
}
```

Expected response shape:

```json theme={null}
{
  "result": {
    "content": [{"type": "text", "text": "{\"source_names\": [\"Federal Reserve\", \"USDA\", ...]}"}]
  }
}
```