A
licenseNot graded
qualityD
maintenanceOcean container shipping intelligence for AI agents — D\&D tariffs, freight rates, vessel schedules, port congestion, inland haulage across 6 major carriers. 24 MCP tools.
MIT
io.github.belegante-byte/aetherx-mcp
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., "@io.github.belegante-byte/aetherx-mcpWhat's the congestion risk at Santos right now?"
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.
aetherx-mcp
MCP server for the Aether-X Port Congestion Oracle — gives any MCP-compatible agent (Claude Desktop, Cursor, VS Code, custom LLM agents) predictive port congestion signals for global trade and quantitative finance.
Install
pip install aetherx-mcp
# or run without installing (recommended for MCP clients):
uvx aetherx-mcpRelated MCP server: mcp-imf-portwatch
Configure your MCP client
Claude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"aetherx-oracle": {
"command": "uvx",
"args": ["aetherx-mcp"],
"env": { "RAPIDAPI_KEY": "SUA_RAPIDAPI_KEY" }
}
}
}Cursor (~/.cursor/mcp.json)
{
"mcpServers": {
"aetherx-oracle": {
"command": "uvx",
"args": ["aetherx-mcp"],
"env": { "RAPIDAPI_KEY": "SUA_RAPIDAPI_KEY" }
}
}
}Tools
Tool | Arguments | Returns |
|
| Congestion score, ETA delay, waiting vessels, freight volatility |
|
| Same, for a whole portfolio, fetched in parallel |
| — | The 15 pre-seeded ports (id, name, country) |
Every response is a typed payload:
{
"port_id": "BRSSZ",
"port_name": "Santos",
"country": "Brasil",
"congestion_score": 0.78,
"eta_delay_days": 1.6,
"waiting_vessels": 12,
"freight_volatility_index": 0.42,
"updated_at": "2026-09-17 15:46:53"
}Configuration
Variable | Default | Description |
| — | When set, requests are routed through the RapidAPI gateway (metered billing) |
|
| RapidAPI host |
|
| Direct API base URL |
Without RAPIDAPI_KEY, the server calls the public production API directly.
Example agent prompts
"What's the congestion risk at Santos right now?"
"Rank these ports by congestion: BRSSZ, CNSHA, NLRTM, USLAX."
"Which of my Asian ports has the highest freight volatility index?"
License
MIT — see LICENSE. The signals are provided "AS IS" and do not constitute investment advice. See the Terms of Service.
Available Tools
3 toolsget_port_riskAInspect
Return the predictive congestion signal for a single port.
Args: port_id: UN/LOCODE of the port, e.g. "BRSSZ" (Santos), "CNSHA" (Shanghai).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| port_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A3.8/5.0
Behavior2/5
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 says 'Return', implying a read operation, but it does not state side effects, response behavior, or limitations. This is minimal transparency beyond the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the purpose and follows with a compact args block. Every sentence earns its place, with no filler or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read tool, the description covers purpose and parameter format, and the output schema can handle return structure. It does not explicitly route to get_ports_risk for multi-port queries, but the singular wording and sibling names provide enough context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 defines port_id as a UN/LOCODE and provides two concrete examples (Santos and Shanghai), giving format and usage context that the bare schema field name 'Port Id' lacks.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return'), a clear resource ('predictive congestion signal'), and a clear scope ('single port'). The singular/plural contrast with the sibling get_ports_risk helps an agent distinguish the tools without opening schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is only implied by 'single port', which hints that this tool is for one port rather than a bulk query. However, it never explicitly names alternatives like get_ports_risk or states when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_ports_riskAInspect
Return congestion signals for several ports in parallel.
Args: port_ids: list of UN/LOCODEs, e.g. ["BRSSZ", "CNSHA", "NLRTM"].
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| port_ids | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It usefully discloses parallel execution and that it returns congestion signals, but says nothing about error handling, rate limits, or read-only guarantees beyond the word 'return'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with no filler. The action and resource are front-loaded, and the parameter documentation directly follows with an example. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with an output schema and clear sibling context, this is nearly complete. The example UN/LOCODEs and parallel behavior make the call contract understandable. It does not explicitly point to list_supported_ports for valid codes, but that is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 does by defining port_ids as UN/LOCODEs and providing concrete examples (BRSSZ, CNSHA, NLRTM), adding meaning beyond the bare array schema. It stops short of specifying validation rules or length limits.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns congestion signals for multiple ports, using a specific verb and resource. The plural 'ports' and 'in parallel' distinguish it from the singular sibling get_port_risk.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'several ports in parallel' gives clear context that this tool is for batch/multi-port queries, implying the singular sibling is for one port. However, it does not explicitly name alternatives or state when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_supported_portsAInspect
List the 15 ports pre-seeded in the oracle (id, name, country).
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.1/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the exact fixed count (15), the static 'pre-seeded' nature, and the fields returned, which is transparent for a read-only list. Minor omissions like error conditions are acceptable for a zero-parameter tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no wasted words. It conveys the action, resource, quantity, and output fields efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless listing tool with an output schema, the description provides everything an agent needs: what is listed, how many items, and their fields. No meaningful invocation context is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. The description adds no parameter complexity because none exists, and schema coverage is effectively complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('List'), a specific resource ('ports pre-seeded in the oracle'), and the returned fields ('id, name, country'). It is immediately distinct from the sibling risk-focused tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no indication of when to use this tool versus get_port_risk or get_ports_risk, nor any exclusions. An agent must infer that this is the simple enumeration tool and that risk data belongs to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v0.1.1- First observed
get_port_risk - First observed
get_ports_risk - First observed
list_supported_ports
TDQS
A4.1/5.0
Scored across 3 tools
Disambiguation4/5
The two risk tools differ only in cardinality (single vs. batch), but the names and descriptions clearly indicate which to use. list_supported_ports is entirely distinct. Minor potential confusion when querying one port, but explicit pluralization disambiguates.
Naming Consistency5/5
All tools follow a consistent verb_noun snake_case pattern: get_ for queries, list_ for enumeration. Pluralization is used appropriately (port vs. ports), making the naming predictable and readable.
Tool Count4/5
Three tools is minimal but appropriate for a read-only oracle with a fixed dataset. It covers listing, single query, and batch query without unnecessary bloat. Slightly thin, but well-scoped for the domain.
Completeness5/5
The tool set fully covers the domain: you can discover supported ports via list, query one port, or query many in parallel. There are no obvious dead ends or missing operations for the stated purpose of predictive congestion signals.
Maintenance
ActivityMaintained
ResponsivenessNo issues
Related MCP Connectors
Ocean & multimodal freight intelligence: rates, landed cost, transit, customs, risk, ship decisions
IMF PortWatch MCP — global maritime trade & chokepoint signals (free, no auth)
Intelligence subscription protocol for AI agents. Scored, filtered AI intelligence signals via MCP.
Read-only MCP access to DSGHT.ai published foresight and country-grounded claim resolution.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides global maritime trade and chokepoint signals from IMF PortWatch, free and without authentication.5 npmMIT
- FlicenseAqualityBmaintenanceMCP server that exposes tools for monitoring supply chain disruptions, including vessel positions, port weather, congestion, and news. Includes an AI agent that synthesizes these sources to assess route risks.5-
- FlicenseNot gradedqualityCmaintenanceEnables querying maritime vessel data via MCP tools and resources, including vessel search, port proximity, and vessel details lookups.-