MCP server

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 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: the connector gets whatever your plan grants, the sandbox universe on Free, the full universe on Plus. A plan change reaches the connector within five minutes; there is nothing to reconnect.
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 cover a curated set of 12 instruments; live keys (the Plus plan) unlock the full universe.

ChatGPT

Open Settings → Connectors, and under Advanced turn on Developer mode (custom connectors require it, on a paid ChatGPT plan).
Choose Create, name it halal.sh, and paste https://api.halal.sh/mcp as the MCP server URL.
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)

Open Settings → Connectors → Add custom connector (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 your key 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`	Compliant/non-compliant verdicts for up to 50 tickers at once; fund tickers are routed to `get_etf`.
`discover_stocks`	Stocks that match filters: compliance status, sector, market-cap band, financial health, country; largest first on request. Each row names the `instrument_id` to pass to `screen_stock`. Plus plan.
`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`	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…). Pass `section` to read one part in full.

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. Signed-in (OAuth) connectors from the ChatGPT and Claude apps follow the same rule through your account: sandbox universe on Free, full universe on Plus. Scope follows your active subscription rather than the credential: if Plus lapses, a live key and a signed-in connector both fall back to the sandbox universe until it is renewed. Nothing is silently dropped or faked. Unknown tickers passed to screen_portfolio come back in not_found; fund tickers come back in not_found and in etfs, which is your cue to call get_etf; and any symbol outside a sandbox-scoped caller’s universe comes back in sandbox_restricted.

Plus live keys are for your own use: research, automations, and internal workflows. Building a product on halal.sh is a separate developer plan.

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.

Getting Started

Core Concepts

Guides

Connect

ChatGPT

Claude (claude.ai and Claude Desktop)

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

Tools

Sandbox vs full access

Reading the docs from your editor

​Connect

​ChatGPT

​Claude (claude.ai and Claude Desktop)

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

​Tools

​Sandbox vs full access

​Reading the docs from your editor

Connect

ChatGPT

Claude (claude.ai and Claude Desktop)

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

Tools

Sandbox vs full access

Reading the docs from your editor