Model Context Protocol (MCP) Server & Consolidated Tool Surface¶

Arodonata v2 includes a production-hardened Streamable-HTTP Model Context Protocol (MCP) server (arodonata[mcp]) that can run either as a standalone CLI (arodonata-mcp) or embedded as an ASGI sub-application (create_mcp_server, create_asgi_app) inside a FastAPI or Starlette host.

1. Consolidated Tool Surface Optimization (v2 Architecture)¶

In Arodonata v2, the MCP tool surface was redesigned and consolidated into 13 cache-aligned core tools (plus 5 opt-in tamper-proof CPCRUD tools when ARODONATA_MCP_CPCRUD=true).

Why We Consolidated the MCP Tools¶

Early MCP servers often expose dozens of 1-to-1 wrappers over raw Check Point API endpoints (show-hosts, show-networks, show-access-layers, show-packages, etc.). That causes three major problems for LLM agents:

1. Tool Selection Ambiguity & Context Bloat: Too many overlapping tool schemas consume thousands of prompt tokens and cause models to pick the wrong endpoint.
2. Unbounded Output Overflow: Raw Check Point API calls or unanchored substring searches on large enterprise domains return thousands of objects and blow up the LLM context window.
3. N+1 API Round-Trips: Answering questions like "How many hosts and networks exist per domain?" or "What packages and layers exist in Domain4?" previously required dozens of sequential tool calls.

Arodonata v2 solves all three problems with progressive disclosure, multi-table unified lookup, SQL-free cached aggregation, and hybrid cache/live execution:

2. Deep-Dive into Key Tool Behaviors¶

2.1 Three-Tier Matching in show_object¶

When an LLM calls show_object(uid_or_name=..., mgmt_name=..., domain=..., obj_type=None, limit=20, offset=0):

1. Tier 1 — Exact Match (match_type="exact"):
2. If uid_or_name contains no * or ? wildcards and matches an exact UID or case-insensitive name in arodonata_objects, arodonata_services, arodonata_assets, or arodonata_rulebase_layer / arodonata_rulebase_package_layer, show_object returns that single entity with full details (including gateway interfaces, network_security_blades, member_uids, and virtual_system_uids).
3. Tier 2 — Strict Explicit Wildcard (match_type="wildcard"):
4. If uid_or_name contains * or ? (e.g. "web-*-prod" or "*.example.com"), it evaluates anchored fnmatchcase strictly against the pattern without adding implicit leading/trailing wildcards. If total == 1, it returns the full object; if total > 1, it returns a paginated candidate slice (limit default 20, max 500).
5. Tier 3 — Paginated Substring Candidate Fallback (match_type="substring_candidates"):
6. If uid_or_name has no wildcard and no exact match exists in cache, instead of failing with a bare "not found" error or dumping thousands of objects, show_object searches for case-insensitive substring matches across cached names and returns up to limit (20) compact candidate summaries (uid, name, type, domain_name, summary) with from, to, and total so the LLM can pick the exact object on the next turn.

2.2 Progressive Disclosure via query_objects & show_rulebase¶

• Schema & Inventory Discovery (query_objects(aggregate="describe")):
• Calling query_objects(mgmt_name="mdsm-prod", aggregate="describe") returns all available domains, per-type object/service/asset counts, and the exact list of filterable and groupable fields (domain_name, type, original_domain, color, protocol, port, etc.).
• Cross-Domain Counting (query_objects(aggregate="count", group_by=["domain_name", "type"])):
• Counts objects and services across all domains in a single SQL query, supporting scope_origin="local" (domain-owned only) vs "global" (original_domain == "Global").
• Guided Rulebase Discovery (show_rulebase):
• Calling show_rulebase(mgmt_name="mdsm-prod", domain="Domain4") without package or layer (or with a misspelled layer name) automatically returns "mode": "catalog" containing all cached packages (arodonata_rulebase_package_layer) and layers (arodonata_rulebase_layer, including inline layers and implicit_cleanup_action).

2.3 Pre-Login Domain Validation & Actionable ToolFailure¶

Every domain-scoped MCP tool validates domain against the cached arodonata_domains table (triggering a single domain-list refresh on cache miss) before attempting any Check Point login. If an invalid domain name is passed, the tool returns an actionable error listing the valid domain names on that server instead of triggering unnecessary failed logins.

3. Running & Embedding the MCP Server¶

3.1 Standalone CLI (arodonata-mcp)¶

# Start with static bearer token authentication (default)
export ARODONATA_MCP_AUTH_MODE=static
export ARODONATA_MCP_TOKEN_VARS=TEAM_ALPHA_MCP_TOKEN
export TEAM_ALPHA_MCP_TOKEN="a-very-long-random-secret-token-at-least-32-chars"

uv run arodonata-mcp --host 127.0.0.1 --port 8000 --path /mcp

3.2 Embedding in FastAPI / Starlette (create_mcp_server & create_asgi_app)¶

See examples/12_mcp_embedded.py for a complete runnable example mounting Arodonata's MCP server inside a FastAPI application with custom host-level tools:

from contextlib import asynccontextmanager
from fastapi import FastAPI
from arodonata import ArodonataClient, ArodonataMCPSettings, create_asgi_app, create_mcp_server

client = ArodonataClient()
mcp_settings = ArodonataMCPSettings(auth_mode="host", path="/mcp")
mcp_server = create_mcp_server(client, mcp_settings=mcp_settings)
mcp_asgi = create_asgi_app(client, mcp_settings=mcp_settings, server=mcp_server)


@asynccontextmanager
async def lifespan(app: FastAPI):
    async with client, mcp_asgi.lifespan(app):
        yield


app = FastAPI(lifespan=lifespan)
app.mount("/mcp", mcp_asgi)

4. MCP Configuration & Security Reference (ArodonataMCPSettings)¶