Content
# MXP (Mesh eXchange Protocol)
**The high-performance open implementation for AI agent communication**
*A2A-compatible • 37x faster than JSON • Built-in observability • Open source*
[](LICENSE)
[](https://crates.io/crates/mxp)
[](https://docs.rs/mxp)
> **📄 [Read the Whitepaper](WHITEPAPER.md)** | 🌐 [Visit getmxp.xyz](https://getmxp.xyz)
---
## The Vision: Be the Linux of Agent Protocols
In 1999, Linux seemed hopeless against Windows. Today, Linux runs:
- 100% of the top 500 supercomputers
- 96% of the world's top web servers
- Every major cloud platform
- 3 billion Android devices
**Linux didn't win by fighting Windows. It won by enabling everything else.**
MXP takes the same approach to AI agent protocols. We don't fight standards—we implement them *better* and enable others to build the future.
---
## What is MXP?
MXP is an **open, high-performance binary protocol** for agent-to-agent communication that:
- **Works with existing standards** - A2A-compatible semantics, MXP performance
- **Enables, not competes** - Use MXP as your transport layer, keep your APIs
- **Delivers real performance** - 37x faster than JSON, verified benchmarks
- **Provides built-in observability** - Trace ID in every message, no instrumentation needed
- **Stays open source** - MIT/Apache-2.0 licensed, public domain spec
### The Enabler Philosophy
```
┌─────────────────────────────────────────────────────┐
│ Your Agent Framework / A2A │
│ (Keep your existing semantics) │
└─────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ MXP Protocol Layer │
│ (High-performance encoding, built-in tracing) │
└─────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ MXP Transport Layer │
│ (Custom UDP, encryption, reliability, streaming) │
└─────────────────────────────────────────────────────┘
```
**MXP makes your agents faster without changing your code.**
---
## Why MXP?
### For Developers: Drop-In Performance
```rust
// Before: HTTP/JSON
let response = client.post("/agent/call")
.json(&payload)
.send().await?; // ~2,262ns encode + network
// After: MXP (same semantics, 37x faster encoding)
let response = mxp_client
.call(payload)
.await?; // ~60ns encode + network
```
### For Architects: The Best of Both Worlds
| What You Get | How |
|--------------|-----|
| **Standard compatibility** | A2A message semantics supported |
| **37x faster encoding** | Binary protocol, zero-copy design |
| **Built-in tracing** | Every message has trace context |
| **Streaming support** | Native LLM token streaming |
| **Open source** | No vendor lock-in, fork freely |
### For Enterprises: Production-Ready
- **Gradual adoption** - Start with gateway, migrate incrementally
- **Observability** - Traces and metrics without instrumentation
- **Security** - ChaCha20-Poly1305/AES-GCM encryption, X25519 key exchange
- **Open governance** - Community-driven, foundation-ready
---
## Quick Start
### Installation
```bash
cargo add mxp
```
### Basic Usage
```rust
use mxp::{Message, MessageType};
// Create a message
let message = Message::new(MessageType::Call, b"Hello, agent!");
// Encode to bytes (37x faster than JSON)
let bytes = message.encode();
// Decode from bytes
let decoded = Message::decode(bytes)?;
// Built-in trace context - no instrumentation needed
println!("Trace ID: {}", decoded.trace_id());
```
### A2A Compatibility (Google's Agent Protocol)
```bash
cargo add mxp --features a2a
```
```rust
use mxp::a2a::{Message, Role, Part, to_mxp, from_mxp, AgentCard};
// Create an A2A message
let msg = Message::user_text("Search for Rust tutorials");
// Convert to MXP for high-performance transport
let mxp_msg = to_mxp(&msg)?;
// Send over MXP transport (37x faster than JSON-RPC)
transport.send(mxp_msg).await?;
// Receive and convert back to A2A
let (method, a2a_msg, task) = from_mxp(&received)?;
```
**Use A2A semantics with MXP performance.** See the [A2A Compatibility Guide](docs/a2a-guide.md) for details.
#### Run the Examples
```bash
# Simple chat agent
cargo run --example a2a_chat --features a2a
# LLM token streaming (78% smaller than JSON!)
cargo run --example a2a_streaming --features a2a
# Agent discovery with AgentCards
cargo run --example a2a_discovery --features a2a
# Task workflow with status updates
cargo run --example a2a_task_workflow --features a2a
# Multi-agent coordination
cargo run --example a2a_multi_agent --features a2a
```
📚 **[See the Cookbook](docs/cookbook.md)** for complete recipes and patterns.
### With Transport
```rust
use mxp::{Transport, TransportConfig};
use std::net::SocketAddr;
let transport = Transport::new(TransportConfig::default());
let handle = transport.bind("127.0.0.1:9000".parse()?)?;
// Send and receive with encryption, reliability, and tracing
let mut buffer = handle.acquire_buffer();
handle.receive(&mut buffer)?;
```
See [examples/](examples/) for complete working examples.
---
## Performance
**Verified benchmarks** (macOS, Apple Silicon, Rust 1.85, Criterion 0.5):
### Codec Performance (256-byte messages)
| Protocol | Time | vs MXP |
|----------|------|--------|
| **MXP** | **60ns** | **baseline** |
| Bincode | 221ns | 3.7x slower |
| MessagePack | 1,178ns | 19.5x slower |
| JSON | 2,262ns | **37.5x slower** |
### Throughput
| Payload | Encode Rate | Decode Rate |
|---------|-------------|-------------|
| 256B | 37M msg/s | 73M msg/s |
| 1KB | 22M msg/s | 32M msg/s |
| 4KB | 7M msg/s | 10M msg/s |
**Reality check**: Network bandwidth becomes the bottleneck before CPU. These numbers matter for high-frequency agent coordination, heartbeats, and LLM token streaming.
```bash
# Run benchmarks yourself
cargo bench --bench codec
open target/criterion/report/index.html
```
---
## Migration Path
### Day 1: Gateway Mode (No Code Changes)
```
Your Agents (HTTP/JSON) ──→ MXP Gateway ──→ MXP Network
(automatic conversion)
```
### Day 30: Hybrid Mode
```
New Agents (MXP native) ──→ MXP Network
Legacy Agents (HTTP) ──→ MXP Gateway ──→ MXP Network
```
### Day 90: Full MXP
```
All Agents (MXP native) ──→ MXP Network
(maximum performance)
```
**You can adopt MXP incrementally. No big bang migration required.**
---
## Key Features
### Agent-Native Operations
First-class message types for agent lifecycle:
```
0x01 - AgentRegister Register agent with mesh
0x02 - AgentDiscover Discover agents by capability
0x03 - AgentHeartbeat Keep-alive / health check
0x10 - Call Synchronous RPC
0x11 - Response Response to Call
0x12 - Event Async event (fire-and-forget)
0x20 - StreamOpen Open stream (LLM tokens, etc.)
0x21 - StreamChunk Stream data chunk
0x22 - StreamClose Close stream
```
### Built-in Observability
Every message includes trace context automatically:
```rust
// No instrumentation code needed
let msg = Message::new(MessageType::Call, payload);
// msg.trace_id() is automatically populated
// msg.message_id() enables request correlation
```
### Native Streaming
Optimized for LLM token streams:
```rust
// Open a stream for token-by-token delivery
let stream = agent.stream_open(target_agent).await?;
// Send tokens as they're generated
for token in llm.generate() {
stream.send_chunk(token).await?;
}
stream.close().await?;
```
### Security
- **Handshake**: Noise IK-inspired with X25519 key exchange
- **Encryption**: ChaCha20-Poly1305 / AES-GCM (AEAD)
- **Anti-Replay**: Packet number tracking
- **Session Resumption**: Fast reconnection with tickets
---
## Protocol Specification
| Property | Value |
|----------|-------|
| Magic Number | `0x4D585031` ("MXP1") |
| Header Size | 32 bytes (cache-aligned) |
| Checksum | XXHash3 (64-bit) |
| Transport | UDP with reliability layer |
| Encryption | ChaCha20-Poly1305 / AES-GCM |
| Default Port | 9000 |
| Max Payload | 16 MB |
See [SPEC.md](SPEC.md) for the complete wire format specification.
---
## Ecosystem & Roadmap
### Current Status
- ✅ **Core protocol** - Production-ready Rust implementation
- ✅ **Transport layer** - UDP with encryption, reliability, streaming
- ✅ **Benchmarks** - Verified performance claims
- ✅ **A2A compatibility layer** - Google A2A semantics over MXP transport
### In Progress
- 🚧 **JavaScript/TypeScript SDK** - Browser + Node.js support
- 🚧 **HTTP/WebSocket gateway** - Bridge for gradual adoption
### Planned
- 📅 **Python SDK** - Q2 2026
- 📅 **Go SDK** - Q3 2026
- 📅 **MXP Stack** - One-command agent infrastructure deployment
- 📅 **Foundation governance** - Neutral home for the project
### The Goal
**Year 1**: Be the "fast alternative" - Compatible, faster
**Year 2**: Be the "default for performance" - When speed matters, use MXP
**Year 3**: Be the "obvious choice" - Why would you use anything else?
---
## Comparison
### vs HTTP/JSON
| | MXP | HTTP/JSON |
|-|-----|-----------|
| **Encoding** | 60ns | 2,262ns (37x slower) |
| **Overhead** | 40 bytes | 100-500+ bytes |
| **Tracing** | Built-in | Requires instrumentation |
| **Streaming** | Native | SSE (clunky) |
### vs gRPC
| | MXP | gRPC |
|-|-----|------|
| **Transport** | Custom UDP | HTTP/2 over TCP |
| **Agent primitives** | Built-in | None |
| **Tracing** | Mandatory | Optional |
| **Dependencies** | Minimal | Heavy |
### vs A2A
| | MXP | A2A (Google) |
|-|-----|--------------|
| **Semantics** | Compatible | Standard |
| **Performance** | 37x faster | HTTP-based |
| **Governance** | Open source | Google-led |
| **Position** | Implementation | Specification |
**MXP and A2A are complementary, not competing.** Use A2A semantics with MXP transport.
---
## Contributing
MXP is open source and community-driven. We welcome:
- 🌍 **SDK implementations** in other languages
- 🔧 **Protocol enhancements** and extensions
- 📖 **Documentation** improvements
- 🐛 **Bug reports** and test cases
- 💡 **Ideas** for the roadmap
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
---
## License
**Protocol Specification**: Public domain (CC0)
**Reference Implementation**: MIT OR Apache-2.0
This means:
- ✅ Anyone can implement MXP in any language
- ✅ Commercial use without restrictions
- ✅ No attribution required for protocol implementation
- ✅ Fork and extend freely
---
## Community
- 🌐 **Website**: [getmxp.xyz](https://getmxp.xyz)
- 📄 **Whitepaper**: [WHITEPAPER.md](WHITEPAPER.md)
- 📋 **Specification**: [SPEC.md](SPEC.md)
- 🐦 **Twitter**: [@mxp_protocol](https://twitter.com/mxp_protocol)
- 📧 **Email**: protocol@getmxp.xyz
- 🐛 **Issues**: [GitHub Issues](https://github.com/yafatek/mxp-protocol/issues)
---
## Enterprise
For enterprise adoption, partnerships, and support:
- 📧 **Business**: business@mxpnexus.com
- 🏢 **Compliance**: SOC2, ISO 27001, HIPAA available
- 📖 **Adoption playbook**: [docs/adoption-playbook.md](docs/adoption-playbook.md)
---
<div align="center">
**MXP: Enabling the next generation of AI agents**
*Open source • High performance • Built to last*
</div>
