igw-error-management-mcp

v2.5.0

Published

14 days ago

MCP server for InsurGateway error management and ManagementConsole traffic inspection

0High
0Medium
0Low

eyupyusufa

mcp insurgateway igw error-management insurance model-context-protocol

InsurGateway Error Management MCP Server

A Model Context Protocol (MCP) server for tracking, analyzing, and reporting errors from InsurGateway.

Features

Error Tracking — List, filter, sort, and search errors by date, branch, product, company, agent, status, and free text
Error Logs — View detailed request/response logs for each error
Error Analysis — Get analysis details with possible causes and suggestions
Error Actions — Pin errors, update status, send reports, and file bug reports
Reports — Success rates, branch/agent/company breakdowns
Lookups — Search products and list insurance companies for filtering
ManagementConsole Traffic — Search successful and failed IGW traffic, then retrieve raw request/response payloads in either direction

Setup

Choose your tool below. Replace credentials with your own.

Environments

| Environment | IGW_BASE_URL | |-------------|----------------| | Test | https://testgatewayapi.insurapps.net/api | | Production | https://gatewayapi.insurapps.net/api |

Claude Code

claude mcp add-json --scope user igw-error-management '{
  "command": "npx",
  "args": ["-y", "igw-error-management-mcp@latest"],
  "env": {
    "IGW_BASE_URL": "https://testgatewayapi.insurapps.net/api",
    "IGW_USERNAME": "your-username",
    "IGW_PASSWORD": "your-password",
    "IGW_WEB_API_KEY": "your-api-key"
  }
}'

Claude Desktop

Edit config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "igw-error-management": {
      "command": "npx",
      "args": ["-y", "igw-error-management-mcp@latest"],
      "env": {
        "IGW_BASE_URL": "https://testgatewayapi.insurapps.net/api",
        "IGW_USERNAME": "your-username",
        "IGW_PASSWORD": "your-password",
        "IGW_WEB_API_KEY": "your-api-key"
      }
    }
  }
}

Restart Claude Desktop after saving.

Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global):

