@reaatech/agent-mesh-mcp-server

Status: Pre-1.0 — APIs may change in minor versions. Pin to a specific version in production.

MCP server layer that exposes the agent-mesh orchestrator as an MCP-compliant agent. Provides JSON-RPC 2.0 message routing, tool registration (handle_message, get_session_status, list_agents), and SSE transport for legacy client compatibility.

Installation

npm install @reaatech/agent-mesh-mcp-server
# or
pnpm add @reaatech/agent-mesh-mcp-server

Feature Overview

• JSON-RPC 2.0 routing — standards-compliant method dispatch with error codes per the JSON-RPC spec
• Three MCP tools — handle_message (route user messages through the orchestrator), get_session_status (query session state), list_agents (enumerate registered agents)
• SSE transport — Server-Sent Events for legacy MCP client compatibility (GET /mcp/sse, POST /mcp/messages)
• Express middleware — drop-in mcpMiddleware for existing Express applications
• Orchestrator passthrough — delegates to handleInternalRequest from the gateway for full request pipeline execution

Quick Start

import express from "express";
import { mcpMiddleware, sseHandler, messageHandler } from "@reaatech/agent-mesh-mcp-server";
 
const app = express();
app.use(express.json());
app.use(mcpMiddleware); // Handles POST /mcp
 
app.get("/mcp/sse", sseHandler);
app.post("/mcp/messages", messageHandler);
 
app.listen(8080);

API Reference

MCP Middleware

mcpMiddleware

Express middleware that intercepts POST /mcp requests and routes them through the JSON-RPC 2.0 handler. All other requests pass through unchanged.

app.use(mcpMiddleware);

JSON-RPC Handler

handleMcpRequest(req, res): Promise<void>

Processes an MCP JSON-RPC 2.0 request. Validates the message format, dispatches to the appropriate method handler, and returns a JSON-RPC 2.0 response.

MCP Methods:

Tools Registered:

SSE Transport

sseHandler(req, res): Promise<void>

Establishes a Server-Sent Events (GET /mcp/sse) connection for legacy MCP clients. Accepts an optional sessionId query parameter.

app.get("/mcp/sse", sseHandler);

messageHandler(req, res): Promise<void>

Handles incoming MCP messages via POST /mcp/messages?sessionId=<id>. If a matching SSE connection exists, the message is forwarded to the client.

app.post("/mcp/messages", messageHandler);

sendToClient(sessionId, message): boolean

Sends a message to a connected SSE client. Returns false if no connection exists for the given session ID.

closeSseConnection(sessionId): boolean

Force-closes an SSE connection for a given session.

getActiveConnectionCount(): number

Returns the number of currently active SSE connections.

Message Types

McpMessage

interface McpMessage {
  jsonrpc: "2.0";
  id: string | number | null;
  method: string;
  params?: unknown;
}

McpResponse

interface McpResponse {
  jsonrpc: "2.0";
  id: string | number | null;
  result?: unknown;
  error?: {
    code: number;
    message: string;
  };
}

Error Codes (JSON-RPC 2.0 standard):

Usage Patterns

As a Standalone MCP Server

import express from "express";
import { mcpMiddleware, sseHandler, messageHandler } from "@reaatech/agent-mesh-mcp-server";
 
const app = express();
app.use(express.json());
app.use(mcpMiddleware);
 
app.get("/mcp/sse", sseHandler);
app.post("/mcp/messages", messageHandler);
 
app.listen(8080);

Integration with the Full Orchestrator

import express from "express";
import { authMiddleware, healthCheck, handleRequest } from "@reaatech/agent-mesh-gateway";
import { mcpMiddleware, sseHandler, messageHandler } from "@reaatech/agent-mesh-mcp-server";
 
const app = express();
app.use(express.json());
app.use(mcpMiddleware);
 
app.get("/health", healthCheck);
 
// MCP endpoints (can optionally apply auth)
app.get("/mcp/sse", authMiddleware, sseHandler);
app.post("/mcp/messages", authMiddleware, messageHandler);
 
// Direct HTTP API
app.post("/v1/request", authMiddleware, handleRequest);
 
app.listen(8080);

Programmatic Tool Calls

import { handleMcpRequest } from "@reaatech/agent-mesh-mcp-server";
 
// Simulate an MCP tool call
const req = {
  body: {
    jsonrpc: "2.0",
    id: "req-1",
    method: "tools/call",
    params: {
      name: "handle_message",
      arguments: {
        input: "Reset my password",
        employee_id: "emp-123",
      },
    },
  },
} as any;
 
await handleMcpRequest(req, res);

Related Packages

• @reaatech/agent-mesh-gateway — Entry handler (delegated to via handleInternalRequest)
• @reaatech/agent-mesh-registry — Agent listing (for list_agents tool)
• @reaatech/agent-mesh-session — Session queries (for get_session_status tool)

License

MIT