Package com.eqixiac.equinix.mcp.server

package com.eqixiac.equinix.mcp.server
The embedded Equinix Intelligence MCP Server - a community Model Context Protocol server, not affiliated with or endorsed by Equinix, and separate from Equinix's official Fabric MCP server. That server is in Public Preview at https://mcp.equinix.com/fabric: it covers Fabric and Network Edge, signs users in with OAuth 2.1 (Customer Portal login), grants one of the viewer, operator or manager permission levels at consent, and offers create and update tools but no delete tools.

An MCP host (Claude Desktop, Cursor, VS Code, ...) launches EquinixMcpServerMain as a subprocess and speaks newline-delimited JSON-RPC over stdio - the only transport this server offers. Every tool executes through this SDK's typed domain clients and design engines under the operator's own client-credentials (EQUINIX_ACCESS_KEY / EQUINIX_SECRET_KEY); there is no browser consent flow and no separate authorization server.

The design loop. One input, the DesignSpec, drives every design tool (design toolset): design_spec_template and design_validate_spec (issues with JSON paths and fixes, the normalised spec, its fingerprint), design_optimize (recommendation, Pareto frontier, sensitivity, findings, cost with sources and currency conversions, the spec with the used rates pinned), design_analyze_resilience (N-1/N-2, single points of failure, blast radius, remediation, Mermaid graph), design_growth_and_terms, design_estimate_tco, design_compare_cloud_egress, design_analyze_peering, and the plan lifecycle design_plan_deployment / design_get_plan / design_plan_drift / design_export_terraform, and design_decision_record (the whole case for a design as one ADR-style document). Results carry the spec fingerprint and a provenance block; optimization results and plans are kept in the process's DesignStore so later calls can pass a spec_fingerprint or plan_id. The estate toolset adds design_analyze_estate, which reads the customer's own inventory and always requires explicit project ids. With the design toolset the server also serves MCP resources (the DesignSpec JSON Schema, a starter spec, stored plans) and prompts (DesignResources).

Design rules the tool catalog follows:

  • every tool embeds engine logic (optimizer, resilience simulation, wizard, growth, TCO and savings, cloud-to-cloud path comparison, peering, latency, estate analysis) or cross-domain reach (portal, Network Edge, IBX SmartView); none is a 1:1 mirror of a REST endpoint;
  • domain-prefixed snake_case names (design_*, portal_*, ne_*, ibx_*);
  • read-only: no delete tools, and mutations are out of scope for this catalog - they arrive only through the Safe Mutation Broker's dry-run-first two-phase tools, registered via the same ToolRegistration seam. The confirm phase asks the client for the user's approval through an MCP form elicitation (ServerContext.confirmWithHuman(String)) and executes only on an accept; a client without elicitation support is reported as unsupported_by_client;
  • Beta: design_compare_cloud_to_cloud and design_list_multicloud_environments cover native provider-to-provider multicloud links from dated reference data bundled with the SDK. The server calls no cloud-provider control-plane API and never creates such a link; a figure with no citable source is null with a reason, never zero;
  • results are structured JSON sized for a model's context: summaries by default, more with detail=standard|full or by id, and every capped list says how many entries were omitted; a tool call never hangs: live pricing lookups share one per-call time budget and degrade gracefully to dated reference figures;
  • text from remote systems (Equinix API fields and errors, PeeringDB names, pricing errors) is sanitised, bounded and listed under untrusted_data (UntrustedText);
  • a client notifications/cancelled stops a tool call at its next safe point (CancellationSignal); long read-only engine runs (optimization, resilience, estate) are abandoned at once.

Extension seam: build a ToolRegistration (name, JSON schema, annotations, ToolHandler) and pass it to EquinixMcpServer.builder().additionalTools(...); the handler receives the parsed argument JSON and the shared ServerContext of lazily-built SDK facades.

  • Class
    Description
    CancellationSignal
    The cancellation state of one MCP tool call.
    ClaudeDesktopConfigMerger
    Registers this server in a Claude Desktop claude_desktop_config.json by merging into the mcpServers.equinix entry.
    DesignStore
    The design tools' single in-memory store: deployment plans keyed by their plan_id and optimization results keyed by the fingerprint of the spec they were run for, so the tools can be chained (design_optimize then design_plan_deployment, design_get_plan, design_plan_drift, design_export_terraform) without repeating work.
    DesignStore.Entry<T>
    A stored entry.
    DesignStore.Kind
    What a store entry holds.
    DesignStore.Lookup<T>
    The outcome of a lookup.
    DesignStore.Put
    The outcome of a store.
    DesignStore.Status
    How a lookup resolved.
    EquinixMcpServer
    The embedded Equinix Intelligence MCP Server - a community server, not affiliated with Equinix and separate from Equinix's official Fabric MCP server (Public Preview at https://mcp.equinix.com/fabric).
    EquinixMcpServer.Builder
    Builder for EquinixMcpServer.
    EquinixMcpServerMain
    Launches the embedded Equinix Intelligence MCP Server over stdio - the entry point an MCP host (Claude Desktop, Cursor, VS Code, ...) configures as a command.
    HumanConfirmation
    The result of asking the person at the MCP client to approve one action through a form elicitation (ServerContext.confirmWithHuman(String), delivered by a HumanConfirmer).
    HumanConfirmation.Status
    What the client reported for one confirmation prompt.
    HumanConfirmer
    How the server asks the person at the MCP client to approve one action.
    PricingBudget
    The live-pricing time budget of one tool call: ServerContext.pricingTimeoutMillis() milliseconds, shared by every pricing lookup the call makes (cloud provider price lists and the Equinix rate card alike).
    ServerContext
    The shared state a ToolHandler executes against: the lazily-built SDK facades (Fabric + design engines, Customer Portal, Network Edge, IBX SmartView), the environment, the JSON mapper, and the single-process DesignStore of plans and optimization results.
    ServerContext.Builder
    Builder for ServerContext.
    ServerContext.ProviderRateCardFactory
    Creates the live pricing adapter for a provider.
    ToolCallCancelledException
    Thrown by a handler that stops because the client cancelled its tool call with notifications/cancelled.
    ToolHandler
    The body of an MCP tool: takes the parsed argument JSON and the shared ServerContext, returns the structured result payload.
    ToolHandler.Cancellable
    A handler that observes its cancellation signal while it runs.
    ToolRegistration
    One complete MCP tool definition: name, description, JSON input/output schema, behavior annotations, owning Toolset, and the ToolHandler that executes it.
    Toolset
    The named tool groups the embedded MCP server can expose, selectable via EquinixMcpServer.builder().toolsets(...), the EQUINIX_MCP_TOOLSETS environment variable, or the --toolsets launch argument (comma-separated ids, e.g.
    UntrustedText
    The one place tool output handles text that came from a remote system: Equinix API fields (ticket references, device names, service-profile names, error messages), PeeringDB names, and the messages of failed pricing lookups.
    UntrustedText.Untrusted
    A text node holding sanitised remote text.