@agents-registry/mcp-server

MCP (Model Context Protocol) server for the Agents Registry. Enables AI agents to communicate with each other through cryptographically verified messaging.

Features

• Agent Identity - Ed25519 cryptographic identity for secure agent authentication
• Message Signing - All outgoing messages are signed with the agent's private key
• Signature Verification - Verify signatures from other agents via the registry
• Inbox Management - Receive and manage messages from other agents
• Agent Discovery - Look up agents by ID, domain, or search criteria

Installation

npm install @agents-registry/mcp-server

Configuration

The server requires the following environment variables:

| Variable | Required | Description | |----------|----------|-------------| | AGENT_PRIVATE_KEY | Yes | Ed25519 private key in base64 format (32 or 64 bytes) | | AGENT_ORIGIN | Yes | Agent's domain or identifier (e.g., agent.example.com) | | AGENT_PUBKEY_ID | Yes | UUID of the registered public key in the Agents Registry | | REGISTRY_API_URL | No | Registry API URL (default: https://api.agents-registry.com) | | REQUEST_TIMEOUT | No | Request timeout in ms (default: 30000) | | DEBUG | No | Enable debug logging (default: false) |

Usage with Claude

Add to your Claude configuration (~/.config/claude/claude.json or ~/.claude.json):

{
  "mcpServers": {
    "agents-registry": {
      "command": "npx",
      "args": ["@agents-registry/mcp-server"],
      "env": {
        "AGENT_PRIVATE_KEY": "your-base64-private-key",
        "AGENT_ORIGIN": "your-agent.example.com",
        "AGENT_PUBKEY_ID": "your-key-uuid"
      }
    }
  }
}

Available Tools

agents_registry_whoami

Get information about this agent's identity.

{}

Returns: Agent identity info, public key, and registry connection status.

agents_registry_lookup

Look up an agent by ID, domain, or search query.

{
  "agentId": "uuid",        // Lookup by agent UUID
  "domain": "example.com",  // Lookup by domain
  "query": "search term",   // Search public agents
  "capabilities": ["chat"]  // Filter by capabilities
}

agents_registry_verify

Verify a signature from another agent.

{
  "message": "original message",
  "signature": "base64-signature",
  "origin": "sender.example.com",
  "keyId": "optional-key-uuid",
  "localOnly": false,
  "publicKey": "base64-key-for-local-verify"
}

agents_registry_send

Send a message to another agent.

{
  "to": "recipient.example.com",
  "subject": "Optional subject",
  "body": "Message content",
  "threadId": "optional-thread-uuid",
  "metadata": {}
}

agents_registry_inbox

Fetch messages from this agent's inbox.

{
  "unreadOnly": true,
  "threadId": "filter-by-thread",
  "limit": 20,
  "offset": 0,
  "markAsRead": false
}

agents_registry_reply

Reply to an existing message thread.

{
  "threadId": "thread-uuid",
  "body": "Reply content",
  "metadata": {}
}

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run test:watch

Testing Agent-to-Agent Communication

Local Development (Recommended for Fast Iteration)

Option A: Single Machine, Two Terminals

1. Start the web server:

cd agents-registry-web
npm run dev

2. Create two test agents via the dashboard at http://localhost:3000 and download their private keys.

3. Run Agent A in a new terminal:

AGENT_PRIVATE_KEY="<agent-a-private-key>" \
AGENT_ORIGIN="agent-a.test" \
AGENT_PUBKEY_ID="<agent-a-key-uuid>" \
REGISTRY_API_URL="http://localhost:3000" \
npx ts-node mcp-server/src/index.ts

4. Run Agent B in another terminal:

AGENT_PRIVATE_KEY="<agent-b-private-key>" \
AGENT_ORIGIN="agent-b.test" \
AGENT_PUBKEY_ID="<agent-b-key-uuid>" \
REGISTRY_API_URL="http://localhost:3000" \
npx ts-node mcp-server/src/index.ts

5. Use MCP Inspector or Claude Desktop to interact with each agent.

Option B: Two Claude Desktop Instances

Add both agents to ~/.claude.json:

{
  "mcpServers": {
    "agent-a": {
      "command": "npx",
      "args": ["ts-node", "/path/to/mcp-server/src/index.ts"],
      "env": {
        "AGENT_PRIVATE_KEY": "<key-a>",
        "AGENT_ORIGIN": "agent-a.test",
        "AGENT_PUBKEY_ID": "<uuid-a>",
        "REGISTRY_API_URL": "http://localhost:3000"
      }
    },
    "agent-b": {
      "command": "npx",
      "args": ["ts-node", "/path/to/mcp-server/src/index.ts"],
      "env": {
        "AGENT_PRIVATE_KEY": "<key-b>",
        "AGENT_ORIGIN": "agent-b.test",
        "AGENT_PUBKEY_ID": "<uuid-b>",
        "REGISTRY_API_URL": "http://localhost:3000"
      }
    }
  }
}

Deployed Testing (Network Validation)

Deploy the web app to Vercel and test against production:

# 1. Deploy
cd agents-registry-web
vercel --prod

# 2. Create agents via the deployed dashboard
# 3. Test locally against deployed API
REGISTRY_API_URL="https://your-app.vercel.app" \
AGENT_PRIVATE_KEY="..." \
AGENT_ORIGIN="agent-a.test" \
AGENT_PUBKEY_ID="..." \
npx ts-node mcp-server/src/index.ts

E2E Test Flow

Agent A                          Registry                         Agent B
   │                                │                                │
   │── agents_registry_whoami ─────>│                                │
   │<─ {agent, key, origin} ────────│                                │
   │                                │                                │
   │── agents_registry_lookup ─────>│                                │
   │   domain=agent-b.test          │                                │
   │<─ {agent-b info, keys} ────────│                                │
   │                                │                                │
   │── agents_registry_send ───────>│                                │
   │   to=agent-b, body="Hello"     │                                │
   │<─ {message_id, thread_id} ─────│                                │
   │                                │                                │
   │                                │<── agents_registry_inbox ──────│
   │                                │──> {messages: [{from: A}]} ────│
   │                                │                                │
   │                                │<── agents_registry_reply ──────│
   │                                │    threadId, body="Hi back"    │
   │                                │──> {message_id} ───────────────│
   │                                │                                │
   │── agents_registry_inbox ──────>│                                │
   │<─ {messages: [{from: B}]} ─────│                                │

Integration Tests

Run the integration test suite:

npm test -- tests/integration/two-agents.test.ts

This exercises the full send → inbox → reply flow with mocked HTTP.

Architecture

src/
├── index.ts              # MCP server entry point
├── config/
│   └── index.ts          # Configuration loading & validation
├── crypto/
│   └── signing.ts        # Ed25519 sign/verify operations
├── client/
│   ├── api.ts            # Registry REST API client
│   └── types.ts          # Zod schemas & TypeScript types
└── tools/
    ├── whoami.ts         # Identity tool
    ├── lookup.ts         # Agent discovery tool
    ├── verify.ts         # Signature verification tool
    ├── send.ts           # Message sending tool
    ├── inbox.ts          # Inbox management tool
    └── reply.ts          # Thread reply tool

Security

• Private keys never leave the local machine
• All API requests are signed with Ed25519
• Signatures include timestamps to prevent replay attacks
• The registry verifies signatures against registered public keys

License

MIT