DEV Community

farshad khazaee
farshad khazaee

Posted on

Breeze v2: An AI-First Go Framework Built for MCP, Agents, and Distributed Systems

#go #mcp #ai #webdev

What if your backend wasn't just built for humans and services — but for AI agents too?

That's the idea behind Breeze v2.

Breeze started as a high-performance, event-driven Go web framework built around gnet.

But the direction of v2 is much broader.

The goal is to build a Go application platform where AI agents, APIs, services, workflows, observability, and runtime infrastructure are first-class citizens.

Not an AI wrapper around a web framework.

An AI-First architecture from the inside out.

Breeze on GitHub

The Problem With "AI-Enabled" Backends

Most applications were designed like this:

                    Application
                         │
              ┌──────────┴──────────┐
              │                     │
             API                  Admin
              │                     │
            Users                Services
Enter fullscreen mode Exit fullscreen mode

Then AI arrived.

Suddenly we add:

                 AI Agent
                    │
              ┌─────┴─────┐
              │           │
            Tools       Context
              │           │
              └─────┬─────┘
                    │
                Application
Enter fullscreen mode Exit fullscreen mode

And now another layer of infrastructure is required.

An MCP server.

Another authentication system.

Another API adapter.

Another way to expose tools.

Another way to inspect production.

Another way to give an agent access to the system.

I think this architecture is backwards.

If AI agents are becoming a first-class consumer of software, the application framework should understand them from the beginning.

That's one of the core ideas behind Breeze v2.

Breeze v2 Is AI-First

The architecture is increasingly centered around three ideas:

                       Breeze v2
                           │
          ┌────────────────┼────────────────┐
          │                │                │
         MCP             Fleet           Runtime
          │                │                │
       AI Agents      Distributed       Application
          │             Systems          Control
          │                │                │
          └────────────────┼────────────────┘
                           │
                     Go Application
Enter fullscreen mode Exit fullscreen mode

MCP gives agents a standardized interface into the application.

Fleet gives distributed systems a unified observability and tracing layer.

The runtime provides the infrastructure that connects everything together.

MCP Isn't a Plugin in Breeze

One of the most important architectural decisions in Breeze v2 is that MCP is part of the framework itself.

Breeze exposes its capabilities to AI agents through the Model Context Protocol in several different modes. ([GitHub][1])

That means an AI agent can interact with Breeze at different levels.

1. MCP as a Development Agent

The first mode is:

breeze-mcp --mode=generator
Enter fullscreen mode Exit fullscreen mode

This is not simply an API wrapper.

It is designed to let an agent build and modify a Breeze project.

The generator MCP exposes roughly 40 tools covering operations such as:

  • scaffolding projects
  • generating resources
  • wiring framework features
  • planning change sets
  • running the Go toolchain
  • inspecting services
  • examining routes
  • checking errors
  • reading logs
  • inspecting performance
  • inspecting traces
  • detecting contract violations
  • diagnosing services
  • Docker-aware fleet provisioning

([GitHub][1])

Think about what this changes.

Instead of:

Developer
   ↓
IDE
   ↓
CLI
   ↓
Framework
Enter fullscreen mode Exit fullscreen mode

you can have:

Developer
   ↓
AI Agent
   ↓
MCP
   ↓
Breeze
   ├── CLI
   ├── Generator
   ├── Runtime
   ├── Fleet
   └── Application
Enter fullscreen mode Exit fullscreen mode

The agent isn't guessing how your project works.

It has structured capabilities.

From "Generate Code" to "Operate the System"

A traditional AI coding agent might generate:

type User struct {
    ID    uint64 `json:"id"`
    Name  string `json:"name"`
}
Enter fullscreen mode Exit fullscreen mode

That's useful.

But imagine asking:

Create a user service, add authentication, expose the API, run the tests, inspect the service, and tell me if anything is wrong.

That requires more than code generation.

The agent needs to:

Understand
    ↓
Plan
    ↓
Generate
    ↓
Build
    ↓
Run
    ↓
Inspect
    ↓
Diagnose
    ↓
Change
    ↓
Verify
Enter fullscreen mode Exit fullscreen mode

That's the direction Breeze's generator MCP is designed to support.

2. MCP for Production Runtime

The second mode is fundamentally different:

breeze-mcp --mode=app-runtime
Enter fullscreen mode Exit fullscreen mode

This mode is read-only.

The mutating tools aren't merely hidden behind a permission check.

They are not registered in the first place. ([GitHub][1])

