mcp-agentic-framework

The MCP Agentic Framework is a Node.js-based system that enables multiple AI agents to register, discover, and exchange messages asynchronously using a simple file-backed message store. It exposes an HTTP transport that allows Claude or other MCP-compatible clients to connect and participate in agent conversations, broadcasting, and targeted messaging. This server includes built-in tools for registering agents, listing currently registered agents, sending messages between agents, and checking for unread messages. To use it, start the HTTP transport and point your Claude client (or any MCP consumer) at the server's /mcp endpoint. The server's health endpoint at /health returns status information to monitor uptime and versioning.

Key capabilities include:

• register-agent: Add a new agent with a name and description.
• unregister-agent: Remove an agent from the registry.
• discover-agents: List all registered agents.
• send-message: Send a direct message from one agent to another.
• check-for-messages: Retrieve unread messages for a given agent. Messages are removed after being read.

To integrate with Claude Desktop, configure the MCP transport in ~/.claude.json to point to http://<host>:3113/mcp (default port 3113). The HTTP transport supports Server-Sent Events (SSE) for real-time updates from the MCP server.

Prerequisites:

• Node.js and npm installed on your system
• Git (optional, for cloning the repository)

Installation steps:

1. Clone the repository:

git clone https://github.com/Piotr1215/mcp-agentic-framework.git
cd mcp-agentic-framework

2. Install dependencies:

npm install

3. Run tests (optional but recommended) to verify installation:

npm test

4. Start the HTTP transport (default port 3113) and begin using the MCP server:

npm run start:http

Note: If you want to customize the port or environment, set ports or related environment variables before starting the server.

Environment and usage tips:

• The server uses a file-based storage approach for simplicity and portability. Ensure the working directory has appropriate permissions for reading/writing storage files.
• Default HTTP port is 3113. You can override by setting PORT before starting the server.
• When integrating with Claude, update your Claude configuration to point to the MCP endpoint (http://<host>:3113/mcp).
• The available tools (register-agent, unregister-agent, discover-agents, send-message, check-for-messages) can be called via the MCP API exposed by the /mcp endpoint. Ensure agents provide valid IDs and descriptions.
• If you run into issues with connectivity, check the server logs via npm run logs or your process manager’s log output to verify that the HTTP transport is listening on the expected port.
• The health endpoint at /health returns a JSON payload with status, name, and version, useful for health checks in orchestrators.