Affected area
- Rust core runtime
- Python binding
- Middleware or guardrails
- Plugins
- Observability or exporters
- Framework integrations
- Documentation or examples
Proposed target release: 0.7
Related foundational proposals:
Problem or opportunity
Many applications execute tools through MCP clients or harness-native abstractions rather than Relay managed-tool APIs. The agent and tool server may run in different processes with independent Relay runtimes.
Today there is no reusable adapter pattern that preserves both:
- Tool-call semantics such as name, arguments, call ID, structured result, and error status.
- Causal context linking the remote tool execution to the initiating agent or LLM scope.
LLM request codecs can recognize provider tool-use structures after they have been encoded into a model request, but they cannot reconstruct execution metadata or distributed parentage that the harness has already discarded.
Relay should provide adapter APIs and reference mappings. It should not own application transport or operate as a mandatory MCP proxy.
Proposed enhancement
Provide reusable MCP and harness adapter helpers that map external tool protocols into Relay lifecycle and annotation APIs.
For MCP, the adapter should preserve:
Provide at least one reference integration demonstrating an agent-side caller and a separately instrumented tool server. The caller or application chooses an authenticated transport for correlation context, such as application headers or protocol metadata.
Adapters must apply existing Relay sanitization and must not automatically trust externally supplied parent identifiers or arbitrary metadata.
Runtime contract and binding impact
Core should expose transport-neutral building blocks. Rust and Python should receive reference adapter support first because they are common MCP integration surfaces. Other bindings can adopt the same serialized contracts incrementally.
An application that does not use MCP should be able to implement the same adapter pattern for its harness-specific tool abstraction without depending on MCP packages.
Alternatives considered
- A mandatory Relay MCP proxy would add deployment, trust, and availability requirements.
- Cross-instance Relay IPC or a leader process would make application topology a Relay concern.
- Provider request codecs observe tool messages too late to guarantee execution provenance.
- JSON-RPC request IDs correlate one protocol exchange but do not establish Relay scope or distributed trace parentage.
- Content sniffing cannot safely recover discarded result status or schema.
Acceptance criteria
- A reference MCP tools/call flow emits correlated Relay tool start and end events with the correct call ID, result status, and structured content.
- A two-process example links the remote tool scope beneath an explicit external parent without direct communication between Relay runtimes.
- Protocol failures and tool execution failures remain distinguishable.
- Arbitrary JSON text is preserved as text unless a producer declares structured content.
- Untrusted parent and metadata inputs are validated and sanitized.
- No Relay proxy, shared registry, leader election, or cross-instance IPC is required.
- Documentation explains which responsibilities belong to Relay, the harness or MCP adapter, and the application transport.
Affected area
Proposed target release: 0.7
Related foundational proposals:
Problem or opportunity
Many applications execute tools through MCP clients or harness-native abstractions rather than Relay managed-tool APIs. The agent and tool server may run in different processes with independent Relay runtimes.
Today there is no reusable adapter pattern that preserves both:
LLM request codecs can recognize provider tool-use structures after they have been encoded into a model request, but they cannot reconstruct execution metadata or distributed parentage that the harness has already discarded.
Relay should provide adapter APIs and reference mappings. It should not own application transport or operate as a mandatory MCP proxy.
Proposed enhancement
Provide reusable MCP and harness adapter helpers that map external tool protocols into Relay lifecycle and annotation APIs.
For MCP, the adapter should preserve:
Provide at least one reference integration demonstrating an agent-side caller and a separately instrumented tool server. The caller or application chooses an authenticated transport for correlation context, such as application headers or protocol metadata.
Adapters must apply existing Relay sanitization and must not automatically trust externally supplied parent identifiers or arbitrary metadata.
Runtime contract and binding impact
Core should expose transport-neutral building blocks. Rust and Python should receive reference adapter support first because they are common MCP integration surfaces. Other bindings can adopt the same serialized contracts incrementally.
An application that does not use MCP should be able to implement the same adapter pattern for its harness-specific tool abstraction without depending on MCP packages.
Alternatives considered
Acceptance criteria