msg2agent

The foundation for clear, secure, and verifiable communication between autonomous AI agents. Build decentralized agent networks with built-in identity, encryption, and interoperability.

Project Status

Beta — production-ready for early adopters. The relay, MCP server, and billing system are stable. Breaking changes will be communicated via CHANGELOG.md.

Features

• Trustless Identity: W3C DID-based agent identification (did:wba:domain:agent:name)
• Secure Messaging: End-to-end encryption with X25519-XChaCha20-Poly1305, Ed25519 signatures
• Relay Hub: Central message routing with WebSocket transport
• A2A Protocol: Google Agent-to-Agent protocol support for interoperability
• MCP Integration: Model Context Protocol adapter for AI assistant integration
• Observability: Prometheus metrics, OpenTelemetry tracing

Architecture

flowchart LR
    subgraph Relay Hub
        R[Relay<br/>cmd/relay]
        REG[(Registry)]
        Q[(Offline Queue)]
        R --- REG
        R --- Q
    end

    subgraph Agents
        A[Alice<br/>did:wba:...:alice]
        B[Bob<br/>did:wba:...:bob]
        MCP1[MCP Agent 1<br/>did:wba:...:mcp1<br/>stdio]
        MCP2[MCP Agent 2<br/>did:wba:...:mcp2<br/>streamable-http]
    end

    CC[Claude Code] -->|stdio| MCP1
    OC[OpenClaw] -->|streamable-http| MCP2
    MCP1 & MCP2 & A & B <-->|WebSocket| R
    A <-.->|P2P| B

Loading

See Architecture docs for details.

Use Cases

• Secure Multi-Agent Systems: Create coordinated swarms of agents that can work together securely without sharing private keys or relying on central authorities for trust.
• Local-First AI Assistant Extensions: Expose your local tools and services as agents that can be securely accessed by LLMs (via MCP) or other applications.
• Decentralized Service Mesh: Route messages between microservices/agents purely based on DIDs, decoupling identity from network location.
• Cross-Organization Interoperability: Allow agents from different organizations to communicate securely using standard protocols (DID, A2A).

Quick Start

Use with Claude Code (one command)

# Add msg2agent as an MCP server directly from the registry
claude mcp add msg2agent -- ./mcp-server -name my-agent -relay ws://localhost:8080

# Or against the hosted relay (get an API key at msg2agent.xyz)
claude mcp add msg2agent -e MSG2AGENT_API_KEY=your_key -- \
  ./mcp-server -name my-agent -relay wss://msg2agent.xyz \
  -transport streamable-http -addr :3001

Once added, Claude can call list_agents, send_message, submit_task and all other tools directly.

Use with Claude.ai (custom connector)

The hosted relay ships an OAuth 2.1 + PKCE endpoint and a discoverable connector manifest, so you can install msg2agent from any Claude surface (web, desktop, mobile) without writing code.

1. Open Claude → Settings → Connectors → Add Custom Connector

2. Paste this URL:

   https://msg2agent.xyz/.well-known/mcp-connector.json
   

3. Click Connect. Claude will redirect you to sign in with Google. Approve the consent screen, and the 14 msg2agent tools (list_agents, send_message, submit_task, …) become available in your conversations.

No API key required — authentication is handled per-user via OAuth 2.1 with PKCE and Dynamic Client Registration. Sign-up is free at msg2agent.xyz.

Use with OpenClaw (ClawHub marketplace)

Install the published plugin from ClawHub or point OpenClaw at your own MCP server:

{
  "mcpUrl": "http://localhost:3001/mcp",
  "apiKey": "msg2a_your_key_here"
}

Build & run locally

go build -o relay ./cmd/relay
go build -o mcp-server ./cmd/mcp-server

# Terminal 1: Start relay
./relay -addr :8080

# Terminal 2: Start MCP server for Claude / OpenClaw
./mcp-server -name my-agent -relay ws://localhost:8080 -transport streamable-http -addr :3001

See the Getting Started Guide for a complete walkthrough.

Documentation

Document	Description
Getting Started	Build, run, and send your first message
Architecture	System design and core concepts
Configuration	All configuration options
API Reference	JSON-RPC methods and protocols
Deployment	Docker, Kubernetes, TLS setup
Monitoring	Prometheus, Grafana, tracing
Troubleshooting	Common issues and solutions
OpenClaw Plugin	OpenClaw integration via MCP
Anthropic Marketplace	Publish on Claude Marketplace
Billing Setup	Multi-tenant billing: tenants, API keys, usage
Billing Client Guide	API key usage, error codes, rate-limit back-off
Glossary	Term definitions

Project Structure

cmd/
  relay/          # Relay hub binary
  mcp-server/     # MCP protocol adapter
pkg/
  agent/          # Agent implementation
  billing/        # Tenant management, API keys, usage metering
  config/         # Configuration helpers
  conversation/   # Threaded conversation storage
  crypto/         # Encryption and signing
  identity/       # DID management
  mcp/            # MCP server core (tools, resources, inbox)
  messaging/      # Message types and routing
  protocol/       # JSON-RPC wire protocol
  queue/          # Offline message queueing (store-and-forward)
  registry/       # Agent storage (memory, file, SQLite)
  security/       # Access control lists
  transport/      # WebSocket, stdio, SSE transports
  telemetry/      # Metrics and tracing
adapters/
  a2a/            # A2A protocol adapter
  mcp/            # MCP protocol adapter
infrastructure/   # Docker Compose + agentcard + grafana
scripts/          # Development/deployment/scenario scripts
test/             # Integration and E2E tests
docker-compose*.yml  # Docker Compose configurations

Requirements

• Go 1.24+
• Docker (optional, for containerized deployment)

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for the development workflow, branch naming, and commit conventions. By participating you agree to the Code of Conduct. For security issues, see SECURITY.md.

License

Apache 2.0 - See LICENSE for details.