metorial

Metorial hosts MCP servers via two distinct execution paths: managed Lambda-style functions running on Deno runtime for custom servers, or HTTP-based remote server integration for existing MCP implementations. The platform handles server versioning, deployment, and lifecycle events through a unified management API that abstracts over both execution modes, enabling developers to deploy code once and connect multiple AI clients without infrastructure management.

Metorial manages persistent sessions between MCP clients and servers using WebSocket, Server-Sent Events (SSE), or HTTP streaming transports, with automatic connection state tracking and message routing. The session layer (localSession.go, remoteSession.go) abstracts transport differences, enabling clients to switch protocols transparently while maintaining message ordering and delivery guarantees across distributed execution engines.

Metorial includes configuration generation tooling (generate.ts, type.ts) that templates environment variables for different deployment environments (development, staging, production) and generates type-safe configuration objects. The system validates required variables, provides defaults for optional settings, and generates TypeScript types for configuration access, reducing configuration errors and enabling IDE autocomplete.

Metorial includes GitHub Actions workflows (build-api.yml) that automate testing, building, and publishing Docker images on every commit. The pipeline runs unit tests, builds Docker containers, pushes to registry, and can trigger deployments. The build system uses Turbo for monorepo optimization, caching dependencies and build artifacts to reduce CI/CD duration.

Metorial's MCP engine (written in Go) manages execution of both local managed servers (Deno-based Lambda functions) and remote HTTP-based servers through separate session implementations (localSession.go, remoteSession.go). The engine handles protocol translation, message routing, error handling, and connection lifecycle management, with gRPC-based manager service coordinating across multiple engine instances for horizontal scaling.

Metorial implements a provider OAuth system that discovers OIDC endpoints, manages token lifecycle (acquisition, refresh, revocation), and injects provider credentials into MCP server execution contexts. The OAuth layer supports both standard OIDC implementations and custom OAuth flows, with token storage encrypted in the database and automatic refresh before expiration to ensure uninterrupted server access to protected resources.

Metorial provides a searchable marketplace (marketplace application) where developers publish MCP servers and users discover/install them with one-click integration. The marketplace indexes server metadata (name, description, capabilities, version), handles installation by creating server instances, and manages server ratings/reviews. Publishing requires version tagging and metadata validation, with automatic indexing for discoverability.

Metorial includes a web-based dashboard (dashboard application) for managing MCP servers, viewing real-time session metrics, configuring OAuth providers, and monitoring execution logs. The dashboard uses Vite-based frontend build system with microfrontend architecture, enabling modular UI components that communicate with the REST API backend for server state management and observability.

Metorial abstracts MCP protocol details and enables any AI model (OpenAI, Anthropic, Ollama, etc.) to call MCP server functions through a unified schema-based interface. The platform translates MCP resource/tool definitions into provider-specific function calling formats, handles parameter validation, and manages response marshaling back to the MCP protocol, enabling seamless tool use across different AI model APIs.

Metorial provides production-ready Docker Compose configuration (metorial.docker-compose.yml, engine-unified.Dockerfile) enabling self-hosted deployment of the entire platform including API services, MCP engine, database, caching layer, and frontend applications. The deployment includes environment variable templating, volume management for persistence, and networking configuration, allowing organizations to run Metorial on-premises or in private cloud environments.

Metorial uses gRPC and protocol buffers (manager.pb.go, manager_grpc.pb.go) for high-performance communication between API gateway and MCP execution engines, enabling efficient message serialization, bidirectional streaming, and service discovery. The gRPC manager service handles session lifecycle, message routing, and connection state management across distributed engine instances with automatic load balancing.

Metorial uses Prisma ORM with PostgreSQL to persist session state, message history, execution events, and server metadata. The data layer (session.go, message.go, event.go, run.go) provides type-safe database access with automatic migrations, connection pooling, and query optimization. Session data includes connection metadata, message ordering, and event timestamps for audit trails and debugging.

Metorial exposes a REST API (rest.ts) that handles client requests for server management, session creation, OAuth configuration, and marketplace operations. The API gateway routes requests to appropriate backend services (MCP engine, marketplace, authentication), transforms responses to consistent JSON format, and implements request validation and error handling. The API supports both synchronous operations (server configuration) and asynchronous operations (server deployment) with status polling.