Skip to main content
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:
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: sandbox keys are free and cover a curated set of 12 instruments; live keys (the Plus plan) 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

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

​
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 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.
Pro 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.