Model Context Protocol (MCP) Integration
Relevant source files
The following files were used as context for generating this wiki page:
Model Context Protocol (MCP) Integration in Crucible provides a structured way to expose service operations as tools for Large Language Models (LLMs). The system uses the project's Intermediate Representation (IR) to generate native client bindings and metadata that allow LLMs to interact with services modelled in the .cru language. This integration ensures that API semantics, including validation, pagination, and error handling, are consistently enforced when accessed by agents.
Crucible functions as a service framework that translates service models into phased pipelines. The MCP integration specifically utilizes the crucible-wire crate to share operation descriptions and the crucible-codegen-common crate to manage doc-comment escaping and redaction rules across native clients. These components work together to provide LLMs with accurate context regarding available tools and their required parameters.
Sources: AGENTS.md:3-10, AGENTS.md:45-55
Architecture and Tool Mapping
The integration maps Crucible service operations to LLM tools by traversing the service's IR. Each operation in a .cru model is treated as a potential tool that an agent can invoke. The system generates language-specific client runtimes (e.g., Python, Go, Java, TypeScript) that handle the underlying transport, retries, and error decoding.
Core Components
| Component | Function |
|---|---|
crucible-ir | Owns the IR and release snapshot format; provides the source of truth for tool definitions. |
crucible-wire | Shares operation descriptions and modelled errors between server and client. |
crucible-codegen | Manages document and CLI output selection for external agent consumers. |
crucible-policy | Performs directional compatibility checks to ensure tool definitions remain stable for agents. |
Sources: AGENTS.md:40-75
Data Flow for Agent Interaction
The diagram shows how service models are transformed into documentation and clients used by LLM agents.
Sources: AGENTS.md:40-80, crates/crucible-codegen-kotlin/src/lib.rs:380-400
Client Generation and Tooling
Crucible generates native clients that serve as the interface for MCP tools. These clients implement specific logic for different programming languages to ensure that LLMs receive responses in the most appropriate format.
TypeScript Integration
In TypeScript, the generator qualifies named shapes and built-in types. The runtime imports Document and Unit types to handle structured data and empty responses. The generator also produces JSDoc blocks that Strike-through deprecated members, providing clear signals to LLMs about which fields are safe to use.
Sources: crates/crucible-codegen-ts/src/names.rs:10-35, crates/crucible-codegen-ts/src/names.rs:180-200
.NET (C#) Integration
The C# generator produces native .NET 8 models and asynchronous clients. It uses XML documentation tags like <summary> and <remarks> to provide tool descriptions. Requirements for operations (permissions) are rendered as sentences in the documentation, allowing agents to understand what credentials or scopes are necessary before calling a tool.
Sources: crates/crucible-codegen-csharp/src/lib.rs:140-165, crates/crucible-codegen-csharp/src/lib.rs:250-275
Kotlin Integration
Kotlin clients utilize coroutines and cold flows for pagination. The generator creates KDoc links that resolve to fully qualified names. For LLM integration, the pages_method_name provides a way for agents to walk through large datasets by following continuation tokens automatically.
Sources: crates/crucible-codegen-kotlin/src/lib.rs:160-185, crates/crucible-codegen-kotlin/src/lib.rs:410-430
Documentation for Agents
Crucible generates specialized documentation files, such as AGENTS.md and llms.txt, specifically formatted for ingestion by LLMs. These files contain compact descriptions of wire semantics, redaction rules for @sensitive data, and requirement sentences for operations.
Requirement and Permission Documentation
The system automatically generates sentences describing what an agent must hold to execute an operation. This is derived from the model's permissions definitions.
The sequence shows the agent discovery process using generated documentation before tool execution.
Sources: AGENTS.md:45-55, crates/crucible-codegen-ruby/src/lib.rs:45-65
Redaction and Sensitive Data
To protect sensitive information when interacting with LLMs, Crucible enforces redaction rules at the client level. Members marked as @sensitive in the .cru model are redacted in ToString or debug representations.
- Ruby: Sensitive members are excluded from model representations to prevent leakage in logs or LLM context.
- C#: The
ModelFormatutility redacts values of sensitive members, printing a redaction marker instead of the actual data. - Go: The
formatModelfunction uses the wire schema to identify and redact sensitive fields during serialization.
Sources: crates/crucible-codegen-ruby/src/names.rs:10-20, crates/crucible-codegen-csharp/src/lib.rs:340-355, crates/crucible-codegen-go/src/lib.rs:300-315
Conclusion
The MCP integration in Crucible ensures that LLM agents can interact with services with the same level of type safety and policy enforcement as traditional clients. By generating comprehensive metadata, requirement documentation, and language-specific clients, Crucible allows services to be safely exposed as a collection of tools for AI-driven workflows.