HexaGO – A Go‑Based Hexagonal Architecture Demo for MCP

HexaGO is a lightweight illustration of the hexagonal (ports & adapters) architecture implemented in Go. It demonstrates how a simple calculator service can be structured so that its core business logic is completely isolated from external concerns such as HTTP, databases, or any other I/O. By exposing its functionality through well‑defined ports, the service can be easily plugged into an MCP server, allowing AI assistants to invoke calculations or other domain operations without needing direct knowledge of the underlying infrastructure.

The primary goal of this MCP server is to solve a common problem in AI‑centric development: separating domain logic from communication mechanisms. When an AI assistant requests a calculation, the MCP server forwards that request to the calculator’s core via a defined port. The core performs the arithmetic, then returns the result through the same interface. Because the core never touches HTTP or database code, it remains testable in isolation and can be swapped with alternative implementations (e.g., a distributed computation engine) without touching the AI client.

Key features of HexaGO include:

• Clear separation of concerns: Core logic, ports (interfaces), and adapters (implementations) are organized into distinct packages. This mirrors the pattern described by Alistair Cockburn and Juan Manuel Garrido de Paz, ensuring maintainability.
• Extensible adapters: The HTTP adapter () translates RESTful requests into port calls, while a database adapter can be added later without modifying the core.
• Testability: The ports define contracts that allow unit tests to mock external systems, enabling rapid regression testing of the core business rules.
• MCP compatibility: By exposing its ports as MCP capabilities, AI assistants can discover and invoke the calculator service through standard MCP discovery mechanisms.

Real‑world scenarios where HexaGO shines include:

• AI‑powered financial tools: An assistant can request currency conversion or tax calculations from the server, which safely processes the logic in a decoupled core.
• Educational chatbots: A tutor bot can ask the server to solve math problems, receiving clean results without exposing HTTP details.
• Microservice ecosystems: In a larger architecture, HexaGO can act as a standalone service that other AI agents call via MCP, while the internal adapters handle persistence or external API calls.

Integration with AI workflows is straightforward: an MCP client (e.g., Claude) queries the server’s endpoint or invokes a tool defined by the MCP protocol. The server processes the request through its ports, returns the result, and the assistant can then incorporate that information into a conversation or further computation. This decoupled design ensures that changes to the network layer, database schema, or even programming language do not ripple through the AI client’s logic.

In summary, HexaGO offers developers a clean, modular template for building MCP‑ready services. Its emphasis on hexagonal architecture guarantees that the core remains pure, testable, and easily replaceable—an essential quality for robust AI integrations.