Connecting agents

An agent uses the mesh through the agentmesh-node that runs on its own machine. The node is an MCP server, so you can point any MCP client at it. This guide gives the configuration for the common clients and explains what the agent gets.

If a client only needs to find and call remote MCP tools, it can join without a node through the MCP registry server instead; see Without a node. The two are complementary: the node is the full member, the registry server is a light caller.

What every client needs

Three values, all printed by agentmesh-node run --daemonize:

  • The endpoint: http://127.0.0.1:8080/mcp (Streamable HTTP).
  • The token: the contents of ~/.config/agentmesh/api-token, or the AGENTMESH_API_TOKEN you started the node with. It goes in the header X-Mesh-Authentication: Bearer <token>.
  • The socket: ~/.config/agentmesh/agentmesh.sock. Anything the agent runs in a shell can use the socket without a token. This is the easier way to reach the node’s /v1 inference endpoint from scripts.

The node must be running before the client starts. MCP clients start and manage stdio servers themselves, but agentmesh-node is an HTTP server that they connect to. You can run agentmesh-node run --daemonize as often as you like, so it is safe to put it in a shell profile or to let the agent run it.

What the agent gets

Six tools:

ToolPurpose
get_mesh_infoThe routers the node holds, its connected peers, the local socket path. A quick health check.
list_local_servicesThe services this node publishes.
discover_remote_servicesThe services other nodes publish, by type (mcp, inference, a2a) and optionally by name. Returns the hosting peer ID for each.
find_remote_toolsThe tools behind MCP services, across the mesh or limited to a peer, a service, or a tool name.
describe_remote_toolThe input schema of one tool on one peer. Call this before call_remote_tool, because the provider chooses the argument names.
call_remote_toolRun a tool on a peer. Takes peer_id, the namespaced tool_name (mcp://service/tool) and arguments.

Inference is not an MCP tool. discover_remote_services with {"type":"inference"} lists providers, but to use a model you send an ordinary OpenAI request to the node’s /v1 endpoint, with base_url http://127.0.0.1:8080/v1 and the token as the API key. /v1/models lists the available models.

A2A agents are not MCP tools either. discover_remote_services with {"type":"a2a"} lists them with a local_proxy_url, and any stock A2A client works through that URL, for example the official a2a CLI, whose own skill teaches an agent the protocol. The node API reference shows the call.

Two things an agent should know (the skill below tells it): service names are not unique across the mesh, so the peer ID identifies a provider, and discovery is best-effort per peer, so on a partly reachable mesh some entries come back with an error field next to the good ones.

The skill

Tools tell an agent what it can do. A skill tells it when and how to use them. agentmesh-node ships one:

agentmesh-node skill install            # ~/.claude/skills/agentmesh/ and ~/.gemini/config/skills/agentmesh/
agentmesh-node skill install --project  # ./.claude/skills/ and ./.agents/skills/ in the current repository
agentmesh-node skill install --dir DIR  # anywhere else
agentmesh-node skill list               # where it is installed and whether it is current
agentmesh-node skill show               # print it, for a harness with its own layout

Reinstall the skill after you upgrade agentmesh-node. list says outdated when the installed copy differs from the one in the binary. Restart the client afterwards so that it loads both the skill and the tools.

Claude Code

claude mcp add --transport http agentmesh http://127.0.0.1:8080/mcp \
  --header "X-Mesh-Authentication: Bearer <token>"

The default scope is the current project. --scope user makes the server available everywhere, and --scope project writes a shareable .mcp.json. The equivalent file entry, where type is required:

{
  "mcpServers": {
    "agentmesh": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": { "X-Mesh-Authentication": "Bearer <token>" }
    }
  }
}

claude mcp list should report the server as connected. Tools load at session start. /mcp inside a session shows them, and /skills shows agentmesh-p2p once the skill is installed.

Google Antigravity

Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "agentmesh": {
      "serverUrl": "http://127.0.0.1:8080/mcp",
      "headers": { "X-Mesh-Authentication": "Bearer <token>" }
    }
  }
}

Antigravity picks up the change without a restart. agentmesh-node skill install writes the skill to Antigravity’s global skills directory. --project writes it to .agents/skills/ in the workspace instead.

VS Code and GitHub Copilot

Create .vscode/mcp.json in the workspace. VS Code asks for the token once and keeps it in its secret store, so the file is safe to commit:

{
  "inputs": [
    { "type": "promptString", "id": "agentmesh-api-token",
      "description": "Agent Mesh node API token", "password": true }
  ],
  "servers": {
    "agentmesh": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp",
      "headers": { "X-Mesh-Authentication": "Bearer ${input:agentmesh-api-token}" }
    }
  }
}

