MCP Setup

Install and Check Settings

Use Python 3.11 or newer. On Windows, use the virtual environment's Scripts directory instead of bin. Install from a checkout; registry availability is not required.

Set MADEENAN_API_KEY through your host's secret settings or process environment. The API base URL defaults to https://api.madeenan.com. Set MADEENAN_API_BASE_URL for a self-hosted API and MADEENAN_TIMEOUT for a request timeout in seconds.

Connect Your MCP Host

This is the common mcpServers JSON format, not a universal host format. Use the output of --print-config to get your actual executable path. Other hosts may use a different configuration format.

Follow the official local-host setup guide for the host's configuration location. Merge the Madeenan entry with your existing servers; do not replace the whole file.

The generated configuration contains no key. A desktop host may not inherit your terminal environment. Configure MADEENAN_API_KEY in that host, then restart or reconnect it. Do not paste a key into a tool prompt or commit the host configuration if it contains credentials.

Check the Connection

1. Confirm that the host lists the Madeenan tools.
2. Read config://status if your host supports MCP resources. Check api_key_configured without exposing the key.
3. Call lookup_quran_reference with reference set to 2:153.
4. Call search_islamic_sources with query set to patience and indexes set to [quran, hadith].
5. Inspect the returned reference and source metadata. An empty search result is not a connection failure.

These tool calls contact the Madeenan API and are subject to its limits. The offline configuration check does not prove that a key is valid or that the API is reachable.

Choose a Tool

• search_islamic_sources: find candidate source records.
• lookup_quran_reference, lookup_hadith_reference, and lookup_dua: retrieve known references.
• find_quote_source: find matching wording; a match does not prove authorship.
• create_evidence_bundle: collect sources for review.
• review_evidence_claim: prepare a review checklist, not a truth assessment or ruling.

Troubleshoot Setup

• Command not found: use the absolute executable path from your virtual environment.
• Invalid settings: run --check-config and correct the named environment variable.
• Authentication failure: confirm that the host process receives your key. Do not send it as a tool argument.
• Rate limit or timeout: reduce requests and check upstream limits before retrying.
• No tool list: check the host's MCP logs and confirm that the command uses stdio.