Bud MCP Foundry / Platform architecture

Seven layers.
Complete technical specification.

Consumer, transport, gateway, middleware, backend services, registry, and data. Every request traverses the full middleware stack before reaching a backend. This enforces consistent security, observability, and policy regardless of which component is accessed.

Overview

A layered design that separates concerns across every request.

Bud MCP Foundry delivers a layered architecture that separates concerns across consumer, transport, gateway, middleware, services, platform capabilities, registry, and data layers. Every request traverses the full middleware stack before reaching a backend service.

Below is each layer's specification, the complete middleware responsibility table, all six backend services, the unified four-tier MCP Registry, and the internals of Bifrost and federation.

Platform diagram

The complete stack at a glance.

foundry.bud.studio / architecture / v1

Bud MCP Foundry complete platform architecture: consumer, transport, gateway, middleware, backend services, platform services, registry, data and observability

Seven layers, four registry tiers, one governance plane — expanded below.

Consumer layer

Client-agnostic consumers. Any MCP-compliant client connects.

AI agents are the primary programmatic consumers. They establish authenticated sessions via JWT, OAuth, or SSO tokens; discover capabilities through standard MCP methods (tools/list, resources/list, prompts/list); invoke tools via tools/call; and participate in multi-agent coordination through the A2A Service.

The platform accepts commercial AI assistants (Claude, ChatGPT, Gemini, Cursor), open-source agent frameworks (LangChain, CrewAI, AutoGen, LangGraph), custom-built agents, the React Web Dashboard for administration, programmatic REST/CLI/SDK clients, federated peer Foundries, and editor integrations via stdio MCP wrapping.

Transport layer

Five protocols normalized into a consistent API surface.

The transport layer accepts five protocols and presents a consistent invocation semantics to the middleware stack above it.

HTTP / JSON-RPC

Low-latency request-response operations. Standard REST for administrative calls and synchronous tool invocations.

Server-Sent Events

Uni-directional streaming for long-running tool invocations and MCP protocol sessions.

WebSocket

Full-duplex bidirectional communication for low-latency, interactive sessions.

Streamable HTTP

MCP Streamable HTTP transport, specification version 2025-06-18. Bidirectional with session resumability.

Stdio (bridged)

Support via mcpgateway-wrapper for editor plugins and CLI clients. Automatically bridged to HTTP/SSE by the platform.

API gateway

A single entry point for all traffic.

Built on a high-performance ASGI framework with ORJSON serialization (5-6x faster than stdlib JSON). Accepts and validates inbound connections, routes requests to the correct service endpoint, applies the middleware stack in defined order, serves OpenAPI documentation (Swagger UI), and exposes /health, /ready, and /health/security endpoints.

Middleware stack

An ordered pipeline every request passes through.

Execution order: CORS and compression (outermost), followed by security headers, protocol validation, token scoping, authentication, RBAC, request logging, and observability instrumentation (innermost).

MiddlewareResponsibilityKey behavior

AuthAuthentication enforcementExtracts and validates JWT tokens. Supports plugin-based custom authentication. Checks token revocation status before request processing.

RBACRole-based access controlEvaluates roles and permissions. Global, team-scoped, and personal permission levels. Logs all decisions.

CORSCross-origin resource sharingConfigures allowed origins, methods, headers, and credential sharing for browser-based clients.

Request LoggerStructured loggingStructured JSON logs. Automatically masks JWT tokens, passwords, API keys, and OAuth tokens in output.

Security HeadersHTTP security hardeningInjects CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy.

CompressionResponse compressionApplies negotiated compression (Brotli, Zstandard, or GZip) to response payloads based on client Accept-Encoding.

Rate LimitingRequest throttlingConfigurable rate limits per tool and per client. HTTP 429 with Retry-After header on breach.

Token ScopingFine-grained access controlIP/CIDR restrictions, time-window restrictions, server-scope, permission restrictions, team-membership checks.

Order of execution: CORS → Compression → Security Headers → Protocol Validation → Token Scoping → Authentication → RBAC → Request Logger → Observability instrumentation → Backend service. Outermost to innermost.

Backend services

Six services operating in concert.

Each service has a defined responsibility, its own telemetry surface, and a contract exposed through the API gateway.

Federation Service

Discovers peer gateways through DNS-SD / mDNS (Zeroconf), static peer lists, and peer exchange. Monitors peer health with configurable thresholds. Forwards tool invocation requests to the gateway that owns the requested tool. Aggregates responses across federated peers. Synchronizes capability catalogs.

Gateway Service

Manages peer gateway lifecycle: registration, health monitoring, capability ingestion, decommissioning. Handles gateway-level OAuth token management and refresh flows.

Tool Service

The central registry and invocation engine. Registers tools with JSON Schema input validation. Invokes tools with schema validation, timeout enforcement, and error handling. Executes pre- and post-invocation plugin chains. Tracks per-tool metrics.

Team Management