VS Code does not start a newly declared server on its own. Open the file and use the Start action shown above the entry, or run MCP: List Servers from the command palette. A server listed as stopped was read correctly and is waiting to be started. If you entered a wrong token, clear it with MCP: Reset Cached Tokens. New tools may not appear in a chat that is already in progress. Start a new chat and check that agentmesh-p2p is ticked in the tools picker. To use the server in all workspaces, put the same JSON in the user-level configuration (MCP: Open User Configuration). Copilot reads ~/.claude/skills/, so the default skill install applies.

Claude Desktop

Claude Desktop launches stdio servers only, so it needs a bridge. mcp-remote is a small stdio-to-HTTP proxy that Claude Desktop can launch. Add it to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):

{
  "mcpServers": {
    "agentmesh": {
      "command": "npx",
      "args": [
        "mcp-remote", "http://127.0.0.1:8080/mcp", "--allow-http",
        "--header", "X-Mesh-Authentication: Bearer <token>"
      ]
    }
  }
}

--allow-http is needed because the node serves plain HTTP on loopback. Quit and reopen Claude Desktop. The tools appear under the connectors icon. On Windows the command may need to be npx.cmd. Claude’s cloud-hosted “custom connectors” cannot reach a node on your machine, so use the bridge.

OpenClaw

openclaw mcp set agentmesh '{
  "url": "http://127.0.0.1:8080/mcp",
  "headers": { "X-Mesh-Authentication": "Bearer <token>" }
}'
openclaw mcp list

Restart the OpenClaw gateway after adding it.

Your own code

Any MCP SDK works. In Python, with the official mcp package (2.x):

import httpx
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client

http = httpx.AsyncClient(headers={"X-Mesh-Authentication": "Bearer <token>"})
async with streamable_http_client("http://127.0.0.1:8080/mcp", http_client=http) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()

site/content/docs/snippets/agent_demo.py in the repository is a complete version of this example. For inference, point any OpenAI SDK at http://127.0.0.1:8080/v1 with the token as api_key, or at the socket with no key.

To join the mesh directly from inside an agent process without an agentmesh-node sidecar, see the Embedded Go SDK (sdk/meshnet) and the Native SDKs for JavaScript and Python.

Without a node: the MCP registry server

The official MCP registry lists io.github.google/agentmesh, a stdio MCP server from the npm package @agentmesh-p2p/sdk. The client launches it like any other stdio server. It enrolls with the control plane as its own member, so no agentmesh-node runs beside it:

{
  "mcpServers": {
    "agentmesh": {
      "command": "npx",
      "args": ["--yes", "@agentmesh-p2p/sdk@<version>"],
      "env": {
        "AGENTMESH_CONTROL_PLANE_URL": "https://mesh.example.com",
        "AGENTMESH_BOOTSTRAP_TOKEN_PATH": "/absolute/path/to/join-token",
        "AGENTMESH_STATE_DIR": "/absolute/path/to/this-client-identity"
      }
    }
  }
}

VS Code takes the same entry under servers in .vscode/mcp.json, with "type": "stdio". Node.js 22.18 or later is required, and paths must be absolute because MCP clients do not expand ~.

  • Credential: your mesh operator gives you the control plane URL and a bootstrap token file. Use AGENTMESH_JWT_PATH instead for a workload or OIDC token file. Set one of them for the first run; the server saves its identity in AGENTMESH_STATE_DIR (default ~/.config/agentmesh/mcp) and resumes from it afterwards. Use one state directory per client and mesh.
  • Plain HTTP is accepted only for a loopback control plane, unless you set AGENTMESH_INSECURE_CONTROL_PLANE=true on a network you trust.

It offers the node’s caller tools: get_mesh_info, discover_remote_services, find_remote_tools, describe_remote_tool and call_remote_tool. It publishes nothing, so there is no list_local_services, and it has no /v1 endpoint or socket. Use the node to publish services, call inference over HTTP, or share one identity among several clients. The JavaScript SDK README covers running it from a source checkout and its limits.

A note on trust

A client configured this way is a client of your node. It holds the node’s token and gets everything that the node’s credential grants. That is the right arrangement for an assistant on your own machine. Code that you do not trust should not be able to reach the node’s API at all. The sandboxed agents preview covers that case.

When it does not work

  • 401: the header value does not match the node’s token. Over the socket no token is needed. Over TCP it is required.
  • Connection refused: the node is not running, or it is bound to another address. If curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/mcp answers 401, the endpoint is up.
  • Node in WSL or in a container: the client runs on the host, so bind the node to an address the host can reach (--bind-addr 0.0.0.0:8080) or forward the port.
  • No remote tools: check get_mesh_info first. An empty attached_routers means the node has not been admitted by a router yet, and it has nobody to ask.
  • A tool is listed with an error: the provider’s backend is not answering. Another peer that offers the same service name may work.