Is the HalalScreener MCP free?

Yes. A free tier gives 3 verdict-only screens (lifetime total). Premium ($16.99/mo) unlocks unlimited screening, full ratios, the reasoning trail, purification amounts, and the AI Scholar.

Is an MCP verdict a fatwa?

No. Verdicts are informational, algorithmic applications of AAOIFI Standard No. 21: batch-screened, never an autonomous trade gate, and assume a human in the loop. Consult a qualified scholar.

How do I connect it to Claude or Cursor?

In ChatGPT or Claude, add https://halalscreener.app/api/mcp/mcp as a custom connector and sign in with your HalalScreener account; no key needed. For Claude Desktop or Cursor you can also add `npx -y halalscreener-mcp` with your HALALSCREENER_API_KEY.

Model Context Protocol

The halal compliance layer for your AI agent

Connect Claude, Cursor, or ChatGPT to HalalScreener and let your agent screen stocks for Shariah compliance under AAOIFI Standard No. 21, with audited, explainable verdicts, purification, and the AI Scholar. Read-only and informational, never a trade gate.

Add to Cursor (1-click)Get an API key Read the docs

Built for trust, not blind automation

Every verdict carries a methodology version, the ratios used, a freshness flag, a reproducible audit hash, and a "consult a scholar" flag. Verdicts are batch-screened (not real-time), not a fatwa, and assume a human in the loop. We never tell your agent to buy or sell.

Add to ChatGPT or Claude: no key needed

Paste this address into your AI app as a custom connector. It opens a HalalScreener sign-in, you press Allow, and you are connected.

https://halalscreener.app/api/mcp/mcp

Claude: Settings, Connectors, Add custom connector, paste the address, then Connect.
ChatGPT: Settings, Apps & Connectors, add a custom connector with this address and OAuth sign-in (needs Developer mode under Advanced).
Any other app that supports remote MCP servers with sign-in works the same way.

Without Premium you get 3 verdict screens through connected apps; Premium unlocks every tool. Manage connected apps

Connect in 60 seconds

1Generate an API key on the developers page. It starts with hs_live_ and is shown once, so copy it right away.
2Copy the config below into your client's MCP file (paths listed under each option).
3Replace hs_live_your_key with your real key. The placeholder on its own returns 401 Unauthorized.
4Restart the client. Ask it "Is AAPL halal?" to confirm the server is live.

Option A: Local (Claude Desktop / Cursor)

Paste this into the file for your client, then restart it:

Claude Desktop: Settings → Developer → Edit Config, which opens claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\)
Cursor: Settings → MCP → Add new global MCP server, which opens ~/.cursor/mcp.json (or .cursor/mcp.json inside a project)

{
  "mcpServers": {
    "halalscreener": {
      "command": "npx",
      "args": ["-y", "halalscreener-mcp"],
      "env": { "HALALSCREENER_API_KEY": "hs_live_your_key" }
    }
  }
}

Used "Add to Cursor (1-click)" above? It installs the server with a placeholder key. Open Cursor Settings → MCP → halalscreener and paste your real key into HALALSCREENER_API_KEY.

Option B: Remote (Streamable HTTP)

For clients that support remote MCP servers (ChatGPT, Claude.ai connectors), point them at the hosted endpoint with your key as a Bearer token:

https://halalscreener.app/api/mcp/mcp
Authorization: Bearer hs_live_your_key

Tools

Tool	Tier	What it does
screen_stock	Free	AAOIFI verdict + grade + reproducible audit hash for a symbol.
pretrade_check	Free	Pre-trade guardrail: pass, fail or review for an order, with a signed receipt (EdDSA JWT) to attach to the order log.
screen_portfolio	Free	Per-symbol verdicts plus a portfolio compliance summary.
get_stock_detail	Premium	Full financial + qualitative/quantitative breakdown.
explain_verdict	Premium	The auditable 'why' behind a verdict: the gate that drove it.
calculate_purification	Premium	Impure income to donate, per AAOIFI Standard No. 21.
ask_scholar	Premium	Conversational multi-madhab Islamic-finance Q&A (AI Scholar).
check_compliance_changes	Premium	Portfolio drift monitor: which holdings changed status since a date.
compliance_history	Premium	A stock's AAOIFI verdict timeline over time.

Free tier: 3 verdict-only screens total (pretrade_check counts as a screen). Premium ($16.99/mo) unlocks unlimited screening, full verdicts, the reasoning trail, purification, agent webhooks, and the AI Scholar.

Make your agent halal-aware

Generate a key, paste the config, and your AI can screen any US-listed stock, ETF, or major crypto for Shariah compliance, with the receipts.

Get your API key