MCP qoşulması

huqsi API həm də MCP serveridir (Model Context Protocol, Streamable HTTP nəqli). AI köməkçiniz qanunvericilikdə özü axtarış edib maddələri oxuya bilir.

URL: https://api.huqsi.az/mcp
Alətlər: search_law (semantik axtarış) · get_article (maddənin cari mətni) · get_article_history (dəyişiklik tarixçəsi). Bunlar REST-dəki üç imkanın eynisidir və eyni plan və limitlərlə işləyir.

Qoşulmanın iki yolu var. Hər ikisi eyni hesaba, eyni plana və eyni ortaq kvotaya bağlıdır.

Yol	Kimlər üçün	Açar lazımdır?
OAuth («Add custom connector» → «Connect»)	Claude.ai, Claude Desktop, Claude mobil (Android/iOS), ChatGPT	xeyr
API açarı (`X-API-Key` başlığı)	Claude Code, Cursor, Gemini CLI, n8n, öz skriptləriniz	bəli, kabinetdən

1. OAuth: açarsız qoşulma

Klient serverə qoşulanda huqsi giriş səhifəsi açılır. Daxil olursunuz və icazə verirsiniz, connector aktivləşir. Heç nə kopyalamaq lazım deyil.

Klientdə fərdi connector əlavə edin və URL-ə https://api.huqsi.az/mcp yazın. Client ID və secret sahələrini boş saxlayın: klient özünü avtomatik qeydiyyatdan keçirir.
Connect basın. huqsi səhifəsində e-poçtunuzu yazın. Məktubda 6 rəqəmli kod və link olur:
kodu açıq səhifəyə yazın; və ya
linki həmin brauzerdə açıb «Daxil ol» basın.

Linki başqa cihazda açsanız (məs. telefonda), giriş olmur, sadəcə kod göstərilir. Onu ilk pəncərəyə yazın. Kod və link 15 dəqiqə etibarlıdır, bir dəfə işləyir. Koda 5 cəhd verilir. 3. Hesabınız yoxdursa, elə burada yaranır: istifadə şərtləri və məxfilik siyasəti ilə razılığı işarələyin. Yeni hesab Developer planı ilə başlayır. 4. Razılıq səhifəsində tətbiqin adını və qayıdış ünvanını yoxlayın (məs. claude.ai, chatgpt.com). Həmçinin hesabınız, planınız və bu ayın istifadəsi göstərilir. «İcazə ver» basın.

Claude.ai və Claude Desktop

Settings → Connectors → Add custom connector → Name: huqsi, URL: https://api.huqsi.az/mcp → Add → Connect. Team/Enterprise hesablarında connector-u əvvəlcə Owner əlavə edir. Sonra hər istifadəçi öz huqsi hesabı ilə «Connect» edir.

Claude mobil (Android / iOS)

Mobil tətbiq connector-ları claude.ai hesabınızdan götürür. Əvvəl claude.ai-də əlavə edin (yuxarıdakı addımlar). Telefonda «Connect» basanda giriş səhifəsi tətbiqin daxili brauzerində açılır (Android-də Chrome Custom Tab). Məktubdakı kodu həmin səhifəyə yazmaq ən rahat yoldur.

ChatGPT

Settings → Apps & Connectors → Advanced settings → Developer mode aktiv edin. Sonra Create → MCP Server URL: https://api.huqsi.az/mcp, Authentication: OAuth → Create. Giriş və razılıq yuxarıdakı kimidir. Bu bölmələr ChatGPT planınızdan asılıdır.

Qoşulmanın ömrü

Klient hər saat yeni giriş tokeni alır (60 dəqiqə). Bu, istifadəçi üçün görünmür.
Developer: qoşulma «Connect»-dən sonra 30 gün işləyir, sonra klient yenidən «Connect» istəyir (açarın müddətinin qarşılığı).
Starter, Pro, Business: qoşulma istifadə olunduqca uzanır, 90 gün istifadə olunmasa sönür.
Kabinetdə «Qoşulmuş tətbiqlər» bölməsində hər tətbiqin adı, qoşulma tarixi və son istifadəsi görünür. «Ləğv et» həmin tətbiqin bütün tokenlərini dərhal etibarsız edir. Bundan sonra tətbiq yenidən «Connect» istəyir.
Bir hesabda ən çox 10 aktiv qoşulma ola bilər. Bu hədd API açarı limitindən ayrıdır.

2. API açarı: başlıq ilə qoşulma

Başlıq dəstəkləyən klientlər və avtomatlaşdırma üçün. Açarı kabinetdə yaradın.

Claude Code (CLI):

claude mcp add --transport http huqsi https://api.huqsi.az/mcp --header "X-API-Key: hq_SİZİN_AÇARINIZ"

--header vermədən əlavə etsəniz, Claude Code OAuth ilə qoşulur: /mcp → huqsi → Authenticate. Brauzer açılır, qayıdış localhost-a olur.

Cursor (~/.cursor/mcp.json və ya layihədə .cursor/mcp.json):

