🕸️ agentkit-mesh

Agent-to-agent discovery and delegation via MCP

---

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.

Quick Start

npx agentkit-mesh

This starts an MCP server over stdio, ready to connect to Claude Desktop, OpenClaw, or any MCP client.

MCP Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "agentkit-mesh": {
      "command": "npx",
      "args": ["agentkit-mesh"]
    }
  }
}

OpenClaw

Add to your OpenClaw config:

mcp:
  agentkit-mesh:
    command: npx agentkit-mesh

Architecture

┌─────────────┐     MCP      ┌──────────────────┐
│  AI Agent A  │◄────────────►│                  │
└─────────────┘              │  agentkit-mesh   │
                             │                  │
┌─────────────┐     MCP      │  ┌────────────┐  │
│  AI Agent B  │◄────────────►│  │  Registry   │  │
└─────────────┘              │  │  (SQLite)   │  │
                             │  └────────────┘  │
┌─────────────┐     MCP      │  ┌────────────┐  │
│  AI Agent C  │◄────────────►│  │  Discovery  │  │
└─────────────┘              │  └────────────┘  │
                             │  ┌────────────┐  │
                             │  │ Delegation  │  │
                             │  └────────────┘  │
                             └──────────────────┘

MCP Tools

mesh_register

Register an agent with its capabilities.

Parameter	Type	Description
name	string	Unique agent name
description	string	What this agent does
capabilities	string[]	List of capabilities
endpoint	string	Agent's HTTP callback URL — receives POST /task (e.g. http://host:port/task)

mesh_discover

Discover 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
query	string	Search query (e.g. "budget management")
limit	number?	Max results to return

Returns agents ranked by token-overlap score with the matched capability tokens.

mesh_unregister

Remove an agent from the registry.

Parameter	Type	Description
name	string	Agent name to remove

mesh_delegate

Delegate a task to another agent by name.

Parameter	Type	Description
targetName	string	Name of the target agent
task	string	Task description to delegate
context	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.

Agent POST /task contract

The 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.

Delegating over HTTP directly

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" }'

Securing the control plane

The /v1/* routes (register, discover, delegate, …) require a shared secret. Configure it with environment variables before starting serve:

Env var	Required	Description
MESH_TOKEN	yes	Shared secret. Clients must send Authorization: Bearer <MESH_TOKEN>. If unset, all /v1/* requests return 401 (fail-closed).
MESH_CORS_ORIGIN	no	Allowed browser origin for CORS. Defaults to http://localhost:8766 (never *).

/health stays open (no auth) for liveness probes. This is a single shared bearer secret — there are no per-agent keys, scopes, or rotation.

Use Case: FormBridge

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: keyword / token-overlap matching

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.

Programmatic API

import { AgentRegistry, DiscoveryEngine, DelegationClient, createServer } from 'agentkit-mesh';

All classes are exported for direct use without the MCP server layer.

🤝 Contributing

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.

🧰 AgentKit Ecosystem

Project	Description
AgentLens	Observability & audit trail for AI agents
Lore	Cross-agent memory and lesson sharing
AgentGate	Human-in-the-loop approval gateway
FormBridge	Agent-human mixed-mode forms
AgentEval	Testing & evaluation framework
agentkit-mesh	Agent discovery & delegation	⬅️ you are here
agentkit-cli	Unified CLI orchestrator
agentkit-guardrails	Reactive policy guardrails

License

MIT © AgentKit AI