The problem: cross-cutting logic duplicated across every backend
Hivebrite’s core product is a Rails monolith serving 2,000+ community networks: alumni associations, professional bodies, nonprofits, and corporate alumni programs, each running as an isolated, branded network with its own members, events, groups, and back-office.
Before KrakenD there was no API gateway at all. The monolith took client requests directly and handled JWT validation, input and output checking, and rate limiting itself, endpoint by endpoint. That approach holds up for a single monolith. It stops scaling the moment a second backend enters the picture, because every new service inherits the same per-endpoint maintenance burden.
Hivebrite’s architecture goal was never “100% microservices.” It was to extract a handful of services and build new ones around the monolith, while the monolith kept serving the bulk of the product. The trigger for a gateway was a deliberate move to a contract-first API model: engineers author an API contract, models, requests, responses, as the single source of truth, and the published OpenAPI spec is produced from it.
Cyril Schmitt, the Backend Engineer who led the evaluation, compared KrakenD against Tyk. Performance at low traffic was roughly equivalent, Tyk slightly ahead under minimal load, KrakenD stronger above 1,000 requests per second. The decision came down to something more fundamental: pricing transparency. Tyk had a track record of moving features from free to enterprise mid-relationship. KrakenD’s model was explicit from day one, and that predictability mattered as much as the throughput numbers.
The solution: a contract-first pipeline with one API gateway
KrakenD sits in front of everything, consuming the published contracts and taking over the cross-cutting work the monolith used to do per endpoint: JWT validation at the edge, request and response validation against the contract schema, and rate limiting. New APIs already route through the gateway; the legacy surface is migrating over progressively.
REST and MCP proxy to the Rails monolith and a couple of extracted Go and Python services
Hivebrite runs KrakenD across four geographic zones, US, Europe, Asia, and Switzerland, with multiple instances per zone for high availability and isolation. The entire fleet is managed through the same resolver pipeline.
Inside the gateway: an annotation layer that compiles into native config
The single source isn’t just an OpenAPI spec. It’s an OpenAPI spec enriched with a small private annotation vocabulary, Hivebrite’s own x-gateway-* directives, that a Go resolver compiles into native gateway config (x-krakend-*) at build time. The mechanism underneath is stock KrakenD: OpenAPI import already turns an annotated operation into JWT validation, schema validation, rate limiting, and MCP tool exposure. What Hivebrite added on top is its own naming layer, decoupling its internal contract conventions from KrakenD’s own configuration syntax so either can evolve independently. Per operation, at the source, the team can toggle request and response validation on or off, decide whether the operation is exposed as an MCP tool, give the MCP tool a description distinct from the human-facing documentation, and target an audience, internal or partner.
Baked into a Docker image; Flexible Config assembles the final krakend.json per environment at pod start
The MCP side is organized into catalogs, an admin catalog today, a user catalog growing next, and because everything is anchored on the OpenAPI schemas, those same schemas enrich the MCP tool definitions and their input shapes. One schema drives validation, documentation, and the MCP contract at once. This annotation layer is where new surfaces arrive REST-, MCP-, and docs-ready from the same description, with per-operation control.
The unexpected turn: MCP as a second delivery surface
When the Model Context Protocol became a practical tool for exposing APIs to LLM agents, Hivebrite’s team saw the opportunity immediately. The back-office API could be exposed to LLM clients so an operator could drive their community network in natural language: “find members registered for next month’s event,” “create the alumni mixer and open RSVPs,” “show pending approvals.” The agent calls the matching MCP tools, and the gateway handles the rest. Every call stays scoped to the operator’s single network, since the gateway and backend enforce that boundary and an agent never gets cross-network reach.
The interesting part is what that use case pushed the team to modernize. Hivebrite was already using JWTs, but in an older token format. MCP became the occasion to migrate the legacy API onto their current JWT format, carrying an audience claim, internal or partner, so a token is only valid on the API surface it’s meant for. The MCP project cleaned up a debt that had been sitting in the backlog, leaving a much cleaner surface behind.
The delivery mechanism is a single annotation on an OpenAPI operation:
x-gateway-mcp: admin
The resolver reads that annotation and, at build time, emits both the REST endpoint and the corresponding MCP tool from the same operation definition. One source, two surfaces, no duplicated configuration. The team applies this uniformly across the legacy API and the new contract APIs, so every new API ships MCP-ready by design.
Today, Hivebrite has several hundred REST operations across its legacy API and newer contract APIs. More than 200 of them are wired as MCP tools from those same definitions, a curated subset kept active. The cost of exposing an existing operation to an LLM agent is a single annotation line.
One source of truth, two delivery surfaces. We expect this pattern to become fairly standard as more teams start exposing their REST surface to LLMs.
The team proved the surface internally first, and is now running a beta with selected customers ahead of a broader rollout.
Three MCP-specific plugins, built for Hivebrite’s exact requirements
Hivebrite’s use case had needs specific to its own stack: a Rails backend expecting query parameters in bracket notation, an internal pagination convention carried in response headers, and an admin-facing agent where preserving backend validation detail on error was worth the extra work. KrakenD’s plugin system let the team write exactly those three MCP-specific pieces of business logic in Go. Everything else, JWT validation, schema validation, rate limiting, the MCP tool exposure itself, runs on stock KrakenD configuration.
Both paths return the MCP result (content / isError) to the LLM client
Argument forwarding (bodytoquery). Once the MCP server dispatches a tools/call, path parameters are substituted into the URL, but the remaining tool arguments still need to reach a Rails backend in bracket notation, ?network_event[title]=Foo. The plugin takes an allowlist derived from each OpenAPI operation and writes the arguments onto the outbound query string, with the flattening each side expects, query parameters for read calls, nested JSON turned into bracket notation for writes.
Error passthrough. When a backend returns a 422 with field-level validation detail, {"errors": [{"field": "email", "code": "taken"}]}, that information is exactly what an LLM agent needs to retry intelligently. For this admin-facing tool, Hivebrite wanted that detail preserved rather than flattened, so the plugin packs the backend error body into a 200 response matching MCP’s result.isError: true convention. Every other REST caller runs through a separate error-formatter plugin instead, one of Hivebrite’s other custom plugins, that rewrites the same backend error into the team’s own canonical error envelope. That plugin traces back to one of the team’s earliest questions to KrakenD’s support, telling an expired JWT apart from a malformed one, which came back with the same answer: a handler plugin was the way to do it.
Header-to-body promotion (pagination-wrap). The MCP wire carries the body, not the HTTP response headers. For Hivebrite those headers carry RFC-5988 pagination metadata, Link, X-Total, X-Page, X-Per-Page, that an agent needs to reason about when paginating through results. The plugin reads the headers and folds them into the response body. The same approach generalizes to any metadata a backend expresses through headers.
Three specific requirements, three MCP-specific Go plugins, the rest of the REST and MCP surface running on stock configuration. KrakenD’s engineering team found the pattern useful enough that parts of it are now being looked at as candidates for built-in helpers, the kind of feedback loop that comes from a team running real MCP traffic in production.
A third surface from the same source: audience-scoped docs
Beyond REST and MCP, the same single-source pipeline produces a third output: API documentation generated per audience, internal and partner each seeing exactly the surface their token is allowed to call. The docs are rendered with Scalar, open source, and served by the gateway itself, behind a dedicated endpoint, with no separate docs service to run. Generating them into the same image that ships the gateway config keeps them version-locked: every environment, including ones trialling a newer contract while a feature is in testing, serves documentation that matches exactly what it exposes. One source of truth, three delivery surfaces.
Results
| Metric | Result |
|---|---|
| REST operations exposed through the gateway | Several hundred (legacy + contract APIs) |
| Operations wired as MCP tools | 200+ |
| Additional config to expose an operation to an LLM | 1 annotation line |
| Gateway config files maintained by hand | 0 (generated from spec) |
| Custom plugins built | 3 (MCP-specific: argument forwarding, error passthrough, header promotion) |
| Delivery surfaces from one contract | 3 (REST, MCP, audience-scoped docs) |
The outcome that captures the story isn’t a single performance number. It’s the elimination of an entire category of duplicated work: one OpenAPI spec produces the REST API, the MCP tool surface, and the documentation. The governance already built for REST, JWT validation, schema enforcement, rate limiting, comes along for free on the agent surface.
MCP is now a product capability at Hivebrite, not a side project. It rolls out per network, customer by customer, like any other feature. The cost of shipping it was an annotation line, not a new service, a new security model, or a new team to run it.
Ready to simplify your API management?
See how KrakenD can help your team achieve similar results.