{
  "mcpServers": {
    "huqsi": {
      "url": "https://api.huqsi.az/mcp",
      "headers": {"X-API-Key": "hq_SİZİN_AÇARINIZ"}
    }
  }
}

Gemini CLI (~/.gemini/settings.json):

{
  "mcpServers": {
    "huqsi": {
      "httpUrl": "https://api.huqsi.az/mcp",
      "headers": {"X-API-Key": "hq_SİZİN_AÇARINIZ"},
      "timeout": 30000
    }
  }
}

gemini → /mcp əmri ilə serverin və alətlərin görünməsini yoxlayın.

n8n (AI Agent):

Workflow-a AI Agent node-u əlavə edin, alət kimi MCP Client Tool seçin.
Endpoint: https://api.huqsi.az/mcp, Server Transport: HTTP Streamable.
Authentication: Header Auth → Name X-API-Key, Value hq_SİZİN_AÇARINIZ.
Agentin sistem promptunda qeyd edin: hüquqi suallarda əvvəl search_law, sonra get_article çağırsın və cavabda maddəyə istinad etsin.

Claude Desktop, OAuth əvəzinə açarla (claude_desktop_config.json, mcp-remote körpüsü ilə):

{
  "mcpServers": {
    "huqsi": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.huqsi.az/mcp", "--header", "X-API-Key:${HUQSI_API_KEY}"],
      "env": {"HUQSI_API_KEY": "hq_SİZİN_AÇARINIZ"}
    }
  }
}

ChatGPT Responses API (proqramdan):

{
  "model": "gpt-5",
  "tools": [{"type": "mcp", "server_label": "huqsi", "server_url": "https://api.huqsi.az/mcp",
             "headers": {"X-API-Key": "hq_SİZİN_AÇARINIZ"}, "require_approval": "never"}],
  "input": "Cinayət Məcəlləsinə görə oğurluğa görə hansı cəza nəzərdə tutulur?"
}

Authorization: Bearer hq_… də qəbul olunur: hq_ ilə başlayan bearer API açarı sayılır.

Sayğac

Yalnız alət çağırışları kvotadan sayılır. initialize, tools/list və bağlantının özü sayılmır.
OAuth və API açarı eyni limitlərdən istifadə edir: REST ilə ortaq aylıq kvota, dəqiqəlik limit və IP tavanı. Hamısı hesab üzrədir.
Kabinetdəki istifadə cədvəlində alətlər mcp:search_law, mcp:get_article, mcp:get_article_history adları ilə görünür. Hər qoşulmuş tətbiqin öz sayı da var.
Limit aşılanda alət xəta mətni qaytarır (rate_limited: …, quota_exceeded: …, ip_rate_limited: …). Bağlantı kəsilmir. Hər /mcp cavabında X-Plan başlığı var.

Yoxlama (MCP Inspector)

npx @modelcontextprotocol/inspector

Transport: Streamable HTTP, URL: https://api.huqsi.az/mcp. Sonra iki yoldan birini seçin:

OAuth: «Open Auth Settings» → «Quick OAuth Flow». Brauzerdə huqsi girişi və razılığı açılır.
Açar: Header X-API-Key əlavə edin.

«List Tools» üç aləti göstərməlidir, search_law sorğusu nəticə qaytarmalıdır.

Alətlərin davranışı

search_law(query, limit=5, law_ids=None, include_repealed=False) — results[] siyahısı qaytarır. Hər elementdə article_id, citation və maddədən qısa parça (snippet, ən çox 600 simvol) olur, tam mətn olmur. Model istinad etməzdən əvvəl get_article çağırmalıdır.
get_article(article_id) — dəqiq cari mətn, in_force və qısa tarixçə qaytarır: amendments_total və son 3 dəyişiklik aktı (recent_amendments). Bu, çox vaxt ayrıca tarixçə çağırışını lazımsız edir. Mətn ən çox 30 000 simvoldur, daha uzunu truncated: true ilə kəsilir. Id-ni təxmin etməyin: əvvəl search_law çağırın.
Cavab sahələri REST ilə eynidir (REST nümunələri): amendments_total dəyişiklik aktlarının sayıdır, stored_versions isə yalnız bazada saxlanan mətn versiyalarının sayı (hüquqi dəyişiklik sayı deyil); first_seen_at cari mətnin bazada ilk göründüyü, data_updated_at bazanın son yeniləndiyi vaxtdır. Vaxtlar UTC-dədir (2026-11-01T02:08:57.435Z), tarixlər YYYY-MM-DD; dəyəri olmayan sahə null olur.
get_article_history(article_id, limit=20, offset=0) — maddəni dəyişdirən bütün aktlar. Köhnə redaksiyaların mətni yoxdur. Alət təsvirləri modelə köhnə mətni uydurmamağı açıq deyir.
Alət təsvirləri ingiliscədir (modellər üçün ən etibarlı dil). Qayıdan mətnlər isə rəsmi Azərbaycan dilindədir. Model tərcümə etsə, təsvirlər ona tərcümənin qeyri-rəsmi olduğunu deməyi və rəsmi mətnə istinad etməyi tapşırır. Məhkəmə qərarları bu serverdə yoxdur.