That's an important security property.

Instead of:

Agent
  │
  ├── read
  ├── inspect
  ├── modify
  └── deploy
Enter fullscreen mode Exit fullscreen mode

a production runtime can expose:

Agent
  │
  ├── inspect
  ├── diagnose
  ├── observe
  └── analyze
Enter fullscreen mode Exit fullscreen mode

No accidental mutation surface.

That's the kind of boundary I think AI infrastructure needs.

3. MCP Inside the Application

Breeze can also embed MCP directly into the application.

No separate MCP process is required.

scope, _ := mcp.NewScope(mcp.CapFleet)

server, token, err := mcp.StartInProcess(
    app,
    mcp.InProcessConfig{
        Mode:  mcp.ModeAppRuntime,
        Port:  2000,
        Token: os.Getenv("BREEZE_MCP_TOKEN"),
        Scope: scope,
    },
)
Enter fullscreen mode Exit fullscreen mode

Then the application can expose its own MCP control plane alongside normal application traffic. ([GitHub][1])

Conceptually:

                  Breeze Application
                         │
             ┌───────────┴───────────┐
             │                       │
          HTTP API                MCP
             │                       │
          Humans                 AI Agents
Enter fullscreen mode Exit fullscreen mode

Same application.

Same runtime.

Different consumers.

4. Auto-MCP

This is one of my favorite parts of the design.

You can make an existing route callable by an AI agent by explicitly tagging it.

For example:

router.Handle(
    breeze.POST,
    "/orders",
    createOrder,
    auth.Require(),
    breeze.MCPTool(
        "create_order",
        "Places an order for a customer.",
    ),
)
Enter fullscreen mode Exit fullscreen mode

That's it.

The route becomes an MCP tool.

More importantly, the call goes through the same middleware chain as HTTP. ([GitHub][1])

And untagged routes are not exposed.

So the model is:

HTTP Route
    │
    ├── HTTP
    │
    └── MCP Tool
Enter fullscreen mode Exit fullscreen mode

instead of duplicating the business logic:

HTTP Handler ────────────┐
                         ├── Business Logic
MCP Handler ─────────────┘
Enter fullscreen mode Exit fullscreen mode

This is what I mean by AI-First.

The application doesn't need a separate AI version of itself.

MCP + Authentication + Middleware

Another important detail is that Auto-MCP doesn't bypass your application architecture.

If your route has:

auth.Require()
Enter fullscreen mode Exit fullscreen mode

the MCP invocation goes through that same middleware chain.

So your application can define:

Authentication
      ↓
Authorization
      ↓
Rate Limit
      ↓
Validation
      ↓
Business Logic
Enter fullscreen mode Exit fullscreen mode

and expose the resulting capability to an AI agent.

This is much safer than creating an entirely separate "AI API."

MCP Scopes

Breeze also provides capability scopes.

For example:

scope, _ := mcp.NewScope(mcp.CapFleet)
Enter fullscreen mode Exit fullscreen mode

The idea is that an MCP token doesn't automatically get access to everything.

Instead:

Agent
  │
  ▼
MCP Token
  │
  ▼
Capability Scope
  │
  ├── Fleet
  ├── Runtime
  ├── Diagnostics
  └── ...
Enter fullscreen mode Exit fullscreen mode

That gives applications a much more explicit security boundary for agent access. ([GitHub][1])

Fleet: AI Needs a Map of the System

Now we get to the second major piece of Breeze v2.

Fleet.

An AI agent working with a distributed application has a fundamental problem:

How does it understand what's actually happening across multiple services?

Consider:

                API Gateway
                     │
        ┌────────────┼────────────┐
        │            │            │
      Users        Orders       Payments
        │            │            │
        └────────────┼────────────┘
                     │
                 Database
Enter fullscreen mode Exit fullscreen mode

A single failed request can cross multiple services.

Without distributed tracing, an agent sees fragments.

With Fleet:

Request
  │
  ├── API
  │
  ├── Orders
  │
  ├── Payments
  │
  └── Database
Enter fullscreen mode Exit fullscreen mode

becomes one traceable execution path.

Distributed Tracing Without an OTel Stack

Breeze Fleet provides distributed tracing across services without requiring Jaeger, Zipkin, or an OpenTelemetry Collector.

A service can create a tracer:

tracer := fleet.New(fleet.TracerConfig{
    ServiceName:   "orders",
    AggregatorURL: "http://fleet-aggregator:9000/fleet",
})

