Click on "Deploy 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., "@agentkit-mesh discover agents that help with budget management"
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.
Agents register their capabilities, discover each other by keyword / token-overlap matching, and delegate tasks. Registration and discovery are exposed as standard MCP tools; delegation is performed over HTTP (POST /task) to each agent's registered endpoint.
npx agentkit-meshThis starts an MCP server over stdio, ready to connect to Claude Desktop, OpenClaw, or any MCP client.
Related MCP server: ARCXS Protocol MCP Server
Add to claude_desktop_config.json:
{
"mcpServers": {
"agentkit-mesh": {
"command": "npx",
"args": ["agentkit-mesh"]
}
}
}Add to your OpenClaw config:
mcp:
agentkit-mesh:
command: npx agentkit-mesh┌─────────────┐ MCP ┌──────────────────┐
│ AI Agent A │◄────────────►│ │
└─────────────┘ │ agentkit-mesh │
│ │
┌─────────────┐ MCP │ ┌────────────┐ │
│ AI Agent B │◄────────────►│ │ Registry │ │
└─────────────┘ │ │ (SQLite) │ │
│ └────────────┘ │
┌─────────────┐ MCP │ ┌────────────┐ │
│ AI Agent C │◄────────────►│ │ Discovery │ │
└─────────────┘ │ └────────────┘ │
│ ┌────────────┐ │
│ │ Delegation │ │
│ └────────────┘ │
└──────────────────┘mesh_registerRegister an agent with its capabilities.
Parameter | Type | Description |
| string | Unique agent name |
| string | What this agent does |
| string[] | List of capabilities |
| string | Agent's HTTP callback URL — receives |
mesh_discoverDiscover agents whose description / capabilities overlap with the query tokens. Matching is plain keyword / token-overlap (no embeddings or semantic search): the query is lowercased and split into tokens, and each agent is scored by the fraction of query tokens found in its description + capabilities.
Parameter | Type | Description |
| string | Search query (e.g. "budget management") |
| number? | Max results to return |
Returns agents ranked by token-overlap score with the matched capability tokens.
mesh_unregisterRemove an agent from the registry.
Parameter | Type | Description |
| string | Agent name to remove |
mesh_delegateDelegate a task to another agent by name.
Parameter | Type | Description |
| string | Name of the target agent |
| string | Task description to delegate |
| string? | Optional JSON context |
Delegation does not go over MCP. The mesh sends an HTTP POST to the target
agent's registered endpoint (its POST /task URL). Any agent that exposes such
an HTTP endpoint can participate — no MCP server required on the target side.
POST /task contractThe target agent must accept a JSON request body of the form:
{
"delegationId": "uuid",
"task": "Get budget and cost center for Engineering",
"context": { "depth": 1 },
"callbackUrl": "http://mesh-host:8766/v1/delegations/<id>/result"
}(callbackUrl is only present for async delegations.) The agent responds with one of:
Synchronous: HTTP 200 and a JSON body { "result": "..." } (or any JSON; it
is returned to the caller as the delegation result).
Asynchronous: HTTP 202 to accept the task, then later POST the result to
callbackUrl with { "status": "completed" | "failed", "result"?: ..., "error"?: ... }.
Failure: any non-2xx status; the body text is surfaced as the error.
If the registered agent has auth configured, the mesh attaches it (e.g.
Authorization: Bearer <token>) to the outgoing request.
The mesh also exposes the delegation flow over its own HTTP control plane:
agentkit-mesh serve --port 8766 # start the HTTP control plane
curl -X POST http://localhost:8766/v1/delegate \
-H "Authorization: Bearer $MESH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{ "targetName": "finance-agent", "task": "Get Engineering budget" }'The /v1/* routes (register, discover, delegate, …) require a shared secret.
Configure it with environment variables before starting serve:
Env var | Required | Description |
| yes | Shared secret. Clients must send |
| no | Allowed browser origin for CORS. Defaults to |
/health stays open (no auth) for liveness probes. This is a single shared
bearer secret — there are no per-agent keys, scopes, or rotation.
An HR agent filling an expense form discovers the Finance agent:
import { AgentRegistry, DiscoveryEngine } from 'agentkit-mesh';
const registry = new AgentRegistry();
// Agents register themselves
registry.register({
name: 'finance-agent',
description: 'Budget management and expense approval',
capabilities: ['budget', 'cost_center', 'expense_approval'],
endpoint: 'http://localhost:4002/task',
});
// HR agent discovers who can help with budget fields
const discovery = new DiscoveryEngine();
const results = discovery.discover('budget cost center', registry);
// → [{ agent: finance-agent, score: 0.67, matchedCapabilities: ['budget', 'cost', 'center'] }]See examples/ for a runnable demo.
Discovery ships as plain keyword / token-overlap matching only — there is no
embedding model or semantic search. DiscoveryEngine.discover() tokenizes the
query, scores each agent by the fraction of query tokens that appear in its
description + capabilities, and returns the matches ranked by that score.
Resource-requirement filtering (scheme/host-aware URI matching) can further
narrow results. That is the full extent of the matching algorithm.
import { AgentRegistry, DiscoveryEngine, DelegationClient, createServer } from 'agentkit-mesh';All classes are exported for direct use without the MCP server layer.
Contributions are welcome! Fork the repo, make your changes, and open a pull request. For major changes, open an issue first to discuss what you'd like to change.
Project | Description | |
Observability & audit trail for AI agents | ||
Cross-agent memory and lesson sharing | ||
Human-in-the-loop approval gateway | ||
Agent-human mixed-mode forms | ||
Testing & evaluation framework | ||
agentkit-mesh | Agent discovery & delegation | ⬅️ you are here |
Unified CLI orchestrator | ||
Reactive policy guardrails |
MIT © AgentKit AI
Delegate a task to an agent. Routes via HTTP callback to the agent's registered endpoint.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | Task to delegate | |
| targetName | Yes | Name of the target agent |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It does disclose an important behavior: the task is routed over HTTP to a previously registered endpoint. But it does not say whether the call is synchronous, asynchronous, fire-and-forget, or what happens on failure, which leaves meaningful behavioral ambiguity for an agent.
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?
Two short, purposeful sentences with no filler. The core action is front-loaded, and the routing detail adds necessary context without bloating the description.
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?
For a low-complexity tool with full parameter schema coverage, the description is usable. However, the absence of annotations and an output schema means the description should also clarify async behavior, return values, or failure semantics; those are not addressed.
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 schema covers both parameters, so the baseline is 3. The description adds value by implying targetName must correspond to an agent with a registered HTTP endpoint, which is not stated in the schema's parameter descriptions.
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 uses a specific verb and resource: 'Delegate a task to an agent.' It also adds the distinctive routing mechanism ('Routes via HTTP callback to the agent's registered endpoint'), which clearly separates this from siblings like mesh_register, mesh_discover, and mesh_unregister.
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 intended use is implied by the first sentence: use this when you want to delegate a task to an agent. However, there is no explicit guidance about when not to use it, prerequisites beyond having a registered endpoint, or how it compares to the sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover agents matching a query by capability
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results | |
| query | Yes | Search query (e.g., "code review architecture") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. 'Discover' implies a non-mutating lookup, but the description does not disclose side effects, result format, pagination behavior, failure modes, or whether any agent state is changed. It restates the basic operation without deeper behavioral context.
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?
A single sentence with no filler. The core verb, resource, and distinguishing qualifier are all present and front-loaded. Nothing extraneous is included.
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?
For a simple lookup tool with fully documented parameters, the description is minimally adequate. However, with no output schema, no annotations, and no usage guidance, an agent knows what the tool searches but not what the result looks like or when to choose it over registrations and delegation.
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%, so both parameters are already documented. The description adds the 'by capability' framing, which clarifies the intent of the query parameter, but it offers no additional meaning for 'limit' or the expected query format beyond the schema.
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?
States a specific verb ('Discover'), a resource ('agents'), and the selection criterion ('matching a query by capability'). This clearly differentiates from sibling tools like mesh_register, mesh_unregister, and mesh_delegate, which all suggest different operations.
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 the tool is for finding agents by query, but it does not explicitly state when to prefer it over siblings or when not to use it. There are no exclusions or alternative tool references, leaving usage context to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Register an agent with its capabilities and HTTP callback endpoint
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Unique agent name | |
| endpoint | Yes | HTTP callback URL (e.g., http://host:port/task) | |
| description | Yes | What this agent does | |
| capabilities | Yes | List of capabilities |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Register' implies a state-changing action, but the description does not say whether registration is idempotent, whether an existing agent with the same name is overwritten or rejected, whether authorization is required, or what response is returned.
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?
A single sentence that is front-loaded with the action and specifies the key registration contents without extra padding. It is concise and every phrase is meaningful.
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?
For a simple four-parameter registration tool, the description plus full schema coverage is minimally viable. However, with no output schema and no annotations, there is no guidance on duplicate handling, returned registration details, or prerequisites, so the description is not fully complete.
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 description coverage is 100%, so the schema already documents all four parameters adequately. The description adds no details beyond what the schema provides; it only restates capabilities and endpoint at a high level.
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 names a specific verb ('Register') and resource ('an agent') and enriches it with the registration payload scope ('capabilities and HTTP callback endpoint'). This clearly separates it from sibling tools like mesh_discover, mesh_unregister, and mesh_delegate.
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 (register an agent into the mesh) but gives no explicit when-to-use guidance or exclusions and does not mention sibling alternatives. An agent can infer the operation from the verb, but the description does not state when this tool should be preferred over mesh_unregister or mesh_delegate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unregister an agent
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Agent name to remove |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. 'Unregister' implies removal, but the description does not state whether the operation is reversible, what happens if the agent is not found, or whether it affects active delegations. This is a significant gap 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 sentence with no wasted wording. It front-loads the action and resource clearly. For such a simple tool, 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?
With no annotations, no output schema, and no additional context, the description leaves out critical operational details: error behavior, idempotency, and the effect of unregistering on related mesh entities. The agent is left to infer the consequences of the call, making the description insufficiently complete.
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 100% coverage with the property 'name' described as 'Agent name to remove'. The tool description adds no new parameter semantics beyond that, so the baseline 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 uses the specific verb 'unregister' with the resource 'agent', clearly indicating the inverse of the sibling mesh_register. Even without reading the schema, an agent can distinguish this tool from mesh_discover, mesh_delegate, and mesh_register.
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?
There is no guidance about when to use this tool versus alternatives, no mention of prerequisites (e.g., the agent must already be registered), and no exclusions. The only implied context is the action itself, which does not help an agent decide between unregistering and registering or discovering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.3.1mesh_delegatemesh_discovermesh_registermesh_unregisterScored across 4 tools
Each tool targets a clearly distinct action in the agent mesh lifecycle: registration, unregistration, discovery, and task delegation. There is no overlap between registration and discovery or between discovery and delegation, so an agent can reliably select the correct tool.
All tools use a consistent mesh_<verb> naming pattern with clear imperative verbs: discover, register, unregister, delegate. The prefix uniformly indicates the server's domain, and there are no mixed conventions or vague names.
Four tools is well-scoped for an agent mesh server: register, unregister, discover, and delegate cover the essential operations without redundancy. Each tool earns its place in the set.
The core lifecycle of registering, discovering, delegating to, and unregistering agents is covered. The only notable gap is the lack of an update/refresh operation, but this can be worked around by unregistering and re-registering an agent.
AI agent registry — search, discover, register, and connect agents via MCP.
MCP delegation fallback for AI agents to discover capabilities, knowledge, tools, and collaborators.
Discover and call AI agents via MCP. Supports A2A agents and platform agents with async tasks.
Agent-native collaboration network: orchestrate a team of long-running agents from any MCP client.
