Model Context Protocol (MCP)를 사용하면 AI 클라이언트가 외부 도구를 직접 호출할 수 있습니다. Halal Terminal MCP 서버를 연결하면, 대시보드에 티커(ticker)를 복사하여 붙여넣을 필요 없이 일상적인 언어로 어떠한 주식이나 ETF라도 샤리아 (Shariah) 준수 여부를 스크리닝할 수 있습니다. 이 가이드는 약 5분 만에 기초부터 작동하는 설정까지 안내합니다.

얻을 수 있는 것

연결이 완료되면 Claude Desktop, Claude Code, Cursor 또는 기타 MCP 클라이언트 (Windsurf, Cline, Continue, Zed, Goose) 내에서 직접 "AAPL이 할랄(halal)인가요?" 또는 _"이 포트폴리오를 감사해 주세요: AAPL, MSFT, GOOGL"_와 같은 질문을 할 수 있습니다. 어시스턴트는 적절한 도구를 선택하고, API를 호출하여 실제 데이터로 답변합니다.

이 서버는 8개 카테고리에 걸쳐 22개의 도구를 제공합니다: 5가지 방법론 (AAOIFI, DJIM, FTSE, MSCI, S&P)에 따른 주식 및 ETF 스크리닝, 대량 인덱스 스크리닝, 실시간 시세 및 가격 이력, ETF 보유 자산 분석, 포트폴리오 및 관심 목록 스캔, 배당금 및 자카트 (zakat) 계산기, 뉴스 및 SEC 공시, 그리고 보고서 및 교육 도우미가 포함됩니다. 모든 판정은 방법론에 기반한 스크리닝이며, 파트와 (fatwa)가 아닙니다.

1단계: 무료 API 키 받기

api.halalterminal.com에서 가입하세요. 이메일로만 가입하며 신용카드는 필요하지 않고, 몇 초 안에 받은 편지함으로 키가 전송됩니다. 무료 티어에는 월 500개의 토큰이 포함되어 있어, 업그레이드하기 전에 서버를 평가하기에 충분합니다. 키는 ht_yourkey와 같은 형식입니다. 다음 단계를 위해 잘 보관해 두세요.

2단계: 클라이언트 연결하기

가장 빠른 전송 방식은 호스팅된 SSE 엔드포인트입니다. 로컬 브릿지가 필요한 클라이언트의 경우, @halalterminal/mcp 패키지가 이를 stdio로 래핑하며, npx 덕분에 별도의 설치가 필요하지 않습니다:

# 권장 사항 - 설치 불필요
npx -y @halalterminal/mcp

...

Claude Desktop

설정(Settings)을 열고, 개발자(Developer)로 이동하여, 설정 파일(config file)을 편집한 후 서버를 추가하세요. 본인의 키로 교체한 다음 Claude Desktop을 재시작하세요:

