MCP connection

huqsi API is also an MCP server (Model Context Protocol, Streamable HTTP transport): your AI assistant can search Azerbaijani legislation and read articles by itself.

• URL: https://api.huqsi.az/mcp
• Tools: search_law (semantic search) · get_article (current text of an article) · get_article_history (amendment history). These are the same three capabilities as the REST API, with the same plan and limits.

There are two ways to connect. Both are tied to the same account, plan and shared quota.

1. OAuth: connect without a key

When the client connects, the huqsi sign-in page opens. You sign in and allow access, and the connector is active. Nothing to copy.

1. Add a custom connector in your client with the URL https://api.huqsi.az/mcp. Leave the client ID and secret empty: the client registers itself.
2. Press Connect. Enter your e-mail on the huqsi page. The e-mail contains a 6-digit code and a link:
3. type the code into the open page; or
4. open the link in the same browser and press «Sign in».

If you open the link on another device (e.g. your phone), it does not sign you in: it only shows the code. Type that code into the first window. The code and the link are valid for 15 minutes and work once. You get 5 tries at the code. 3. No account yet? It is created right there: tick the box to agree to the terms of use and the privacy policy. New accounts start on the Developer plan. 4. On the consent page, check the app name and its return address (e.g. claude.ai, chatgpt.com). The page also shows your account, plan and this month's usage. Press «Allow».

Claude.ai and Claude Desktop

Settings → Connectors → Add custom connector → Name: huqsi, URL: https://api.huqsi.az/mcp → Add → Connect. On Team/Enterprise accounts an Owner adds the connector first. Each user then connects with their own huqsi account.

Claude mobile (Android / iOS)

The mobile app uses the connectors of your claude.ai account. Add the connector on claude.ai first (steps above). When you press «Connect» on the phone, the sign-in page opens in the app's built-in browser (a Chrome Custom Tab on Android). Typing the code from the e-mail into that page is the easiest way.

ChatGPT

Settings → Apps & Connectors → Advanced settings → enable Developer mode. Then Create → MCP Server URL: https://api.huqsi.az/mcp, Authentication: OAuth → Create. Sign-in and consent are as above. Which of these menus you see depends on your ChatGPT plan.

Connection lifetime

• The client gets a new access token every hour (60 minutes); you do not notice this.
• Developer: the connection works for 30 days after «Connect», then the client asks you to connect again (the counterpart of the key lifetime).
• Starter, Pro, Business: the connection stays active while it is used and ends after 90 days without use.
• The dashboard lists every app under «Connected apps» with its name, connection date and last use. «Revoke» invalidates all of that app's tokens immediately. The app then asks you to «Connect» again.
• At most 10 active connections per account. This limit is separate from the API key limit.

2. API key: connect with a header

For clients that support headers and for automation. Create the key in the dashboard.

Claude Code (CLI):

claude mcp add --transport http huqsi https://api.huqsi.az/mcp --header "X-API-Key: hq_YOUR_KEY"

Without --header, Claude Code connects with OAuth instead: /mcp → huqsi → Authenticate. A browser opens and the result is returned to localhost.

Cursor (~/.cursor/mcp.json or .cursor/mcp.json in the project):

{
  "mcpServers": {
    "huqsi": {
      "url": "https://api.huqsi.az/mcp",
      "headers": {"X-API-Key": "hq_YOUR_KEY"}
    }
  }
}

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

{
  "mcpServers": {
    "huqsi": {
      "httpUrl": "https://api.huqsi.az/mcp",
      "headers": {"X-API-Key": "hq_YOUR_KEY"},
      "timeout": 30000
    }
  }
}

n8n (AI Agent): add an MCP Client Tool to the AI Agent node. Endpoint: https://api.huqsi.az/mcp, Server Transport: HTTP Streamable, Authentication: Header Auth with Name X-API-Key and Value hq_YOUR_KEY.

Authorization: Bearer hq_… is accepted too: a bearer value that starts with hq_ is treated as an API key.

Counting

• Only tool calls count against the quota. initialize, tools/list and the connection itself are free.
• OAuth and API keys use the same limits: one monthly quota shared with REST, the per-minute limit and the per-IP ceiling. All of them are per account.
• When a limit is hit, the tool returns an error text (rate_limited: …, quota_exceeded: …, ip_rate_limited: …). The connection stays open. Every /mcp response carries an X-Plan header.

Testing with MCP Inspector

npx @modelcontextprotocol/inspector

Transport: Streamable HTTP, URL: https://api.huqsi.az/mcp. Then pick one of the two ways:

• OAuth: «Open Auth Settings» → «Quick OAuth Flow». The huqsi sign-in and consent pages open in the browser.
• Key: add the header X-API-Key.

«List Tools» should show three tools, and a search_law call should return results.

Tool behaviour and the official text

• search_law returns short passages (snippet, at most 600 characters), not full texts. The model must call get_article before citing.
• get_article returns the exact current wording (at most 30 000 characters) and the 3 most recent amending acts.
• get_article_history lists all amending acts. Earlier wordings are not available.
• Response fields (same as REST):
• amendments_total (history: total) is the number of acts that amended the article.
• stored_versions is only the number of text versions stored in this database since 2026-10-07. It is not the number of legal amendments: amendments_total: 12 with stored_versions: 1 is normal.
• first_seen_at is when the current text first appeared in this database, not when the amendment was adopted.
• data_updated_at is when the database last received its daily update from e-qanun.az.
• Timestamps are UTC with milliseconds (2026-11-01T02:08:57.435Z); dates are YYYY-MM-DD. A field without a value is null, never an empty string. section_path is null for now (the source hierarchy is being fixed).
• The law texts are the official Azerbaijani wording. The tool descriptions tell the model that any translation it gives is unofficial and must point to the official text (law title, «maddə N», source URL). Court decisions are not in this server.