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