router.Use(fleet.Middleware(tracer))
Enter fullscreen mode Exit fullscreen mode

Then run a shared aggregator:

go run ./cmd/fleet-aggregator
Enter fullscreen mode Exit fullscreen mode

([GitHub][1])

Fleet uses W3C traceparent propagation and exports spans asynchronously so tracing doesn't block request handlers. ([GitHub][1])

Fleet Is More Than Tracing

This is where Fleet becomes particularly interesting.

It provides a live topology graph:

             API
              │
        ┌─────┴─────┐
        ▼           ▼
      Users       Orders
                    │
                    ▼
                 Payments
Enter fullscreen mode Exit fullscreen mode

And the graph includes:

  • live p50 latency
  • live p95 latency
  • trace propagation
  • topology
  • root-cause highlighting
  • blast-radius highlighting
  • OpenAPI contract validation
  • trace-correlated logs

([GitHub][1])

The root-cause and blast-radius analysis is deterministic graph analysis rather than an AI black box. ([GitHub][1])

That's important.

AI can consume the resulting structured information, but the underlying diagnostic signal doesn't need to be invented by an LLM.

Now Combine MCP + Fleet

This is where the architecture becomes interesting.

Imagine a production incident:

User reports:
"Checkout is slow."
Enter fullscreen mode Exit fullscreen mode

An AI agent can potentially move through:

MCP
 │
 ▼
Fleet
 │
 ▼
Topology
 │
 ▼
Traces
 │
 ▼
Latency
 │
 ▼
Logs
 │
 ▼
Contract violations
 │
 ▼
Diagnosis
Enter fullscreen mode Exit fullscreen mode

Instead of asking an AI:

"What do you think is wrong?"

we can give it structured evidence.

That changes the role of AI.

AI becomes the reasoning layer over real runtime data, rather than the source of runtime truth.

That's a much more interesting model.

AI-First Doesn't Mean AI Everywhere

This distinction matters.

Breeze isn't trying to replace deterministic infrastructure with an LLM.

Instead:

Deterministic Infrastructure
          │
          ├── Routing
          ├── Authentication
          ├── Tracing
          ├── Metrics
          ├── Workflows
          ├── Diagnostics
          └── Runtime
                    │
                    ▼
                   MCP
                    │
                    ▼
                 AI Agent
                    │
                 Reasoning
Enter fullscreen mode Exit fullscreen mode

The framework provides facts.

The agent reasons about those facts.

JSON-RPC Is Part of the Foundation

Breeze also includes a complete JSON-RPC 2.0 server running as a peer of the HTTP layer rather than simply as another HTTP route.

It supports:

  • requests
  • notifications
  • batches
  • standard JSON-RPC errors
  • stdio transport

The stdio transport is also what powers the MCP integration. ([GitHub][1])

This gives Breeze a clean protocol stack:

                Breeze
                   │
        ┌──────────┼──────────┐
        │          │          │
       HTTP      JSON-RPC     MCP
        │          │          │
      REST      Services    Agents
Enter fullscreen mode Exit fullscreen mode

AI-Readable APIs

Breeze also generates OpenAPI 3.1 documentation and provides:

/openapi.json
/scalar
/llms.txt
/llms-full.txt
Enter fullscreen mode Exit fullscreen mode

The llms.txt endpoints provide a model-readable representation of the API. ([GitHub][1])

That means API documentation isn't only for humans anymore.

It's also becoming part of the context layer for AI systems.

Workflows + Agents

AI agents frequently need to initiate operations that are not atomic.

For example:

Create Customer
      ↓
Provision Account
      ↓
Charge Payment
      ↓
Create Resources
      ↓
Notify Customer
Enter fullscreen mode Exit fullscreen mode

Breeze provides durable workflows with capabilities such as:

  • retries
  • compensation
  • workflow visualization
  • orchestration

The project includes a runnable workflow example demonstrating retries, compensation and live visualization. ([GitHub][1])

This gives an agent something important:

reliable actions instead of arbitrary sequences of API calls.

Events Become the Nervous System

Breeze also includes a typed event system.

The event layer is designed as the internal communication mechanism between framework subsystems.

The repository describes it as a typed, reflection-free publish/subscribe system used by areas such as routing, OAuth2, dashboard, scheduler, plugins and WebSockets. ([GitHub][2])

Conceptually:

                  Events
                    │
       ┌────────────┼────────────┐
       │            │            │
     HTTP         Workflow      OAuth
       │            │            │
    WebSocket    Dashboard    Scheduler
