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

# MCP server

> Use halal.sh Shariah compliance as a tool inside ChatGPT, Claude, Codex, Gemini, Cursor, VS Code, and any MCP client.

The halal.sh **MCP server** exposes the compliance API as tools an AI agent can
call directly. Ask *"is NVDA halal?"* or *"screen my portfolio"* and the agent
queries halal.sh with our methodology, ratios, evidence, and citations.

Every tool is **read-only** — nothing changes state — so clients can auto-approve
calls without a confirmation prompt.

## Connect

The hosted server speaks [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-25) at:

```
https://api.halal.sh/mcp
```

There are two ways to authenticate, depending on the client:

* **Sign in (the ChatGPT and Claude apps).** Add the URL as a connector and
  sign in with your halal.sh account when prompted. No key to manage.
  Signed-in connectors are currently scoped to the sandbox universe on every
  plan while full-universe connector access completes security review.
* **API key (developer tools).** Claude Code, Codex, Gemini CLI, Cursor, and
  VS Code send the key as a Bearer header. [Create a key](https://halal.sh/account/api):
  sandbox keys are free and cover a curated set of 12 instruments; live keys
  (the [Plus plan](https://halal.sh/plans)) unlock the full universe.

### ChatGPT

1. Open **Settings → Connectors**, and under **Advanced** turn on
   **Developer mode** (custom connectors require it, on a paid ChatGPT plan).
2. Choose **Create**, name it `halal.sh`, and paste
   `https://api.halal.sh/mcp` as the MCP server URL.
3. Complete the halal.sh sign-in when prompted, then enable the connector
   from the tools menu in a chat.

### Claude (claude.ai and Claude Desktop)

1. Open **Settings → Connectors → Add custom connector** (paid Claude plans).
2. Paste `https://api.halal.sh/mcp` and choose **Add**.
3. Click **Connect** and sign in with your halal.sh account. The tools then
   appear in the chat tools menu on web, desktop, and mobile.

### Claude Code, Codex, Gemini CLI, Cursor, VS Code

<CodeGroup>
  ```bash Claude Code theme={null}
  claude mcp add --transport http halal https://api.halal.sh/mcp \
    --header "Authorization: Bearer hsh_sandbox_your_key"
  ```

  ```toml Codex (~/.codex/config.toml) theme={null}
  [mcp_servers.halal]
  url = "https://api.halal.sh/mcp"
  http_headers = { "Authorization" = "Bearer hsh_sandbox_your_key" }
  ```

  ```bash Gemini CLI theme={null}
  gemini mcp add --transport http halal https://api.halal.sh/mcp \
    --header "Authorization: Bearer hsh_sandbox_your_key"
  ```

  ```json Cursor (~/.cursor/mcp.json) theme={null}
  {
    "mcpServers": {
      "halal": {
        "url": "https://api.halal.sh/mcp",
        "headers": { "Authorization": "Bearer hsh_sandbox_your_key" }
      }
    }
  }
  ```

  ```json VS Code (.vscode/mcp.json) theme={null}
  {
    "servers": {
      "halal": {
        "type": "http",
        "url": "https://api.halal.sh/mcp",
        "headers": { "Authorization": "Bearer hsh_sandbox_your_key" }
      }
    }
  }
  ```
</CodeGroup>

<Warning>
  Treat the key like a password — keep it in your client's local config, never
  in shared or client-side code. The server is read-only, but your key counts
  against your plan's rate limits.
</Warning>

## Tools

| Tool                     | What it does                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------- |
| `screen_stock`           | Full AAOIFI determination for one stock — screens, segments, purification, stability. |
| `screen_portfolio`       | Compliant/non-compliant verdicts for up to 50 tickers at once.                        |
| `search_instruments`     | Find a stock's ticker by company name.                                                |
| `get_financials`         | Extracted financial metrics + the calculated AAOIFI ratios.                           |
| `get_evidence_packet`    | Audit-ready bundle: each screen's calculation + source filings.                       |
| `get_compliance_history` | How a determination changed across filing periods.                                    |
| `get_financial_health`   | Fragile / robust / antifragile rating and its five ratios.                            |
| `get_etf`                | An ETF's Shariah purity and holdings breakdown.                                       |
| `get_etf_holdings`       | Per-holding compliance, paginated.                                                    |
| `get_methodology`        | AAOIFI Standard 21 thresholds, screens, and version.                                  |
| `search_methodology`     | What the standard *says* about a rule (debt, liquidity, purification…).               |

## Sandbox vs full access

A **sandbox key** restricts the tools to the sandbox universe (AAPL, MSFT, NVDA,
GOOGL, JPM, GS, META, TSLA, JNJ, AMZN, SPY, HLAL) — ideal for trying it out.
A **live key** unlocks the full stock & ETF universe and comes with the
[halal.sh Plus plan](https://halal.sh/plans). Signed-in (OAuth) connectors from
the ChatGPT and Claude apps are scoped to the sandbox universe on every plan
for now. Unknown or ETF tickers passed to
`screen_portfolio` come back in `not_found`, and any symbol outside a sandbox
key's universe comes back in `sandbox_restricted`, rather than as fake rows or
silent drops.

<Note>
  Pro live keys are for your own use: research, automations, and internal
  workflows. Building a product on halal.sh is a
  [separate developer plan](https://halal.sh/developers).
</Note>

## Reading the docs from your editor

Separately, this documentation is itself available as an MCP server at
`https://docs.halal.sh/mcp` (auto-hosted by our docs platform — which is why
this guide lives at `/mcp-server`) for "how do I use endpoint X" questions.
Use the **Copy MCP server URL** action in the contextual menu in each page's
header to add it to your client.