MCP Admon Server — API Reference
All tools and resources below belong to the current implementation. The server is designed to grow: new modules (shipments, billing, companies, etc.) will add their own tools and resources to this registry without touching the existing ones.
Tools — tickets module
All tools are exposed via the MCP protocol. They are not HTTP endpoints — they are invoked by AI agents through the MCP transport.
get_ticket_types
Returns ticket type information from the TicketRulesCache. Operates in two modes:
Mode 1 — no arguments: returns a summary of all available (non-blocked) ticket types.
| Field | Description |
|---|---|
id | Ticket type ID |
name | Snake-case type name (e.g. overweight) |
description | Human-readable label |
use_case | When to use this type (from mcp_context) |
requires_guide | Whether a tracking number is needed |
Mode 2 — with type_id or type_name: returns full requirements for a specific type.
| Field | Description |
|---|---|
required_variables | List of { name, type } fields the agent must collect |
optional_variables | List of { name, type } fields to collect if mentioned |
requires_guide | Whether a tracking number is required |
amount_limit_mxn | Amount ceiling enforced at CLAIM_IN_REVIEW transition (if applicable) |
requires_credit_id | Whether a credit reference is required |
agent_notes | Free-form instructions the agent must follow without exception |
Types without mcp_context or with is_blocked: true are excluded from both modes.
Backend call: none (served from TicketRulesCache)
create_ticket
Creates a new ticket for a company. Before calling this tool, agents must call get_ticket_types to obtain required fields and agent notes. Validates conditions.avaliable_status and conditions.validations from catalog_ticket_types.rules. Uploads any provided files (base64) automatically after creation.
Required inputs: company_id, type, comments
Optional inputs: shipment_id, tracking_number, amount, assigned_to_id, files[] (base64), and any type-specific variables returned by get_ticket_types
Blocking logic: rejects immediately if the ticket type has mcp_context.is_blocked: true or has no mcp_context at all.
Backend call: POST /companies/tickets
update_ticket
Updates an existing ticket's status, comment, or attached files — all in a single call. status_id is optional; omitting it preserves the current status.
Required inputs: ticket_id
Optional inputs: status_id, comment, assigned_to_id, reason_decline, new_ticket_type_id, company_id (required when files are provided), files[] (base64)
Amount validation: when status_id = 10 (CLAIM_IN_REVIEW), the tool fetches the current ticket to read ticket_type_id and ticket_variables.amount, then checks amount against mcp_context.amount_limit_mxn. Rejects with McpError if the limit is exceeded.
Comment rules:
| Status | Comment |
|---|---|
| ACCEPTED (2), DECLINED (3), COMPLETE (7), REJECTED (8), CLAIM_IN_REVIEW (10) | Required |
| FOLLOW_UP (5), IN_REVIEW (6), IN_ANALYSIS (9), INCOMPLETE (4), PENDING (1) | Optional |
Backend calls: GET /companies/tickets/{ticket_id} (only when transitioning to CLAIM_IN_REVIEW), PUT /companies/tickets/{ticket_id}
get_ticket
Retrieves the full detail of a single ticket. Enriches ticket_variables keys with explicit unit names (e.g. days → term_in_days) to prevent AI misinterpretation.
Required inputs: ticket_id
Backend call: GET /companies/tickets/{ticket_id}
list_tickets
Lists tickets with optional filters. Defaults: start=0, length=10.
| Filter | Type | Description |
|---|---|---|
company_id | number | Scope to a specific company |
ticket_id | number | Find a specific ticket |
tracking_number | string | Find tickets by guide number (use to check duplicates) |
ticket_type | string | Filter by type name |
ticket_status | string | Filter by status name |
carrier | string | Filter by carrier name |
shipment_type | 1|2|3 | 1=Paquete, 2=LTL, 3=FTL |
international | 0|1|2 | 0=Nacional, 1=Internacional, 2=Importación |
sla | 0|1|2 | 0=On time, 1=At risk, 2=Overdue |
created_start_date | YYYY-MM-DD | Created on or after |
created_end_date | YYYY-MM-DD | Created on or before |
start | number | Pagination offset |
length | number | Page size |
Backend call: GET /companies/tickets
Resources — shared
tickets://statuses
Returns all ticket statuses with metadata (id, label, requires_comment). Served from local constants — no backend call.
shipments://statuses
Returns all shipment statuses (id, name). Used to show human-readable names in avaliable_status validation errors. Loaded from GET /catalog/shipment-statuses and cached (TTL 12 hours).
Note: The
tickets://typesresource was removed. Its functionality is now covered by theget_ticket_typestool, which agents call proactively at the start of the ticket creation workflow.
Backend Endpoints — infrastructure
POST /mcp/activity-log
Inserts an activity log record into mcp_activity_log.
Auth: token_admin_or_bot_ai
Request body:
| Field | Type | Required | Description |
|---|---|---|---|
tool_name | string (max 100) | ✅ | Name of the MCP tool called |
mcp_name | string (max 100) | ❌ | Identifier of the MCP server |
user_id | integer | ❌ | Defaults to 0 (SYSTEM_USER_ID) |
input_params | object | ❌ | Tool input parameters |
status | success|error|denied | ✅ | Outcome of the tool call |
error_message | string | ❌ | Error message if status=error |
execution_time_ms | integer | ❌ | Duration in milliseconds |
Response: { success: true } with HTTP 201
Environment Variables
| Variable | Required | Description |
|---|---|---|
BACKEND_URL | ✅ | Base URL of the Hapi.js backend (e.g. http://127.0.0.1:3002) |
BACKEND_BOT_AI_TOKEN | ✅ | Bot token for backend auth (token_admin_or_bot_ai) |
MCP_API_KEY | ✅ (HTTP mode) | API key clients must send in X-API-Key header |
PORT | ❌ | HTTP server port (default: 3100) |
MCP_TRANSPORT | ❌ | Set to stdio for Claude Desktop; omit for HTTP (default) |