← Back to blogעברית

Goose under the hood: an MCP-native harness with a protocol at the center

How Goose builds its agent loop around MCP extensions, approvals, and context management, plus the unique design choice that holds it together and a lesson for harness builders.

Goose is easy to describe as an open source AI agent with a desktop app, CLI, and API. But the more useful description is architectural: Goose is a harness built around a protocol. Instead of treating tools, extensions, and integrations as separate feature buckets, it tries to make them speak one language.

That choice shows up everywhere in how Goose works: in the extension system, in the interactive loop, in approval flows, and even in the way the project is migrating its agent runtime. If you read Goose as “an MCP client that happens to be an agent,” a lot of its design starts to make sense.

Goose's MCP-native harness architecture

The shape of the harness

At a high level, Goose follows the anatomy we mapped in the overview post:

  1. Interface: a desktop app or CLI collects user input and renders results.
  2. Agent: the core runtime manages the loop, state, and coordination.
  3. Extensions: capability providers expose tools the agent can call.

The key detail is how those extensions connect. Goose uses the Model Context Protocol (MCP) as the interoperability layer between the agent and capability servers. Built-in functionality, external MCP servers, and other extension forms are brought into the same tool-calling world. In Goose’s architecture, extensions expose tools, and tools are the concrete actions the model can request.

This gives the harness a clean center of gravity:

  • Discovery and description come from tool definitions.
  • Execution happens through extension/tool dispatch.
  • Safety can be enforced around tool requests and results.
  • Growth comes from adding more extensions without rewriting the agent.

How a turn flows

Goose documents a straightforward interactive loop:

  1. A human request starts the turn.
  2. The agent sends the request and available tools to the selected model provider.
  3. The model may respond with text and/or tool call requests.
  4. Goose executes those tool calls through the relevant extension.
  5. Tool results go back to the model.
  6. Goose revises context to keep the working set useful.
  7. The model produces a final response, or the loop continues if more work is needed.

This is familiar agent-loop territory, but two implementation details matter.

First, errors are part of the conversation. Instead of letting many failures crash the run, Goose can capture execution problems and return them to the model as tool responses. That gives the model a chance to recover, retry differently, or explain what went wrong.

Second, context revision is a first-class concern. Goose explicitly treats token management as part of the harness: summarization, removing stale or irrelevant information, preferring targeted operations (like find-and-replace or focused searches) over bulky rewrites, and keeping verbose outputs under control. In other words, the loop is not only “call tools until done”; it is “keep the next model call viable.”

More than one runtime mode

Recent Goose work also points to a deeper architectural transition. Public architecture notes and codebase discussions describe a legacy loop alongside an opt-in, effect-sourced state-machine path (for example behind GOOSE_STATE_MACHINE=1 in some implementations). The important takeaway is not a specific flag, but the direction: Goose is moving from a large imperative loop toward a more explicit, step-driven runtime model.

Why does that matter? Because agent behavior becomes easier to reason about when each step has clear inputs, outputs, and persisted effects. Retries, approvals, compaction, and queued work are less magical when the runtime can say exactly what state it is in and what event moves it forward. Even during migration, that pressure for explicitness is a sign of a harness maturing.

The unique secret point: one protocol boundary for every capability

If I had to pick the “secret” that makes Goose work the way it does, it is this: Goose treats MCP as the universal boundary between the agent and capability.

That sounds simple, but it is a powerful compression. When built-in tools, local servers, remote servers, and future integrations all arrive through the same protocol-shaped contract, the agent core can focus on orchestration instead of special cases. Tool discovery, invocation, result handling, permissions, and even UX around approvals can all attach to one consistent seam.

This is why Goose feels extension-native rather than extension-added. The harness is not “a core agent plus some plugins”; it is closer to “a protocol client with an agent loop around it.” That framing explains how Goose can span CLI, desktop, API, and different extension transports without inventing a new integration story each time.

Lesson for anyone building a harness

The transferable lesson from Goose is: choose one capability contract and make the whole system honor it.

If every tool path has different semantics, different error shapes, and different permission hooks, the harness accumulates invisible complexity. You end up debugging the integration layer instead of improving the agent. A strong contract (MCP or your own) gives you a place to centralize:

  • schema and validation expectations,
  • execution and timeout behavior,
  • approval and policy enforcement,
  • logging/observability,
  • and recovery from tool failures.

You do not have to use MCP specifically. But you do need the Goose instinct: collapse the number of ways “doing work” can happen. The more uniform the boundary, the easier it is to evolve the loop, add capabilities, and keep safety consistent.

Sources

Weekly series

Read the posts in order:

  1. Adding a blog to my personal site (without starting over) - 2026-11-11
  2. Why PostHog is one of the first tools I add to a new product - 2026-11-18
  3. Anatomy of a coding harness: what makes AI coding agents work - 2026-11-11
  4. Context management in coding harnesses: what gets sent, and why it matters - 2026-11-18
  5. Goose under the hood: an MCP-native harness with a protocol at the center (this post) - 2026-11-11
  6. Pi under the hood: a minimal harness built around session trees and primitives - 2026-11-18
  7. OpenCode under the hood: one loop, many models, real environment feedback - 2026-11-11
  8. DeepSeek Harness under the hood: everything is a plugin, and the log is the contract - 2026-11-18

Previous: Context management in coding harnesses: what gets sent, and why it matters Next: Pi under the hood: a minimal harness built around session trees and primitives