{
  "mcpServers": {
    "halalterminal": {
...

Claude Code

터미널에서 명령 한 줄로 SSE를 통해 호스팅된 서버를 등록할 수 있습니다:

claude mcp add --transport sse halalterminal \
  https://mcp.halalterminal.com/sse \
  --header "X-API-Key: ht_yourkey"

Cursor, Windsurf 또는 기타 직접 SSE 클라이언트

클라이언트의 SSE URL을 지정하고 쿼리 파라미터(query parameter)로 키를 입력하세요:

https://mcp.halalterminal.com/sse?api_key=ht_yourkey

끝입니다. 클라이언트는 22개의 모든 도구(tools)를 자동으로 검색합니다. 인증(Auth)은 클라이언트가 지원하는 방식에 따라 X-API-Key 헤더 또는 ?api_key= 쿼리 파라미터를 사용합니다.

3단계: 첫 번째 질문하기

일반적인 채팅 메시지처럼 입력하세요. 어시스턴트(assistant)는 각 메시지를 도구에 매핑하여 실시간 결과를 반환합니다.

• "Is AAPL halal?" (AAPL은 할랄인가요?): screen_stock을 호출하여 5가지 방법론 각각에 대한 판정 결과를 나란히 반환합니다. 본 게시물 작성 당시의 실시간 스크리닝 결과에 따르면, Apple은 5가지 기준(AAOIFI, DJIM, FTSE, MSCI, S&P) 모두에서 준수(compliant)하는 것으로 나타났습니다. 판정 결과는 재무 상태에 따라 변동되므로, 스냅샷보다는 항상 최신 결과를 신뢰하십시오.
• "Scan this portfolio: AAPL, MSFT, GOOGL" (이 포트폴리오를 스캔해줘: AAPL, MSFT, GOOGL): scan_portfolio를 호출하여 각 보유 종목에 대한 판정 결과와 바스켓 전체의 총 준수 비율(compliant percentage)을 반환합니다.
• "Calculate zakat on my holdings" (내 보유 자산에 대한 자카트(zakat)를 계산해줘): calculate_zakat을 호출하며, 보유 포지션을 입력하면 실시간 니삽(nisab) 임계값에 대해 2.5%를 적용합니다.
• "Compare SPUS vs HLAL" (SPUS와 HLAL을 비교해줘): compare_etfs를 호출하여 두 펀드의 준수 비율, 보유 종목, 총 정화율(purification rate)을 나란히 비교하여 귀하의 기준에 어떤 것이 적합한지 판단할 수 있게 합니다.
• "What is dividend purification for this stock?" (이 주식의 배당금 정화(purification) 금액은 얼마인가요?): 정화 기능이 활성화된 get_dividends를 호출하여 기부해야 할 비준수(non-compliant) 비율을 계산합니다.

어시스턴트는 구조화된 응답(structured response)을 읽을 수 있기 때문에 호출을 체이닝(chaining)할 수도 있습니다. 예를 들어, 한 대화 내에서 주식을 스크리닝한 다음 해당 주식의 최근 뉴스 및 SEC 공시 자료를 불러올 수 있습니다.

토큰 비용 (Token costs)

이 API는 요청(request) 기준이 아닌 토큰(token) 기준으로 측정됩니다. 일반적인 호출에는 대략 1~5개의 토큰이 소요됩니다. 전체 주식 스크리닝(stock screen)에는 5개의 토큰이 소요되므로, 무료 플랜의 500개 토큰으로는 한 달에 약 100번의 스크리닝을 수행할 수 있습니다. 시세(quote) 조회나 검색과 같은 가벼운 읽기 작업은 비용이 더 적게 듭니다. 각 엔드포인트(endpoint)별 전체 비용 표는 /api/keys/token-costs에서 확인할 수 있으며, 대시보드에서 언제든지 남은 잔액을 확인할 수 있습니다.

Halal Terminal으로 구축하세요

Halal Terminal API

22개의 MCP 도구, 5가지 스크리닝 방법론, ETF 보유 자산 분석 및 자카트(zakat) 계산기를 제공합니다. 신용카드 등록 없는 무료 티어(Free tier)를 이용해 보세요.

무료 API 키 받기 -> API 살펴보기

다음 단계

• 공식 MCP 레지스트리 (Official MCP registry): registry.modelcontextprotocol.io에서 등록된 서버를 찾아보세요.
• GitHub 리포지토리 (GitHub repo): 모든 클라이언트에 대한 설정 가이드, 전체 도구 참조 및 이슈 트래커를 github.com/goww7/halalterminal-mcp에서 확인할 수 있습니다.
• API 문서 (API docs): 대화형 참조 문서는 api.halalterminal.com/api-reference에 있습니다.

단 5분 만에 당신의 AI 클라이언트는 샤리아(Shariah) 스크리닝을 수행할 수 있게 됩니다. api.halalterminal.com에서 키를 발급받아 질문을 던져보세요.

중요 면책 조항 (Important Disclaimer)

금융 자문이 아닙니다. 이 페이지에서 제공하는 정보는 교육 및 정보 제공 목적으로만 제공되며, 금융 자문, 투자 자문, 매매 자문 또는 기타 어떠한 형태의 조언으로 해석되어서는 안 됩니다. 귀하는 오직 여기에 제시된 정보만을 근거로 어떠한 금융 결정도 내려서는 안 됩니다.

파트와(fatwa)가 아닙니다. 샤리아 준수 (Shariah compliance) 스크리닝 결과는 공개된 금융 데이터를 기반으로 한 자동화된 데이터 분석을 통해 생성됩니다. 이러한 결과는 종교적 판결 (fatwa)을 구성하지 않으며, 판결로 취급되어서는 안 됩니다. 귀하의 상황에 특화된 지침을 얻으려면 항상 자격을 갖춘 이슬람 학자 또는 샤리아 자문가에게 문의하십시오.

직접 조사하십시오. 과거의 성과와 현재의 준수 상태가 미래의 결과나 지속적인 준수를 보장하지는 않습니다. 스크리닝 데이터에는 오류가 포함되어 있거나 최신 정보가 아닐 수 있습니다. 항상 정보를 독립적으로 확인하고, 어떠한 투자 결정을 내리기 전에 자격을 갖춘 금융 자문가와 상담하십시오.

원문은 Halal Terminal 블로그에 게시되었습니다.