{
  "mcpServers": {
    "igw-error-management": {
      "command": "npx",
      "args": ["-y", "igw-error-management-mcp@latest"],
      "env": {
        "IGW_BASE_URL": "https://testgatewayapi.insurapps.net/api",
        "IGW_USERNAME": "your-username",
        "IGW_PASSWORD": "your-password",
        "IGW_WEB_API_KEY": "your-api-key"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "igw-error-management": {
      "command": "npx",
      "args": ["-y", "igw-error-management-mcp@latest"],
      "env": {
        "IGW_BASE_URL": "https://testgatewayapi.insurapps.net/api",
        "IGW_USERNAME": "your-username",
        "IGW_PASSWORD": "your-password",
        "IGW_WEB_API_KEY": "your-api-key"
      }
    }
  }
}

OpenAI Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.igw-error-management]
command = "npx"
args = ["-y", "igw-error-management-mcp@latest"]

[mcp_servers.igw-error-management.env]
IGW_BASE_URL = "https://testgatewayapi.insurapps.net/api"
IGW_USERNAME = "your-username"
IGW_PASSWORD = "your-password"
IGW_WEB_API_KEY = "your-api-key"

Antigravity (Firebase Studio)

Add to .idx/mcp.json in your workspace:

{
  "mcpServers": {
    "igw-error-management": {
      "command": "npx",
      "args": ["-y", "igw-error-management-mcp@latest"],
      "env": {
        "IGW_BASE_URL": "https://testgatewayapi.insurapps.net/api",
        "IGW_USERNAME": "your-username",
        "IGW_PASSWORD": "your-password",
        "IGW_WEB_API_KEY": "your-api-key"
      }
    }
  }
}

Example Queries

Once set up, try asking your AI assistant:

"Son 24 saatte hangi hatalar var?"
"Quick Sigorta'daki çözülmemiş hataları göster"
"Trafik branşında en çok hata veren sigorta şirketleri hangileri?"
"Bu hatanın request/response detayına bak"
"Son 1 haftada ConnectionError olan hataları listele"
"Allianz Sigorta'nın ürünlerinde timeout hatalarını getir"
"Bu hatayı analiz et, ne olmuş?"
"Bu hatayı IGW ekibine bug olarak raporla"
"Hata mesajında 'araç tarzı' geçen tüm kayıtları bul"
"Doğa Sigorta'nın başarı oranını göster"
"Branş bazında hata raporu çek"
"Bu hatanın durumunu 'Çözüldü' olarak güncelle"
"Hangi sigorta şirketleri aktif?"
"Kasko ürünlerini ara"
"Bu sigorta şirketi teklif numarasıyla IGW'nin şirkete gönderdiği request ve şirketten aldığı response'u getir"
"Bu referans numarasına bağlı outgoing ve incoming logları ara"
"Son yedi gündeki acente loglarını listele"

Tools

Error Queries (read-only)

| Tool | Description | |------|-------------| | igw_errors_list | List errors with filters, sorting, pagination, and free text search | | igw_errors_summary | Lightweight error statistics — status counts per operation type | | igw_errors_operations | Get error operations — which service operations produce errors | | igw_errors_logs | Get detailed error log entries | | igw_errors_log_detail | Get full request/response data for a specific error log | | igw_errors_analyze | Analyze a specific error — possible causes and suggestions |

Reports (read-only)

| Tool | Description | |------|-------------| | igw_errors_success_rate | Overall success/failure rates (proposals and policies) | | igw_errors_report_by_branch | Error report broken down by branch (Kasko, Trafik, etc.) | | igw_errors_report_by_company | Error report broken down by insurance company | | igw_errors_report_by_agent | Error report broken down by agent |

Error Actions (write)

| Tool | Description | |------|-------------| | igw_errors_pin | Pin/unpin an error for tracking | | igw_errors_update_status | Update error analysis status (Solved, InProgress, UserMistake, etc.) | | igw_errors_send_report | Send an error report with description to the relevant team | | igw_errors_send_bug_report | Send a bug report by reference number to InsurGateway |

Lookups (read-only)

| Tool | Description | |------|-------------| | igw_products_search | Search products by name — get product IDs for error filters | | igw_insurance_companies | List available insurance companies — get company IDs for error filters | | igw_products_list | Full product catalog from the GatewayProUI panel — GW product code, insurance company product code(s), branch, online/offline, active status. Requires IGW_PANEL_USERNAME / IGW_PANEL_PASSWORD | | igw_keys_list | Full request/response key catalog from the GatewayProUI panel — key Id, name, value type, parameterized flag, resolved parameter (id + name), dependent flag, active status. Requires IGW_PANEL_USERNAME / IGW_PANEL_PASSWORD |

ManagementConsole Traffic (read-only)

These tools read portal.insurapps.net/ManagementConsole and preserve insurer-specific payloads as raw JSON, XML, or text. They are registered only when portal credentials are available.

IGW_PORTAL_BASE_URL controls this environment independently of IGW_BASE_URL. The default portal URL is production, so enabling these tools on a test MCP instance does not make the portal traffic test data.

| Tool | Description | |------|-------------| | igw_management_console_search | Search correlated outgoing and incoming log rows by any ManagementConsole identifier, with paging and direction filters | | igw_management_console_payload | Retrieve a chunk of one raw sent or received payload by log ID and log type | | igw_management_console_logs_list | Discover incoming logs by a maximum seven-day date range and optional agent, operation, outsource-process, or insurance-company filters |

igw_management_console_search supports all eight portal modes: requestId, proposalId, referanceNo (the portal's original spelling), exceptionLogId, policyId, jobId, insuranceCompanyProposalId, and platformProposalId. Identifiers are strings so long, alphanumeric, or zero-prefixed values remain exact. includeInternalLogs: true maps to the portal's internal-log level; direction can be all, outgoing, or incoming.

Payload direction is explicit:

| logType | payloadSide: sent | payloadSide: received | |-----------|---------------------|-------------------------| | Outgoing | IGW → insurance company request | Insurance company → IGW response | | Incoming | IGW → client response | Client → IGW request |

Large payloads are returned in valid-JSON chunks. Continue with the returned nextOffset until hasMore is false; no common insurer schema is imposed on raw payloads.

Panel Catalog Tools (read-only)

The GatewayProUI panel (panel.insurapps.net) exposes many more catalogs. All of the tools below are read-only and require IGW_PANEL_USERNAME / IGW_PANEL_PASSWORD. The first group is pulled in full and filtered locally (cached ~10 min); the last three are server-side paged because the tables are too large to pull whole.

Full-fetch + local filter (cached):

| Tool | Panel page | ~Rows | |------|-----------|------:| | igw_product_branches_list | Ürün Branşları | 68 | | igw_related_products_list | İlişkili Ürün Yönetimi | 13 | | igw_guarantee_descriptions_list | Teminat Açıklamaları | 175 | | igw_guarantee_product_mappings_list | Ürün Eşleşmeleri | 2 652 | | igw_guarantee_freeword_dependencies_list | Serbest Metin Bağımlılıkları | 6 | | igw_provided_services_list | Kullanıma Açık Servisler | 421 | | igw_key_relations_list | KeyRelation | 2 211 | | igw_parameters_list | Parametre Yönetimi | 572 | | igw_insurance_companies_list | Sigorta Şirketleri (rich) | 89 | | igw_connection_groups_list | Şirket Bağlantı Grupları | 165 | | igw_outsource_processes_list | Outsource Process | 169 | | igw_agents_list | Acente Yönetimi | 2 795 | | igw_agent_connection_infos_list | Acente Bağlantı Bilgileri | 3 456 | | igw_dynamic_forms_list | DynamicForm | 598 |

Server-side paged (page / pageSize; filters narrow the fetched page only):

| Tool | Panel page | ~Rows | |------|-----------|------:| | igw_agent_connections_list | Acente Bağlantıları | 63 382 | | igw_users_list | Kullanıcı Yönetimi (PII) | 21 339 | | igw_action_logs_list | Action Logs | ~5 000 000 |

The panel's DataTables endpoints 500 on per-column server-side search and ignore global search, so filtering is done locally after fetching. For the three paged tools this means filters apply to the current page only — they do not scan the whole table.

Parameter / Cross / Dependency Tools (read-only)

Read-only walk of the panel's Parameter → Value → Cross → Dependency hierarchy plus the agent list (IGW_PANEL_USERNAME required, cached ~10 min):

| Tool | Purpose | |------|---------| | igw_parameter_get | One parameter (Id or name) with all of its values and the keys that use it | | igw_crosses_list | Crosses of a parameter or one value; company/product/agent-type/value filters, readable dependencies, and a warning on every 0 cross IUP agents can reach | | igw_cross_dependencies | Dependency rows of one cross with a readable expression, IUP-closed flag and 0 warning | | igw_key_dependencies | Dependency rows of one key (the Key screen's blue-icon table) | | igw_agents_search | Agent search with the full parent chain and whether the agent sits under InsurUp Parent (700) | | igw_values_for_context | For a company + product + context (default: an IUP agent under 700), which value is actually sent, which are unsupported (0), missing or undecided, and which condition eliminated each cross | | igw_compare_products | Same company, several products: per value, what each product sends in the context (Product -1 applies to all; names expand to every matching product) | | igw_value_trace | Key + the value seen in a quote log → the parameter value and cross it comes from, with its dependency and whether it is selected in the context | | igw_crosses_bulk_check | Company table vs IGW: OK / EKSIK / BELIRSIZ / KOD_YOK per row, plus FAZLA, FAZLA_ACIK (open via Product -1 or an unconditional cross) and UYARI_0, as an Excel-pasteable TSV |

Insurer codes are never guessed: statistic codes (e.g. Ak 608, ANK) map to IGW keys through codeMap, and insurer product/vehicle codes are translated through the crosses of productKey / vehicleKey. When several crosses pass for one value, product-specific beats Product -1 and conditional beats unconditional; the panel list does not expose Bağımlılık Sırası or Acenteye özel mi?, so that order is an approximation.

Read-only by design — no cross/dependency write operations exist.

Panel Credentials (optional)

The panel tools above read from the GatewayProUI admin panel (panel.insurapps.net) instead of the gateway API. Add these env vars to enable them:

| Variable | Description | |----------|-------------| | IGW_PANEL_BASE_URL | Panel URL (default https://panel.insurapps.net) | | IGW_PANEL_USERNAME | Panel login email | | IGW_PANEL_PASSWORD | Panel login password |

Without these the panel tools are simply not registered; everything else works as before.

ManagementConsole Credentials (optional)

Add these environment variables to enable the ManagementConsole tools:

| Variable | Description | |----------|-------------| | IGW_PORTAL_BASE_URL | Portal URL (default https://portal.insurapps.net) | | IGW_PORTAL_USERNAME | Portal login email | | IGW_PORTAL_PASSWORD | Portal login password | | IGW_PORTAL_USE_PANEL_CREDENTIALS | Set to true to explicitly reuse the complete panel credential pair for the portal |

Set the portal-specific credential pair, or explicitly opt in to reusing the complete IGW_PANEL_USERNAME / IGW_PANEL_PASSWORD pair with IGW_PORTAL_USE_PANEL_CREDENTIALS=true. A partial portal credential pair disables the tools instead of mixing credentials from two sources. Credentials stay in the MCP process environment and are never returned by the tools.

Example addition to any MCP server env block:

{
  "IGW_PORTAL_USERNAME": "your-portal-username",
  "IGW_PORTAL_PASSWORD": "your-portal-password"
}

Key Parameters for `igw_errors_list`

| Parameter | Description | |-----------|-------------| | BeginDate / EndDate | Date range (ISO 8601) | | ErrorQuery | Free text search within error messages | | SortColumn | Sort by: GroupCount, AgentName, LastErrorDate, InsuranceCompanyName, ProductName | | SortDescending | Sort direction (true = highest first) | | PageNumber / PageSize | Pagination (default page size: 10) | | AgentId | Filter by specific agent | | InsuranceCompanyId | Filter by insurance company | | ServiceOperationId | 1 = Teklif (Proposal), 2 = Poliçe (Policy) |

AnalyzeStatus Values

| Value | Status | |-------|--------| | 0 | Not Analysed (Analiz Edilmedi) | | 1 | In Progress (İnceleniyor) | | 2 | Solved (Çözüldü) | | 3 | Nothing To Do (Şirket Kuralı / Önlenemez Hata) | | 4 | User Mistake (Kullanıcı Hatası) | | 5 | Connection Error (Servis Bağlantı Hatası) | | 6 | Operation Timeout (Zaman Aşımı) |

Claude Code Skill (Optional)

Claude Code Skills, Claude Code'un belirli araclari daha etkili kullanmasini saglayan ogretilebilir talimat dosyalaridir. Bu repo, IGW hata yonetimi icin ozel bir skill dosyasi (SKILL.md) icerir. Skill yuklendiginde Claude Code; tool parametrelerini, is akislarini, hata durumlarini ve best practice'leri bilir — her seferinde aciklamaniza gerek kalmaz.

Not: Skill kurulumu MCP server kurulumundan bagimsizdir. MCP server'i yukledikten sonra opsiyonel olarak skill'i de ekleyebilirsiniz.

Kurulum

# Skill dosyasini Claude Code'a yukle
claude skill add --name igw-error-management --source-url https://raw.githubusercontent.com/yusufaltunbicak/igw-error-management-mcp/main/SKILL.md

Alternatif olarak, dosyayi manuel indirip yukleyebilirsiniz:

# SKILL.md'yi indir ve Claude Code skills dizinine kopyala
mkdir -p ~/.claude/skills/igw-error-management
curl -o ~/.claude/skills/igw-error-management/SKILL.md \
  https://raw.githubusercontent.com/yusufaltunbicak/igw-error-management-mcp/main/SKILL.md

License

MIT