Multi-tenant team isolation. Manages team membership, roles, and history. Scopes tool, resource, prompt, and server visibility to specific teams. Maintains audit trails of team membership changes.

A2A Service

Implements Agent-to-Agent communication protocol. Registers external AI agents with endpoint URLs, capabilities, and authentication requirements. Proxies inter-agent communication. Tracks per-agent metrics.

MCP Server Service

Manages virtual MCP servers: logical groupings of tools, resources, prompts, and A2A agents exposed as cohesive endpoints. Publishes to the Skills Registry.

MCP Registry

The four-tier unified registry.

The registry unifies all four connectivity modes behind a single governance plane. Consumers see one catalog. Bifrost routes to the correct backend.

Unified Registry

One catalog. Four origins.

Tier 01

Remote hosted

1,000+ third-party MCPs federated over HTTPS / SSE / Streamable HTTP. OAuth via Fernet-encrypted credentials.

Tier 02

Stdio-bridged

Self-hosted stdio MCPs auto-bridged to HTTP/SSE. Subprocess lifecycle, keepalive, horizontal scaling, Redis session state.

Tier 03

AI-generated

Custom MCPs produced by the Ingestion → Crawler → Enhancer → Evaluator pipeline from enterprise assets.

Tier 04

Internal

Tools, resources, and prompts managed natively via the Skills Hub. Stored in PostgreSQL, executed by the platform's service layer.

Virtual server composition. Operators compose virtual MCP servers from selected tools, resources, prompts, and A2A agents. A "Customer Success" virtual server might combine CRM tools, support ticket tools, billing prompts, and a KB retrieval skill, all bundled as a single MCP endpoint.

Data & observability

Persistent state, cache, and telemetry.

Fine-tuned connection pooling for high-concurrency deployments. Every service emits telemetry through a common instrumentation layer.

Data layer

Redis for cache: tool catalogs, session state, gateway capabilities
Distributed session management across worker pools
PostgreSQL 14+ (or MySQL 8+, MariaDB 10.6+) for persistent state
SQLAlchemy 2.0 ORM with Alembic migrations
Fine-tuned connection pooling for high-concurrency deployments

Observability layer

LogFire dedicated AI agent activity logging
OpenTelemetry distributed tracing with W3C Trace Context propagation
Prometheus metrics exposed via /metrics/prometheus with GZip
Structured JSON logs with automatic sensitive-data masking
Export to OTLP (gRPC/HTTP), Jaeger, Zipkin, or console

Deep dive

Bifrost internals.
How one catalog hides four tiers.

Bifrost is the internal routing plane that abstracts multi-protocol, multi-origin MCP server connectivity into a unified dispatch layer. It is the component that makes the four-tier tool management look like one tier to consumers.

Dispatch and routing

Routes MCP method calls to locally registered, federated, or stdio-bridged backends
Enforces routing policies: tool-level access controls, team visibility scoping, rate limiting
Provides multi-source MCP connectivity as a single interface
Supports qualified naming (gateway.tool) for human-readable references across federation

Protocol handling

Translates between transport protocols: normalizes stdio, SSE, and Streamable HTTP into a consistent format
Handles protocol version negotiation between the gateway and each backend MCP server
Forwards requests to federated gateways and aggregates multi-gateway responses
Streams are preserved end-to-end where the backend supports them

Capability merge

Performs capability merge across federated peer Foundries
Composite key identity resolution to disambiguate tools with identical names from different peers
Synchronizes catalog changes with change-event propagation
Deduplicates and flags conflicts for operator review

Virtual server composition

Operators create virtual MCP servers from selected tools, resources, prompts, and A2A agents
Cohesive logical groupings exposed as a single endpoint
Useful for exposing curated, workflow-specific capability sets to specific teams
Each virtual server carries its own visibility, policy, and observability scope

Federation mechanics

Peer discovery and capability synchronization.

Peer discovery

The Federation Service discovers peer gateways through three mechanisms:

DNS-SD / mDNS (Zeroconf) auto-discovery within a reachable network segment
Static peer lists configured at deployment time
Peer exchange, where known peers share their own peer lists

Health monitoring

Each peer is monitored with configurable thresholds. Auto-healing uses separated enabled and reachable status fields. Unhealthy peers are auto-excluded from routing until they recover, and operators can force inclusion or exclusion through the dashboard.

Request forwarding

Tool invocation requests are forwarded to the gateway that owns the requested tool. For requests that span multiple peers (discovery, broadcast), responses are aggregated, deduplicated, and returned as a single MCP-compliant response.

Capability synchronization

Each federated peer advertises its catalog through standard MCP methods. Capability changes are propagated as change events. Composite key identity resolution prevents collisions when peers independently publish tools with the same name.

Ready to go deeper?

Review the security and compliance specification, the full integrations catalog, or industry-specific deployment patterns.

Security & compliance Integrations catalog Industry solutions Back to overview

Seven layers.Complete technical specification.