Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OCI Load Balancer Log MCP Server show top 10 IPs from the last 7 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for querying and analyzing Oracle Cloud Infrastructure (OCI) Load Balancer custom logs. This server allows LLMs to directly search through traffic logs by country, IP, location, and perform aggregated traffic analytics.
Search by Country: Filter logs by country name or ISO country code.
Search by IP: Look up specific IP addresses or CIDR-style prefixes.
Geographic Search: Find traffic originating from specific latitude/longitude bounding boxes.
Traffic Analytics: Get top talkers, country distribution, and protocol statistics.
Zero Hardcoding: Fully configurable via environment variables.
Related MCP server: Kibana MCP Server
OCI CLI Configured: You must have a valid OCI configuration file (usually at ~/.oci/config).
Environment Variables: You need the OCIDs for your compartment, log group, and the specific custom log.
uvxYou can run the MCP server directly from GitHub without manual installation using uvx:
export OCI_COMPARTMENT_ID="ocid1.tenancy.oc1..xxxx"
export OCI_LOG_GROUP_ID="ocid1.loggroup.oc1.xxxx"
export OCI_LOG_ID="ocid1.log.oc1.xxxx"
uvx --from git+https://github.com/mamorett/oci_lb_log_custom_mcp.git oci-lb-logsAdd the following entry to your claude_desktop_config.json:
{
"mcpServers": {
"oci-lb-logs": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/mamorett/oci_lb_log_custom_mcp.git",
"oci-lb-logs"
],
"env": {
"OCI_COMPARTMENT_ID": "ocid1.tenancy.oc1..your_compartment_ocid",
"OCI_LOG_GROUP_ID": "ocid1.loggroup.oc1.your_region.your_log_group_ocid",
"OCI_LOG_ID": "ocid1.log.oc1.your_region.your_custom_log_ocid",
"OCI_CONFIG_PROFILE": "DEFAULT",
"OCI_CONFIG_FILE": "/absolute/path/to/your/.oci/config"
}
}
}
}list_unique_ipsList all unique IP addresses seen in the logs, deduplicated and sorted by request count. Optionally filter by country to get all IPs from a specific origin.
time_range (string): Time window to search (e.g., "24h", "7d"). Default: "24h".
limit (integer): Max raw log entries to scan. Default: 500.
country (string, optional): Filter by full country name (e.g., "Germany").
country_code (string, optional): Filter by ISO country code (e.g., "DE").
Returns a list of IPSummary objects: ip, request_count, country, country_code, city, isp, protocols.
get_top_ipsReturn the top N IP addresses ranked by request count over the given time range. Samples a large window of logs to find the noisiest sources.
time_range (string): Time window to analyze. Default: "24h".
top_n (integer): Number of top IPs to return. Default: 20.
sample_limit (integer): Max raw log entries to scan. Default: 5000.
Returns a list of IPSummary objects sorted by request_count descending.
get_ips_by_countryReturn unique IP addresses grouped by country, with per-country request totals and unique IP counts. Useful for a full breakdown of all traffic sources by origin.
time_range (string): Time window to analyze. Default: "24h".
limit (integer): Max raw log entries to scan. Default: 2000.
Returns a list of IPsByCountry objects sorted by total_requests descending.
Each entry contains: country, country_code, total_requests, unique_ip_count, and a full ips list of IPSummary.
search_logs_by_countrySearch raw log entries by country name or country code.
country (string, optional): Full country name (e.g., "United States").
country_code (string, optional): ISO country code (e.g., "US").
time_range (string): Time window to search. Default: "24h".
limit (integer): Maximum number of entries to return. Default: 100.
search_logs_by_ipSearch raw log entries by a specific IP address or an IP range prefix.
ip_address (string, optional): Exact IP address.
ip_range (string, optional): IP prefix (e.g., "192.168").
time_range (string): Time window to search. Default: "24h".
limit (integer): Maximum number of entries to return. Default: 100.
search_logs_by_locationSearch raw log entries within a geographic bounding box.
lat_min, lat_max, lon_min, lon_max (float): Bounding box coordinates.
time_range (string): Time window to search. Default: "24h".
limit (integer): Maximum number of entries to return. Default: 100.
get_traffic_analyticsGet aggregated traffic statistics (counts only, no IPs). Use the IP tools above if you need actual addresses.
group_by (string): Field to aggregate by ("country", "city", "isp", or "protocol"). Default: "country".
time_range (string): Time window to analyze. Default: "24h".
limit (integer): Number of raw log entries to sample. Default: 1000.
Variable | Description | Default |
| Required. OCID of the OCI Compartment. | N/A |
| Required. OCID of the OCI Log Group. | N/A |
| Required. OCID of the OCI Custom Log. | N/A |
| Profile name in your OCI config file. |
|
| Path to your OCI config file. |
|
MIT
Return unique IP addresses grouped by country, with per-country totals. Useful for understanding which countries have the most unique sources.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| time_range | No | 24h |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the grouping and totals behavior, which is useful. However, it does not mention whether the operation is read-only, how time_range affects data, or any limitations. The description is not misleading but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences that front-load the core action and follow with a use case. Every word contributes value; no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema exists, so return values are not the issue. However, with no parameter semantics and no annotations, the description is insufficient for correct invocation. The tool has two optional parameters whose behavior is unexplained, and there is no guidance on how they interact with the grouping.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'limit' or 'time_range' parameters. The agent is left to infer their meaning from parameter names and defaults, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Return unique IP addresses grouped by country') and the per-country totals. It distinguishes itself from sibling tools like search_logs_by_* which filter logs, and list_unique_ips which likely returns ungrouped IPs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a clear use case: 'Useful for understanding which countries have the most unique sources.' This gives context for when to use the tool. However, it does not explicitly mention when not to use it or suggest alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the top N IP addresses ranked by request count over the given time range.
| Name | Required | Description | Default |
|---|---|---|---|
| top_n | No | ||
| time_range | No | 24h | |
| sample_limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the basic output and does not mention limitations like how sample_limit affects results, whether ranking is exact or approximate, or any performance or caching behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the core function without filler. It is efficiently structured and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too minimal to be complete for an analytics tool. It omits the role of sample_limit, any caveats about how request counts are computed, and does not clarify when this tool is preferable over sibling tools. While the output schema likely covers return values, other context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate. It explains top_n and time_range indirectly ('top N IP addresses', 'given time range'), but completely omits sample_limit. This leaves a significant parameter unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns the top N IP addresses ranked by request count over a time range, which is a specific verb+resource+scope. This distinguishes it from sibling tools like search_logs_by_ip or list_unique_ips.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as list_unique_ips or search_logs_by_ip. It lacks exclusions, prerequisites, or context that would help an agent choose it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get aggregated traffic statistics from OCI Load Balancer logs.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| group_by | No | country | |
| time_range | No | 24h |
| Name | Required | Description |
|---|---|---|
| top_isps | Yes | |
| top_items | Yes | |
| time_range | Yes | |
| unique_ips | Yes | |
| total_requests | Yes | |
| unique_countries | Yes | |
| protocol_distribution | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It only states that it gets statistics, but nothing about pagination, rate limits, required permissions, grouping behavior, or how results are ordered. The description adds no behavioral context beyond the basic read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words. It is front-loaded with the key action and resource, making it easy to parse. However, the extreme brevity borders on under-specification, so it is not a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, sibling tools, and no annotations, the description is insufficient for an agent to invoke it correctly. It does not explain when to use it, what the parameters mean, or what type of aggregated output to expect, despite an output schema existing. The minimal content leaves significant gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema reference coverage is 0%, meaning the description provides no explanation for parameters like limit, group_by, or time_range. While defaults (1000, 'country', '24h') hint at meaning, the agent cannot determine valid values for group_by or the effect of limit and time_range without external knowledge. The description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get aggregated traffic statistics from OCI Load Balancer logs' specifies an action (get) and resource (OCI Load Balancer logs), but 'aggregated traffic statistics' is vague and does not clearly differentiate from sibling tools like get_top_ips or get_ips_by_country. It lacks specificity about what dimensions or metrics are included.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus the sibling search and IP analysis tools. No exclusions, prerequisites, or alternative recommendations are mentioned, leaving the agent to infer usage solely from the tool's name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all unique IP addresses seen in the logs with their request count, country, city, ISP and protocols. Optionally filter by country name or country code.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| country | No | ||
| time_range | No | 24h | |
| country_code | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source of behavioral context. It discloses the output fields and optional country filters but omits critical behaviors such as the default limit of 500 (contradicting 'all' IPs), the effect of time_range, and how country vs country_code filtering interacts. No side effects or permissions are mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the core function, and adds the filter option without unnecessary words. It is highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 4 optional parameters, an output schema, and no annotations, but the description only covers the basic output and country filters. It fails to mention time_range and limit behavior, making it incomplete for users needing full operational understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no descriptions (0% coverage), so the description must explain all parameters. It only clarifies the 'country' and 'country_code' filters, leaving 'limit' and 'time_range' unexplained. This is a significant gap for a tool with default values affecting behavior.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('unique IP addresses'), with details on returned fields (request count, country, city, ISP, protocols). It does not explicitly differentiate from sibling tools like get_ips_by_country or get_top_ips, despite overlapping filter options.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus the sibling tools (e.g., search_logs_by_ip, get_ips_by_country). It does not mention exclusions or prerequisites such as required time range or how to choose between country and country_code.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search OCI Load Balancer logs by country or country code.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| country | No | ||
| time_range | No | 24h | |
| country_code | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states that logs are searched, without mentioning whether results are raw logs or aggregated statistics, how time_range affects results, pagination, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with no filler words. It gets straight to the point and is appropriately concise for a tool with a clear primary function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool having 4 optional parameters, an output schema, and no annotations, the description is only one sentence long. It fails to mention half the parameters, any default behaviors, or usage context, making it incomplete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for the 4 parameters. It only mentions 'country' and 'country_code', omitting 'limit' and 'time_range' entirely, and does not clarify the format or relationship between these parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Search'), the resource ('OCI Load Balancer logs'), and the filtering dimension ('by country or country code'). This clearly distinguishes it from sibling tools like search_logs_by_ip and search_logs_by_location, which filter by different criteria.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives such as search_logs_by_ip or search_logs_by_location. The description only states what the tool does, leaving the agent to infer suitability from the name and filter criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search OCI Load Balancer logs by IP address or IP range (prefix).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| ip_range | No | ||
| ip_address | No | ||
| time_range | No | 24h |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavioral traits. It only states the search action and filter fields, omitting how the two IP filters interact, whether it supports CIDR, or any rate limits or result ordering. This leaves significant ambiguity for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary detail. It efficiently conveys the core purpose without waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is succinct but incomplete for a tool with 4 optional parameters and no annotations. It does not specify the relationship between ip_address and ip_range, the format of time_range, or any behavioral details beyond the search. The presence of an output schema mitigates the need to describe return values, but the tool's usage context is only partially covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies that ip_range is a 'prefix' and that the tool searches by IP address or range, which adds meaning beyond the parameter names. However, it does not explain the limit or time_range parameters, leaving gaps in full parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches OCI Load Balancer logs by IP address or IP range, with a specific verb (Search) and resource (OCI Load Balancer logs). This distinguishes it from sibling tools that search by country or location.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies its usage: use when you need to search logs by IP address or prefix. However, it does not explicitly mention when not to use this tool or name alternative sibling tools, so clear context is provided but exclusions are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search OCI Load Balancer logs within geographic bounds.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| lat_max | Yes | ||
| lat_min | Yes | ||
| lon_max | Yes | ||
| lon_min | Yes | ||
| time_range | No | 24h |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must convey behavioral traits. It implies a read-only search operation, but there is no mention of what the output contains, whether results are paginated or limited, or any side effects or required permissions. The description adds minimal behavioral insight beyond the action itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. However, it is under-specified, lacking necessary context and behavioral details. It earns a middle score because it is efficient but incomplete for a tool with 6 parameters and a search function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, no annotations, and only a one-sentence description. It does not provide usage context, alternatives, or behavior beyond the basic action. The existence of an output schema helps, but the description itself is insufficient for an agent to understand when and how to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the parameters have no explanatory descriptions. The tool description does not compensate by explaining what parameters like lat_min, lon_max, limit, or time_range mean or how they interact. The parameter names are self-explanatory to an extent, but the description provides no added semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches OCI Load Balancer logs within geographic bounds, using a specific verb and resource. It distinguishes itself from siblings like search_logs_by_country and search_logs_by_ip by the geographic bounds concept, though it does not explicitly name alternatives. This is clear but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention how 'search_logs_by_country' or 'search_logs_by_ip' might be more appropriate for certain scenarios, nor does it suggest prerequisites or typical use cases. There is no explicit exclusion or when-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_ips_by_countryget_top_ipsget_traffic_analyticslist_unique_ipssearch_logs_by_countrysearch_logs_by_ipsearch_logs_by_locationScored across 7 tools
Each tool has a clearly distinct purpose: searching logs by different criteria (country, IP, location), getting aggregate analytics, listing unique IPs, top IPs, and IPs grouped by country. Even overlapping tools like list_unique_ips and get_top_ips differ in scope (all vs. top N) and output details.
All tool names follow a consistent verb_noun pattern with lowercase and underscores: search_logs_by_*, get_traffic_analytics, list_unique_ips, get_top_ips, get_ips_by_country. The verbs (search, get, list) are clear and used consistently.
Seven tools is an appropriate size for a log analysis server. Each tool provides a distinct function without being redundant, and the count is neither too sparse nor overwhelming for the domain.
The tool set covers common log search and analytics operations: filtering by country/IP/location, aggregate traffic stats, and IP-focused queries. Minor gaps exist such as no explicit search by status code or user-agent, but the core workflows for analyzing load balancer logs are well covered.
Ingest and search LogsLoom logs from coding agents.
LLM Observability & Orchestration Agent
LLM Orchestration Observability Agent
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
