What ProtoMolt is

ProtoMolt is an ecosystem connecting gRPC, MCP, Kafka, ACP, connectors, sinks, and agent chat. Its Java engine coordinates services and agents across languages through shared protobuf contracts, with synchronous and asynchronous execution, recorded evidence, and receipts.

Overview. Run ProtoMolt as the coordinator for your services and agents. The Java engine invokes gRPC services, maps their messages, applies validation gates, and runs workflows. Kafka and connectors carry data between systems; sinks write results to their destinations. Agents participate through MCP and ACP, while the chat and task console support conversation, guidance, and review. Each participant retains its own runtime.

Coordinate services across language ecosystems

The contract defines how systems work together independently of their implementation languages. For example, a workflow can connect a Python data service, a Go processor, and a Rust search service. ProtoMolt invokes their gRPC operations and maps typed results between steps. Clients and agents can initiate and inspect that work through the platform's protocol interfaces.

Alongside Java, gRPC provides client tooling for 12 other language ecosystems: C#/.NET, C++, Dart, Go, JavaScript (Node.js), Kotlin, Objective-C, PHP, Python, Ruby, Rust, and Swift. HTTP clients can use the JSON interfaces, and agent clients can connect through MCP or ACP.

Build participating services and clients with the protobuf and gRPC tooling for their language. ProtoMolt's bundled compiler has nine generator targets; other client toolchains compile the same protobuf definitions with their own generators.

In the code: language-neutral service contract, shared request validation, RPC and action contract tests, and bundled generator targets.

flowchart TB
  contract["Shared protobuf contracts"] --> engine["ProtoMolt Java engine"]
  agents["MCP · ACP · agent chat"] --> engine
  engine --> agents
  inputs["Kafka and connectors"] --> engine
  engine --> inputs
  engine --> services["gRPC services across languages"]
  services --> engine
  engine --> sinks["Sinks · storage and downstream systems"]
  engine --> runs["Synchronous calls · asynchronous workflows and jobs"]
  runs --> evidence["Results, evidence, and receipts"]

Shared contracts connect service calls, data flows, and agent conversations. Execution can be synchronous or asynchronous, and recorded work can produce a verifiable receipt.

Synchronous and asynchronous work, with receipts

Invoke an operation and wait for its result, run a workflow directly, or submit work to durable jobs that checkpoint progress and complete asynchronously. Kafka request and event paths connect that execution to data streams. Connectors and sinks link the flow to source systems and output destinations.

Recorded workflows and delegation tasks carry execution evidence that can be exported as signed work records and verified as receipts. Recording and signing are configured parts of the execution path; a bare gRPC call does not automatically produce a receipt.

In the code: direct workflow execution, asynchronous submission, recorded execution, and receipt verification. Explore connectors and Kafka, sink libraries, and agent chat and coordination.

Protobuf libraries power the engine

A protobuf descriptor is a machine-readable description of a message. The engine uses its libraries to register descriptors, select fields, map values between message types, and validate results. They work with contracts discovered at runtime as well as generated protobuf classes. Developers can also reuse these libraries independently.

A runtime validation engine

Declare required fields, value ranges, string formats, collection limits, and rules relating several fields in the protobuf schema. ProtoMolt compiles those rules and checks messages at runtime, reporting the field and rule behind each violation. Its Java engine implements Buf's validation rules alongside ProtoMolt's annotations and CEL expressions, so the contract can be checked wherever the workflow requires it.

The same protobuf contracts also generate API descriptions. Validation constraints feed JSON Schema for tools and forms; service descriptors generate OpenAPI for HTTP clients and Swagger UI. JSON Schema translates supported constraints; OpenAPI currently describes routes and types without full validation-rule parity. Runtime validation remains the authority for the full rule set.

In the code: Java validation engine, validation-aware JSON Schema generator and tests, OpenAPI generator and tests.

Schema storage is another reusable layer. The registry stores descriptor sets and offers compatibility checking, including an optional registration gate. That gate must be configured by the host; it is not a default guarantee for every registration. The HTTP service supports Confluent-compatible Protobuf registration and lookup, plus schema-ID wire-format interoperability. See the schema guide for the supported routes and boundaries.

In the code: descriptor registry and tests; mapping and tests; validation and tests; Buf annotation adapter and tests; registry storage, optional compatibility gate, HTTP service test, and wire-format interop test.

Declare embeddings and search fields in the schema

Protobuf annotations can describe how data enters a search index. A text field can declare a chunking policy and embedding configuration: model identity, vector dimensions, similarity function, normalization, and the destination vector field. Embeddings are numeric vectors used to find similar content.

The indexing components read those annotations into a shared mapping. With a configured chunking and embedding path, the search service splits text, calls the embedding provider, and writes vectors alongside the document's text and metadata fields. A policy digest identifies the declared derivation settings. See search and indexing for how the resulting chunks and vectors are queried.

In the code: embedding and indexing annotations, annotation reader, chunking and embedding and tests, index writer and tests.

Turn existing gRPC services into agent tools

Register a reflection-capable gRPC endpoint and ProtoMolt reads its request and response descriptors, stores a service profile, and creates named actions. The host's MCP server exposes those actions as tools without generating client stubs or restarting. The same catalog can be supplied to an ACP agent; the standalone ACP agent also provides tools to reflect and invoke remote gRPC services.

Direct reflected actions take one request. For a server-streaming method they return its first reply; use the explicit invocation tools for the full stream. Client-streaming and bidirectional methods are not added as direct actions. ProtoMolt's own typed gRPC service provides a generic invocation route for registered services.

External service discovery: reflected action registration, method invocation, and external-service tests.

In the code: gRPC catalog bridge and tests; MCP server and tests; ACP catalog agent and tests.