Enter fullscreen mode Exit fullscreen mode

This makes the runtime much easier to observe and extend.

And Then There Is the Traditional Breeze

AI-First doesn't mean abandoning the things Go developers already expect from a web framework.

Breeze still provides a high-performance HTTP stack built around gnet, with an event-driven architecture, inline execution, zero-copy capabilities, pooled objects, optimized routing and configurable worker pools. ([GitHub][2])

It also includes:

WebSockets

Native WebSocket support with text/binary frames, ping/pong, fragmentation and connection management. ([GitHub][2])

OpenAPI / Scalar

Automatic API documentation and interactive Scalar UI. ([GitHub][1])

gRPC

Code generation for gRPC services and adapters. ([GitHub][2])

OAuth2

Production middleware for authentication and social login.

Middleware

Rate limiting, compression, caching and JWT authentication. ([GitHub][2])

Video Streaming

HTTP byte-range streaming with signed expiring URLs and security protections. ([GitHub][1])

Templates / SPA / i18n

Server-rendered views, SPA navigation, reusable components, localization and development hot reload. ([GitHub][1])

Dashboard

A built-in developer dashboard for inspecting the running application.

Observability

Event recording, metrics, live subscribers and execution graphs. ([GitHub][1])

Diagnostics

A unified diagnostic endpoint capable of reporting subsystem states such as ok, degraded, off, and unknown. ([GitHub][1])

CLI

Project scaffolding, resource generation, workflows, middleware, WebSockets, jobs, migrations and gRPC generation. ([GitHub][2])

The Architecture

Putting everything together:

                           AI Agents
                              │
                              ▼
                         ┌─────────┐
                         │   MCP   │
                         └────┬────┘
                              │
              ┌───────────────┼────────────────┐
              │               │                │
              ▼               ▼                ▼
          Generator         Runtime        Auto-MCP
              │               │                │
              └───────────────┼────────────────┘
                              │
                         Breeze Runtime
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
        HTTP               Events             Workflow
          │                   │                   │
      WebSocket          Observability        Retries
          │                   │                Saga
          │                   │              Timeout
          └───────────────────┼───────────────────┘
                              │
                            Fleet
                              │
              ┌───────────────┼───────────────┐
              │               │               │
            Service A      Service B       Service C
              │               │               │
              └───────────────┼───────────────┘
                              │
                         Distributed
                           Tracing
Enter fullscreen mode Exit fullscreen mode

This is the direction of Breeze v2.

The Bigger Idea

I don't think the future of AI applications is:

Web Framework
      +
Separate AI Framework
      +
Separate MCP Server
      +
Separate Observability Stack
      +
Separate Workflow Engine
Enter fullscreen mode Exit fullscreen mode

I think there's an opportunity for something more integrated:

                 Application Platform
                         │
       ┌─────────────────┼─────────────────┐
       │                 │                 │
    Humans            Services          AI Agents
       │                 │                 │
       └─────────────────┼─────────────────┘
                         │
                      Runtime
                         │
        ┌────────────────┼────────────────┐
        │                │                │
       MCP             Fleet          Workflow
        │                │                │
        └────────────────┼────────────────┘
                         │
                       Go
Enter fullscreen mode Exit fullscreen mode

That's what I'm trying to build with Breeze.

Not an AI SDK.

Not an MCP wrapper.

Not just another Go HTTP framework.

An AI-First application runtime for Go.

What's Next?

The interesting part is what becomes possible when these primitives start working together.

Imagine an agent that can:

Understand the application
        ↓
Inspect the architecture
        ↓
Generate a change
        ↓
Run tests
        ↓
Deploy a service
        ↓
Observe the fleet
        ↓
Detect a regression
        ↓
Trace the failure
        ↓
Diagnose the root cause
        ↓
Propose a fix
Enter fullscreen mode Exit fullscreen mode

That's much closer to an agent-native backend than a traditional web application.

And that's where I want Breeze v2 to go.

Try Breeze

Breeze is open source and available on GitHub:

Breeze v2 on GitHub

The project is MIT licensed and currently requires Go 1.25.13 or later. ([GitHub][1])

go get github.com/nelthaarion/breeze/v2
Enter fullscreen mode Exit fullscreen mode

If you're building AI agents, MCP-enabled services, distributed Go systems, or high-performance APIs, I'd love to see what you build with it.

Tags

#go #golang #ai #mcp #opensource

Top comments (1)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.