Agent Relay MCP Server

A Model Context Protocol (MCP) server that enables AI agents to discover and communicate with other A2A (Agent-to-Agent) enabled AI agents through the @artinet/sdk and @artinet/agent-relay.

Features

• Automatic Agent Discovery: Scans network ports to discover available agents
• Multi-Agent Orchestration: Coordinate workflows across multiple specialized agents
• Message Relay: Send messages to agents and receive responses with full task context
• Task Management: Query task status and cancel running tasks
• Agent Discovery: View and search agents by name, description, or skills

Installation

npm install @artinet/agent-relay-mcp

Usage

Commandline

npx @artinet/agent-relay-mcp [callerId] [startPort] [endPort] [scanning-threads]

Example:

npx @artinet/agent-relay-mcp my-assistant 3000 3100 10

*We recommend allocating a small port range because port scanning is resource intensive.

As an MCP Server

import { RelayServer } from "@artinet/agent-relay-mcp";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new RelayServer({
  name: "agent-relay-server",
  version: "0.0.1",
});

await server.init({
  callerId: "my-assistant-name",
  scanConfig: {
    host: "localhost",
    startPort: 3000,
    endPort: 3100,
    threads: 10,
  },
});

const transport = new StdioServerTransport();
await server.connect(transport);

Tool Reference

The server exposes six tools for agent interaction:

sendMessage

Send a message to an agent and receive a response.

| Parameter | Type | Description | | --------- | ------ | ------------------------------------------- | | agentId | string | The ID of the agent to send the message to | | message | string | The message content to send | | taskId | string | (Optional) Task ID to continue conversation |

getTask

Get the current status of a running task.

| Parameter | Type | Description | | --------- | ------ | --------------------------- | | agentId | string | The ID of the agent | | taskId | string | The ID of the task to query |

cancelTask

Cancel a running task.

| Parameter | Type | Description | | --------- | ------ | ---------------------------- | | agentId | string | The ID of the agent | | taskId | string | The ID of the task to cancel |

getAgentCard

Get detailed information about an agent, including its capabilities and skills.

| Parameter | Type | Description | | --------- | ------ | ------------------- | | agentId | string | The ID of the agent |

viewAgents

List all registered agents available to the relay.

searchAgents

Search for agents by name, description, or skills.

| Parameter | Type | Description | | --------- | ------ | ------------------------------- | | query | string | Search query (case-insensitive) |

Configuration

Environment Variables

• ARTINET_RELAY_SYNC_INTERVAL: Agent discovery sync interval in milliseconds (default: 2500)

Configuration Options

interface AgentRelayConfig {
  callerId: string; // Unique identifier for this relay instance (ensures the agent cannot call itself)
  syncInterval?: number; // Sync interval in ms (default: 2500)
  scanConfig?: {
    host?: string; // Host to scan (default: "localhost")
    startPort?: number; // Starting port (default: 3000)
    endPort?: number; // Ending port (default: 3100)
    threads?: number; // Concurrent scan threads (default: 10)
    fallbackPath?: string; // Agent card fallback path (default: "/.well-known/agent-card.json")
  };
}

How It Works

1. Discovery: The relay scans a port range (default: 3000-3100) to find agents that expose A2A endpoints
2. Registration: Discovered agents are registered and their capabilities are cached
3. Synchronization: Periodic sync keeps the agent registry up-to-date
4. Relay: Messages are forwarded to appropriate agents based on agent IDs
5. Task Management: Task status and cancellation are handled through the relay interface

Build

npm run build

Test

npm test

License

Apache-2.0

References

• MCP Specification
• A2A Protocol Documentation
• Artinet SDK