MCP server

With the halal.sh MCP server, an AI agent can call the compliance API as tools. Ask “is NVDA halal?” or “screen my portfolio”, and the agent answers with our determination, the ratios and the filings behind them. Every tool is read-only, so your client can run calls without asking you to confirm each one.

Connect

The hosted server is at this address and uses Streamable HTTP:

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. There is no key to manage: the connector has the full universe on the Plus plan or the Developer plan, and the sandbox universe otherwise. It picks up a plan change within five minutes, without reconnecting.
API key (developer tools): Claude Code, Codex, Gemini CLI, Cursor and VS Code send the key as a Bearer header. Create a key: sandbox keys are free and limited to 12 instruments, and live keys, on the Plus plan or the Developer plan, have the full universe.

ChatGPT

Open Settings, then Connectors, and under Advanced turn on Developer mode (custom connectors need it; it’s on paid ChatGPT plans).
Choose Create, name it halal.sh, and paste https://api.halal.sh/mcp as the MCP server URL.
Sign in to halal.sh when prompted, then turn on the connector from the tools menu in a chat.

Claude (claude.ai and Claude Desktop)

Open Settings, then Connectors, and choose Add custom connector (on paid Claude plans).
Paste https://api.halal.sh/mcp and choose Add.
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

claude mcp add --transport http halal https://api.halal.sh/mcp \
  --header "Authorization: Bearer hsh_sandbox_your_key"

[mcp_servers.halal]
url = "https://api.halal.sh/mcp"
http_headers = { "Authorization" = "Bearer hsh_sandbox_your_key" }

gemini mcp add --transport http halal https://api.halal.sh/mcp \
  --header "Authorization: Bearer hsh_sandbox_your_key"

{
  "mcpServers": {
    "halal": {
      "url": "https://api.halal.sh/mcp",
      "headers": { "Authorization": "Bearer hsh_sandbox_your_key" }
    }
  }
}

{
  "servers": {
    "halal": {
      "type": "http",
      "url": "https://api.halal.sh/mcp",
      "headers": { "Authorization": "Bearer hsh_sandbox_your_key" }
    }
  }
}

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 every call counts against your plan’s rate limits.

Tools

Tool	What it does
`screen_stock`	Full AAOIFI determination for one stock: screens, segments, purification, stability. A gold, silver or commodity vehicle comes back with its structural checklist and the methodology it was decided under.
`screen_portfolio`	Compliance status for up to 50 tickers at once. Fund tickers come back in `etfs`, to look up with `get_etf`.
`discover_stocks`	Stocks that match filters: compliance status, sector, market-cap band, financial health, country; largest first on request. Each row has the `instrument_id` to pass to `screen_stock`. Needs the Plus or Developer plan.
`search_instruments`	Find a stock’s ticker by company name.
`get_financials`	Extracted financial metrics and the calculated AAOIFI ratios.
`get_evidence_packet`	Audit-ready bundle: each screen’s calculation and its 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`	A methodology’s thresholds or criteria, screens, and version: `aaoifi-ss21`, `aaoifi-ss57`, `aaoifi-ss20` or `halal-sh-etf-taxonomy`.
`search_methodology`	What the standard says about a rule (debt, liquidity, purification and more). Pass `section` to read one part in full.

Sandbox and full access

With a sandbox key, the tools work on the sandbox universe only (AAPL, MSFT, NVDA, GOOGL, JPM, GS, META, TSLA, JNJ, AMZN, SPY, HLAL). A live key, which comes with Plus or the Developer plan, works on the full stock and ETF universe. Signed-in (OAuth) connectors from the ChatGPT and Claude apps follow the same rule through your account: the full universe on Plus or the Developer plan, and the sandbox universe otherwise. Without Plus or the Developer plan, a live key and a signed-in connector both fall back to the sandbox universe until you renew one. Every ticker screen_portfolio doesn’t screen comes back in a list: unknown tickers in not_found, fund tickers in not_found and in etfs (look those up with get_etf), and, on the sandbox, symbols outside it in sandbox_restricted.

On Plus, live keys and signed-in connectors are for your own use: research, automations, and internal workflows. To show halal.sh results to the users of your product, you need the Developer plan, a separate subscription from Plus.

Reading the docs from your editor

This documentation is also an MCP server, at https://docs.halal.sh/mcp, for questions about using the API. To add it to your client, use Copy MCP server URL in the contextual menu at the top of any page.

Getting Started

Core Concepts

Guides

Connect

ChatGPT

Claude (claude.ai and Claude Desktop)

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

Tools

Sandbox and full access

Reading the docs from your editor