Agent integration

MCP Guide

The MCP endpoint exposes GiuliaAPI simulation operations as tools for MCP-capable clients. It uses the same tool argument schemas documented in the tool reference.

Endpoint

Configure an HTTP MCP client with the URL below and an X-API-Key header. The client must support this deployment’s JSON-RPC transport and custom authentication headers.

Connect MCP clients to:

https://www.giuliaAPI.com/mcp

The endpoint uses JSON-RPC over the configured MCP transport. Clients normally call initialize, send notifications/initialized, then tools/list, then tools/call.

Preserve the Mcp-Session-Id returned by initialization on subsequent requests when supplied by the server. Check the negotiated protocol version and transport support in your client.

Workspace Binding

Workspace identity is managed outside tool arguments. Depending on the client and deployment, GiuliaAPI can bind MCP calls through transport metadata, request headers, or server-side simulation mapping.

Do not put workspace IDs in tool arguments. The tools only need simulation-level arguments such as sim_id, KPI names, parameter names, and filter lists.

Tool Flow

Call create_simulation or load_scenario.
Optionally inspect or change engineering, UE, or carrier-management settings before running.
Call run_simulation.
Call get_aggregated_results, get_results, or get_ue_parameters.

When comparing variants, create or clone separate simulations and keep track of each returned sim_id.

Tool Categories

Category	Tools
Simulation lifecycle	`create_simulation`, `load_scenario`, `list_simulations`, `clone_simulation`, `delete_simulation`
Parameters	`get_engineering_parameters`, `set_engineering_parameter`, `get_ue_parameters`, `set_ue_parameter`
Carrier management	`get_carrier_management_config`, `set_carrier_management_config`
Execution	`run_simulation`
Results	`get_aggregated_results`, `get_results`, `get_available_results`

Example Tool Call Arguments

{
  "scenario_model": "ITU_R_M2135_UMa",
  "ue_distribution": "uniform",
  "link_direction": "downlink",
  "number_of_episodes": 1
}

{
  "sim_id": "ITU_R_M2135_UMa_uniform_abc123",
  "kpis": ["ue_throughput_Mbps"],
  "group_by": "all",
  "metrics": ["mean", "p10"]
}