Three ways to use the same contracts

Select a path to follow the main steps. All three remain below when JavaScript is unavailable.

1. Correct data into a declared type

Data can arrive through Kafka, connector libraries, or gRPC calls. Kafka Connect includes topic-to-gRPC and gRPC-to-topic integration, plus message mapping and validation transforms. A workflow caller supplies the workflow request envelope and the source record it should process.

Start with a raw message and a target protobuf type. A typed workflow edge can select and project source fields into grounding for structured generation. The model fills the target form; ProtoMolt parses strict protobuf JSON and checks the target's declared validation rules. Parse or validation failures can receive bounded correction attempts. A valid shape can still need a human or a separate semantic judgment about whether its meaning is right; Jev is a proposed optional evaluator, not an integrated provider here.

Workflow evidence records fingerprints, outcomes, and masked artifacts. Raw model output and retry feedback are not persisted in that run evidence.

See the court metadata example for a custom result schema, field rules, and an explicit incomplete result that calls for review.

Data inputs: Kafka source and integration test; Kafka-to-gRPC task and tests.

In the code: typed edges and tests; structured generation and tests; run recorder and replay test.

2. Coordinate work between agents

The coordinator offers a task with an objective, allowed scope, required checks, and an optional typed deliverable. Workers exchange durable messages with the coordinator, report progress, and submit a candidate with evidence. The coordinator checks the candidate's lifecycle, reported checks, and declared deliverable before review. A reviewer can accept it, request another revision, or leave it pending.

The task console shows registered workers, offers, the conversation transcript, review controls, and receipt export. The host has adapters for Kimi, Codex, Cursor, Muse Code, Antigravity, and an OpenAI-compatible endpoint used for Muse Glimmer. Claude Code can join through the delegation MCP tools and its worker skill.

In the code: task contract, candidate checks, and deliverable tests; provider selection and host acceptance test; task console and tests.

3. Test contracts, then run stored workflows

An agent or application can discover and test gRPC methods, check their typed mappings, and compile a workflow for later execution. Give the authoring agent a task contract requiring the workflow artifact and its test evidence. The resulting runtime follows the saved definition; the agent does not have to rediscover the integration for every record.

Typed edges can project and validate data between steps. For asynchronous execution, the jobs service snapshots the submitted definition, claims work from PostgreSQL, and checkpoints progress. An interrupted step can run again before its checkpoint is saved, so side effects need idempotency. External calls and model steps retain their own behavior; compiling a workflow does not make their outputs deterministic.

From exploration to execution: workflow checking, compilation, stored-workflow test, and submission snapshot.

Recorded runs can be checked against their saved artifacts and fingerprints without calling the original service again. A signed work record lets a recipient verify the manifest and supplied artifact bytes; it does not prove that a worker's conclusion was correct.

In the code: gRPC invocation and tests; workflow runner and tests; job submission, checkpointing worker, and tests; recorded replay and tests; receipt verifier and tests.

Explore and run work in the browser

The browser console at /console brings contracts, services, workflows, agent tasks, and receipts into one workbench. Its views call the configured server's operations. The console router connects these entry points.

Author workflows. Edit a JSON definition, check it, save it to the registry, supply input, and run the stored workflow. Inspect findings, step outcomes, and typed or JSON results. The shared client also compiles definitions for receipt evaluation. Workflow editor and check, compile, and run calls.
Explore schemas. Read registered sources, compare versions, inspect types, and check compatibility. Try It builds a form from descriptors and round-trips protobuf JSON. This browser shape check does not execute the full Java validation engine or its CEL rules. Schema views and descriptor-built forms.
Connect services. Acquire descriptors through reflection, Git, or pasted protobuf sources; browse discovered services and invoke methods with request forms. Connection view, service discovery, and method invocation.
Guide agent tasks. Offer objectives and required checks, inspect workers, transcripts, and checkpoints, send guidance, and accept or revise candidates. The offer form covers acceptance checks; arbitrary typed deliverable contracts use the task API. Task console.
Inspect receipts. Export a recorded run, verify its receipt, and evaluate it against a selected stored workflow after compiling that definition. This checks recorded work against the workflow contract. Receipt view.

Agents can orient themselves through MCP by reading protomolt://workspace: it supplies server instructions, the live tool inventory, and a catalog fingerprint. MCP bootstrap implementation.

Choose the storage your work needs

The server's --demo option seeds schemas and a workflow for exploration. It creates temporary registry and workflow directories when none are supplied. Persistent use needs explicit configuration for the kinds of work you run:

Schema and workflow definitions: a Git-backed registry selected with --registry-git.
Run evidence and artifacts: a workflow workspace selected with --workflow-workspace. Recording and receipt signing need their configured paths.
Asynchronous jobs: the jobs database and worker configuration, separate from the definition registry and recorded-run workspace.
Delegation and mesh state: a repository endpoint, drive, and encryption key reference. Without the repository configuration, delegation transcripts and an enabled mesh directory remain in memory.

Configuration and demo seed: server launcher. Persistence: delegation runtime and mesh runtime. See repository storage and jobs for those services.

A composed document platform

The document-platform application assembles repository, intake, parsing, jobs, registry, search, metrics, and browser tools through Composer. Select PROTOMOLT_ROLES to run the same application as specialized nodes. The documented Compose deployment runs a platform app container alongside PostgreSQL and RustFS for its database and object storage.

That startup path requires a local Gradle installDist build before docker compose up --build. It is a source-build deployment, not a no-JDK starter using versioned images.

Implementation: service composition and role configuration. Setup: document platform, role nodes, and Compose definition.

One-command production setup is planned. The demo is an exploration starting point; persistent distributed execution requires the storage and worker configuration above.

Keep going

For the surrounding pieces, see connectors and transforms.