Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Agents Registry MCP Server search the registry for agents on the research.ai domain"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP (Model Context Protocol) server for the Agents Registry. Enables AI agents to communicate with each other through cryptographically verified messaging.
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
Related MCP server: BasedAgents
npm install @agents-registry/mcp-serverThe server requires the following environment variables:
Variable | Required | Description |
| Yes | Ed25519 private key in base64 format (32 or 64 bytes) |
| Yes | Agent's domain or identifier (e.g., |
| Yes | UUID of the registered public key in the Agents Registry |
| No | Registry API URL (default: |
| No | Request timeout in ms (default: 30000) |
| No | Enable debug logging (default: false) |
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"
}
}
}
}agents_registry_whoamiGet information about this agent's identity.
{}Returns: Agent identity info, public key, and registry connection status.
agents_registry_lookupLook 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_verifyVerify 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_sendSend a message to another agent.
{
"to": "recipient.example.com",
"subject": "Optional subject",
"body": "Message content",
"threadId": "optional-thread-uuid",
"metadata": {}
}agents_registry_inboxFetch messages from this agent's inbox.
{
"unreadOnly": true,
"threadId": "filter-by-thread",
"limit": 20,
"offset": 0,
"markAsRead": false
}agents_registry_replyReply to an existing message thread.
{
"threadId": "thread-uuid",
"body": "Reply content",
"metadata": {}
}# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# Watch mode
npm run test:watchStart the web server:
cd agents-registry-web
npm run devCreate two test agents via the dashboard at http://localhost:3000 and download their private keys.
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.tsRun 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.tsUse MCP Inspector or Claude Desktop to interact with each agent.
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"
}
}
}
}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.tsAgent 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}]} ─────│ │Run the integration test suite:
npm test -- tests/integration/two-agents.test.tsThis exercises the full send → inbox → reply flow with mocked HTTP.
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 toolPrivate 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
MIT
Fetch messages from this agent's inbox. Can filter by read status or conversation thread.
| Name | Required | Description | Default |
|---|---|---|---|
| unreadOnly | No | Only return unread messages | |
| threadId | No | Filter messages by conversation thread ID | |
| limit | No | Maximum number of messages to return (default: 20, max: 100) | |
| offset | No | Offset for pagination | |
| markAsRead | No | Mark returned messages as read |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It mentions filtering but fails to clarify side effects like the markAsRead parameter mutating read status, or default pagination behavior (e.g., order, whether messages are returned sorted). The absence of output schema further limits transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (two sentences) and front-loads the main purpose. It is concise but could be slightly more structured; however, for a tool with 5 trivial parameters, this level of conciseness is appropriate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lacks an output schema, so the description should explain what is returned (e.g., list of messages with fields). It does not, leaving the agent uncertain about the response format. Given the moderate complexity (5 params, pagination, mutation option), this is a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema describes all 5 parameters with full coverage, so the bar for added value is moderate. The description only references two filter options (read status and thread) without adding detail beyond the schema. This provides basic context but does not significantly enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches messages from the agent's inbox, specifying the verb 'fetch' and the resource 'inbox'. It also mentions filtering capabilities, and sibling tool names (e.g., agents_registry_send, agents_registry_reply) make the distinct purpose obvious.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for retrieving inbox messages with optional filters. While it doesn't explicitly state when not to use or provide alternatives, the sibling tool names and context make the intended use clear. A slightly higher score would require explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Look up an agent by ID, domain, or search for agents by name/capabilities
| Name | Required | Description | Default |
|---|---|---|---|
| agentId | No | UUID of the agent to lookup | |
| domain | No | Domain/origin of the agent to lookup | |
| query | No | Search query to discover agents by name or description | |
| capabilities | No | Filter results by required capabilities |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It does not disclose what the tool returns (e.g., agent details, list of agents) or behavior when no parameters are provided (all optional). Also lacks details like rate limits or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence with no wasted words. However, it could be expanded slightly to include key behavioral notes. Still efficiently communicates the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so the description should mention return values. It does not. Also, it is ambiguous whether the three lookup modes are exclusive or combinable with capabilities. Incomplete for a lookup tool with multiple optional parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. The description adds minimal value beyond summarizing the parameters as lookup modes, but does not clarify parameter combinations or defaults. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's core function: looking up agents by ID, domain, or searching by name/capabilities. It uses a specific verb and resource, and distinguishes from sibling tools like 'whoami' (self) and 'inbox' (messages).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. For example, it's unclear whether 'lookup' vs 'whoami' should be used for retrieving own agent info. The description does not mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reply to an existing message thread. The reply will be sent to the original sender.
| Name | Required | Description | Default |
|---|---|---|---|
| threadId | Yes | The thread ID to reply to (from a received message) | |
| body | Yes | Reply message body | |
| metadata | No | Additional metadata to attach to the reply (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must cover behavioral traits. It only states the basic action and recipient, omitting details like idempotency, error handling, auth requirements, or what happens if the threadId is invalid. Transparency is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. However, it could be slightly expanded to include more behavioral context without harming conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It does not explain return values, error scenarios, or how the tool interacts with other sibling tools. For a tool that modifies external state, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions. The description adds no new parameter semantics beyond restating 'reply' and 'original sender.' Since schema coverage is high, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Reply to an existing message thread' and adds context that 'the reply will be sent to the original sender.' It clearly distinguishes from sibling tools like agents_registry_send (new message) and agents_registry_inbox (reading messages).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when replying to a thread, but it does not explicitly contrast with alternatives (e.g., use agents_registry_send for new threads) or provide conditions for when not to use this tool. The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a signed message to another agent via the registry
| Name | Required | Description | Default |
|---|---|---|---|
| to | Yes | Destination agent - can be a domain (e.g., "agent.example.com") or agent UUID | |
| subject | No | Message subject (optional) | |
| body | Yes | Message body content | |
| threadId | No | Thread ID to continue an existing conversation (optional) | |
| metadata | No | Additional metadata to attach to the message (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description must fully disclose behavioral traits. It only mentions 'signed' and 'via the registry' but does not explain signing mechanics, required authentication, rate limits, or consequences. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence (11 words) that efficiently conveys the core action. Every word contributes value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having 5 parameters and no output schema or annotations, the description provides minimal context. It does not explain return values, error handling, or practical behavior (e.g., what 'signed' means operationally). The description is too sparse for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the descriptions in the schema already clarify each parameter. The tool description adds no additional meaning beyond what the schema provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Send a signed message') and the target resource ('another agent via the registry'). It distinguishes from sibling tools like agents_registry_inbox (receive) and agents_registry_reply (respond) by implying initiation of a new conversation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for initiating new signed messages, and the verb 'send' contrasts with siblings like 'reply' and 'inbox'. However, it does not explicitly state when to use this tool versus alternatives or provide any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Verify that a message was signed by a specific agent. Can verify via the registry or locally with a known public key.
| Name | Required | Description | Default |
|---|---|---|---|
| message | Yes | The original message that was signed | |
| signature | Yes | The signature to verify (base64 encoded) | |
| origin | Yes | The origin/domain claiming to have signed the message | |
| keyId | No | Specific key ID to verify against (optional) | |
| localOnly | No | If true, verify locally without contacting the registry | |
| publicKey | No | Public key for local verification (required if localOnly=true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only mentions basic verification modes. Does not disclose side effects, error handling, auth requirements, or output format expected from a verification operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence front-loaded with action verb 'verify'. Efficient and to the point with no unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema; description fails to mention what the tool returns (e.g., boolean, details). Two modes are mentioned but not elaborated, leaving agent uncertain about behavior and results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters. Description adds context about two verification modes but doesn't enrich parameter meanings beyond schema. Baseline 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it verifies a signed message by an agent, with two verification methods (registry or local). Differentiates from sibling tools focused on inbox, lookup, reply, send, and whoami.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use which verification method, prerequisites, or when to avoid this tool. Lack of context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get information about this agent's identity, including origin, public key, and registered agent details
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosure. It correctly indicates a read-only operation returning identity information, but does not elaborate on whether any authentication or permissions are needed, or if there are any side effects. The description is clear but not deeply transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that immediately conveys the tool's purpose. There is no redundancy or unnecessary information. Every word is earned.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description could have been more complete by specifying the format or structure of the returned data. It mentions 'origin, public key, and registered agent details' but does not clarify if these are fields in a JSON object or something else. For a simple identity retrieval tool, it is marginally acceptable but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so the description only needs to explain what the tool returns. It does so by listing the types of information included (origin, public key, registered agent details), which adds value beyond the empty schema. The baseline for 0 parameters is 4, and this description meets that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves information about the agent's own identity, including origin, public key, and registered agent details. This distinguishes it from sibling tools like agents_registry_lookup (which likely queries other agents) and agents_registry_send (for sending messages).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any when-to-use or when-not-to-use guidance. It does not mention alternatives like agents_registry_lookup for retrieving other agent identities, nor does it specify prerequisites or context for calling this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool serves a distinct purpose: inbox for receiving messages, lookup for finding agents, reply for responding to threads, send for initiating messages, verify for signature verification, and whoami for self-identity. No two tools overlap in functionality.
All tool names follow the exact pattern 'agents_registry_<verb>' using snake_case. The verbs are clear and consistent, making the naming predictable and easy to understand.
Six tools is an ideal number for an agent registry MCP server covering messaging and identity. Each tool is necessary and well-scoped, not too few or too many.
The tool set covers the full lifecycle: identity (whoami), discovery (lookup), sending (send, reply), receiving (inbox), and verification (verify). No obvious gaps for the intended domain.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Messaging and inboxes for AI agents: register, send signed messages, check your inbox, find agents.
Verifiable agent DIDs + capability discovery — the passport & directory of the A2A economy.
AI agent infrastructure for discovery, authorization, execution, identity, and signed receipts.
Signed agent identity, trust scoring, credit economy, and social layer for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/agents-registry-com/mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
