A lightweight MCP (Model Context Protocol) server that enables Agents to emit structured messages through MCP tool call returns.
- Background
- What is Echo MCP
- Key Design Decisions
- Quick Start
- API Reference
- Examples
- Project Structure
In existing Agent systems, Agents typically communicate intermediate states, stage information, report outlines, and structured results only through natural language text. This creates several challenges:
- Clients struggle to extract specific structured data reliably
- Same-type data lacks unified schema and validation
- Business applications must extend SDKs or protocol layers to consume these messages
- Programmatic consumption of Agent outputs is unreliable with just natural language or loose JSON
Echo MCP solves this problem by providing a mechanism to carry structured messages via MCP tool call returns — without modifying the underlying ACP/SDK protocols.
Echo MCP is a structured message carrier and validation toolkit that provides three core capabilities:
- Built-in Schema Config — Maintain available schemas through a server-side config file
- Schema Discovery — Query available built-in schemas
- Echo/Emit — Receive payloads, validate against specified schemas, and return unchanged
- ❌ A business workflow engine
- ❌ An event bus
- ❌ A rendering layer protocol
- ❌ A permission management system
- ❌ A state management framework
It only provides low-level capabilities without business-layer restrictions.
Echo MCP's output is the MCP tool call return value.
- No dependency on side-effect stream items
- No additional protocol extensions required for clients
- Clients only need to observe tool returns
Echo MCP receives valid payloads and returns them unchanged:
- Input schema = Output schema
- No payload transformation, normalization, or field injection
- "Echo" means exact reproduction
- Clients cannot register new schemas at runtime
- Built-in schemas are maintained in
config/builtin-schemas.json - The same built-in schema set is available to all sessions
If a schema changes, use a new schema ID. No explicit version fields or migration mechanisms.
A built-in __schemaless__ schema ID allows unvalidated structured output:
- Useful for quick experiments, debugging, or coarse-grained structured output
- Request envelope is still validated
Echo MCP is designed for appending new structured messages, not updating previous ones.
If your business needs "updates", include identifiers in the payload (e.g., entity_id, sequence, revision) and let the client fold multiple append messages into the "current state".
- External schema expression: JSON Schema (for discovery, exchange, cross-language compatibility)
- Internal runtime validation: Zod (for TypeScript/Node.js execution efficiency)
All errors return machine-readable error codes with detailed field-level information:
{
"ok": false,
"error": {
"code": "SCHEMA_VALIDATION_FAILED",
"message": "Payload does not conform to schema...",
"schema_id": "zenlix-agent-stage-v1",
"details": [
{ "path": "/stage", "message": "must be string" }
]
}
}npx skills add https://github.com/ZenlixAI/echo-mcp --skill echo
# Clone the repository
git clone https://github.com/zenlix/echo-mcp.git
cd echo-mcp
# Install dependencies (requires pnpm)
pnpm installpnpm devThe server runs on http://localhost:3000 by default.
Open http://localhost:3000/inspector in your browser to test the server interactively.
pnpm buildpnpm testpnpm deployEcho MCP exposes 3 MCP tools:
List all built-in schemas (including built-in __schemaless__).
Input: {}
Output:
{
"schemas": [
{ "schema_id": "__schemaless__", "description": "...", "builtin": true },
{ "schema_id": "zenlix-agent-stage-v1", "description": "...", "builtin": true }
]
}Fetch the full definition of a specific schema.
Input: {"schema_id": "zenlix-agent-stage-v1"}
Output: Schema details including the full JSON Schema definition.
Validate a payload against a schema and return it unchanged.
Input:
{
"schema_id": "zenlix-agent-stage-v1",
"payload": {
"stage": "authentication",
"stage_status": "start",
"next_stage": "authorization",
"extra": {
"user_id": "u_123"
}
}
}Output:
{
"ok": true,
"schema_id": "zenlix-agent-stage-v1",
"payload": {
"stage": "authentication",
"stage_status": "start",
"next_stage": "authorization",
"extra": {
"user_id": "u_123"
}
}
}zenlix-agent-stage-v1 is defined in config/builtin-schemas.json.
Emit stage updates:
{
"schema_id": "zenlix-agent-stage-v1",
"payload": {
"stage": "authentication",
"stage_status": "running",
"next_stage": "authorization",
"extra": {
"user_id": "u_123",
"user_name": "Alice"
}
}
}{
"schema_id": "zenlix-agent-stage-v1",
"payload": {
"stage": "authorization"
}
}{
"schema_id": "__schemaless__",
"payload": {
"kind": "debug_snapshot",
"raw": { "step": "retrieval_done", "hits": 12 }
}
}zenlix-echo-mcp/
├── index.ts # Process entry point
├── config/
│ └── builtin-schemas.json # Built-in schema configuration
├── src/
│ ├── server.ts # MCP server assembly and tool registration
│ ├── echo-service.ts # Built-in schema discovery and echo protocol behavior
│ ├── builtin-schema-config.ts # Built-in schema config loader
│ └── json-schema-zod.ts # JSON Schema to Zod conversion
├── tests/
│ └── echo-service.test.ts # Protocol and behavior tests
├── docs/
│ └── design-doc.md # Comprehensive design documentation
├── AGENTS.md # AI agent navigation guide
└── package.json
- Design Document — Comprehensive product and technical design
- AGENTS.md — AI agent development guide for this repository
MIT © ZenlixAI