Skip to content

Agent Mesh

docs: integrating VS Code and Copilot with a node

Antonio Ojeaf9d353f3ceb4
diff --git a/.vscode/mcp.json b/.vscode/mcp.json
new file mode 100644
index 00000000..86a0612a
--- /dev/null
+++ b/.vscode/mcp.json
@@ -0,0 +1,19 @@
+{
+ "inputs": [
+ {
+ "type": "promptString",
+ "id": "sam-api-token",
+ "description": "SAM node API token (the SAM_API_TOKEN the node was started with)",
+ "password": true
+ }
+ ],
+ "servers": {
+ "sam-mesh": {
+ "type": "http",
+ "url": "http://localhost:8080/mcp",
+ "headers": {
+ "X-Sam-Authentication": "Bearer ${input:sam-api-token}"
+ }
+ }
+ }
+}
diff --git a/agents/skills/sam-mesh/SKILL.md b/agents/skills/sam-mesh/SKILL.md
index d4bc7755..c5f1540d 100644
--- a/agents/skills/sam-mesh/SKILL.md
+++ b/agents/skills/sam-mesh/SKILL.md
@@ -138,9 +138,17 @@ All tools returned by `find_remote_tools` are namespaced. Always call
Remote MCP tools returned by `find_remote_tools` are namespaced as:
```text
-<service_name>.<tool_name>
+<scheme>://<service_name>/<tool_name>
```
+For example `mcp://everything/get-sum`. Pass the name exactly as returned to
+`describe_remote_tool` and `call_remote_tool`; do not reassemble it.
+
+Entries may carry an `error` field instead of a `description` when a peer
+advertises a service whose backend did not answer. Discovery is best-effort per
+peer, so a partly broken mesh yields a partly populated array rather than a
+failed call. Check for `error` before treating a tool as available.
+
Use the input schema from `describe_remote_tool` to build the call arguments.
Do not guess arguments if a tool cannot be described.
diff --git a/internal/node/mcp_handlers.go b/internal/node/mcp_handlers.go
index 1ceb0399..1cde1ad8 100644
--- a/internal/node/mcp_handlers.go
+++ b/internal/node/mcp_handlers.go
@@ -316,9 +316,7 @@ type remoteToolRow struct {
// - Otherwise the candidate list is obtained via DiscoverRemoteServices.
//
// Filtering:
-// - Tools without a "." in their name (infra tools) are excluded.
-// - If params.ServiceName is set, only tools whose name starts with
-// "<service_name>." are returned.
+// - If params.ServiceName is set, only tools from that service are returned.
// - params.Intent is accepted and logged at debug level, but does not
// filter or rank results in this implementation (placeholder for
// future semantic search).
diff --git a/site/content/docs/integrations/_index.md b/site/content/docs/integrations/_index.md
index 15756b3e..ecc45490 100644
--- a/site/content/docs/integrations/_index.md
+++ b/site/content/docs/integrations/_index.md
@@ -19,6 +19,7 @@ Explore the step-by-step guides to integrate SAM with your favorite AI Agent sys
- [Google Antigravity](antigravity/): Connect your local node as a remote MCP server to Google Antigravity.
- [Claude Code](claude-code/): Connect your local node as a remote MCP server to Claude Code.
- [Claude Desktop](claude-desktop/): Use SAM to expose the P2P tool mesh to Claude Desktop.
+- [VS Code and GitHub Copilot](vscode-copilot/): Register your node in `.vscode/mcp.json` and reach the mesh from Copilot's agent mode.
- [OpenClaw](openclaw/): Integrate your node as a remote tool bridge for OpenClaw.
## Connecting via MCP
diff --git a/site/content/docs/integrations/vscode-copilot.md b/site/content/docs/integrations/vscode-copilot.md
new file mode 100644
index 00000000..1d0f90e7
--- /dev/null
+++ b/site/content/docs/integrations/vscode-copilot.md
@@ -0,0 +1,446 @@
+---
+title: "Integrating SAM with VS Code and GitHub Copilot"
+linkTitle: "Integrating SAM with VS Code"
+---
+You can connect your `sam-node` to VS Code as an MCP server, so GitHub Copilot's
+agent mode can discover and call tools from anywhere on the SAM mesh.
+
+## Overview
+
+`sam-node` serves a standard Model Context Protocol endpoint over Streamable
+HTTP. VS Code is a generic MCP client, so once the server is registered its
+tools — `get_mesh_info`, `list_local_services`, `discover_remote_services`,
+`find_remote_tools`, `describe_remote_tool` and `call_remote_tool` — appear
+alongside Copilot's own.
+
+Worth being clear about what this arrangement is. Copilot connects as an
+ordinary MCP client over the node's API, not as a sandboxed agent behind a
+`sam-box`. It gets the node's tools; it does not get a per-agent policy, an
+egress allowance or a boundary. That is the right shape for a coding assistant
+on your own machine, and the wrong one for untrusted code — for that, see
+[Running agents on SAM]({{< relref "/docs/user/running-agents" >}}).
+
+## Prerequisites
+
+- A running `sam-node` serving its API (default `http://localhost:8080`). See
+ the [Quick Start]({{< relref "/docs/quickstart" >}}).
+- The node's API token — the `SAM_API_TOKEN` you started it with, or the
+ contents of `--api-token-path`.
+- VS Code with GitHub Copilot, in agent mode.
+
+## Configuration
+
+Create `.vscode/mcp.json` in your workspace:
+
+```json
+{
+ "inputs": [
+ {
+ "type": "promptString",
+ "id": "sam-api-token",
+ "description": "SAM node API token",
+ "password": true
+ }
+ ],
+ "servers": {
+ "sam-mesh": {
+ "type": "http",
+ "url": "http://localhost:8080/mcp",
+ "headers": {
+ "X-Sam-Authentication": "Bearer ${input:sam-api-token}"
+ }
+ }
+ }
+}
+```
+
+The token is deliberately not in the file. `promptString` with
+`"password": true` makes VS Code ask for it once and keep it in its own secret
+store, which means the file is safe to commit and safe to share — useful,
+because it is also the shortest description of how to attach an agent to a node.
+
+For every workspace rather than one, put the same JSON in your user-level
+`mcp.json` instead: run **MCP: Open User Configuration** from the command
+palette.
+
+`type` must be `http`. Without it the entry is read as a stdio server and will
+not load.
+
+## Start the server
+
+Creating the file is not enough, and this is the step that most often looks like
+a broken node. VS Code does not automatically run a server it has just been told
+about: it waits to be asked.
+
+Open `.vscode/mcp.json` and click the **Start** action VS Code
+shows directly above the `"sam-mesh"` entry. It will prompt for the token the
+first time.
+
+If nothing seems to happen, run **MCP: List Servers** from the command palette.
+That distinguishes the two failures cleanly:
+
+- `sam-mesh` is missing entirely — the file is not being read. Check it is at
+ `.vscode/mcp.json` in the workspace root and is valid JSON.
+- `sam-mesh` is listed but stopped — it was read and is simply waiting. Start it.
+
+A useful property of the "waiting" case is that it leaves no trace: if the
+server was never started, the MCP log has no entry for it at all, successful or
+failed. An empty log is evidence of a server that was never asked to run, not of
+one that ran and failed.
+
+## Verification
+
+Ask Copilot directly:
+
+> What does `get_mesh_info` say about this node?
+
+A healthy node reports a `router_peer_id`, a non-empty `connected_peers`, and a
+`local_api_socket`.
+
+New tools do not always appear in an in-progress chat. If Copilot claims it has
+no mesh tools while **MCP: List Servers** shows the server running, start a new
+chat, and check `sam-mesh` is ticked in the tools picker on the chat input.
+
+## Install the SAM skill
+
+The MCP tools let Copilot reach the mesh. The skill tells it when reaching for
+the mesh is the right move, and how to go about it — discover before describing,
+describe before calling.
+
+```bash
+sam-node skill install
+```
+
+This writes `~/.claude/skills/sam-mesh/SKILL.md`, which VS Code also reads.
+`sam-node skill install --project` writes it into the current repository
+instead, and `sam-node skill list` shows whether an installed copy is current:
+
+```console
+$ sam-node skill list
+SAM skill (sam-mesh):
+ outdated ~/.claude/skills/sam-mesh/SKILL.md Claude
+```
+
+Reinstall when it says `outdated`, and reload the window afterwards.
+
+## Examples
+
+Copilot decides when to reach for these. What follows is what to ask, and the
+real responses from a node attached to the public testnet — abridged where
+marked, but not otherwise tidied up.
+
+### Look at the mesh
+
+> What's the state of the mesh from this node?
+
+Calls `get_mesh_info` with `{}`:
+
+```json
+{
+ "connected_peers": [
+ "12D3KooWNuHQXgEu3fbaBPKnkPCfSsEVjNvpD5Rh3hcfGeJsDzm7",
+ "12D3KooWAjWy4GrQDq27AjXgBbKPrNgWhmmxN221mC9oAYNRcZcs"
+ ],
+ "dht_size": 3,
+ "local_api_socket": "/home/you/.config/sam-mesh/sam.sock",
+ "router_peer_id": "12D3KooWQQHDRrSfZp2S4RRTYz3pd3Fremsb5ZaP3XXg4CNZGDQj"
+}
+```
+
+Two fields are easy to misread. `connected_peers` was 18 entries long in this
+capture while `dht_size` was 3 — they count different things, so a small
+`dht_size` next to a long peer list is not a fault. And `local_api_socket` is a
+Unix socket that answers the same HTTP API without a token, because filesystem
+permissions already decide who may open it. It is the easier way to script
+against your own node.
+
+### Find out what is out there
+
+> What MCP services can this node reach?
+
+Calls `discover_remote_services` with `{"type":"mcp"}`:
+
+```json
+[
+ {"peer_id": "12D3KooWQ1hk…veSLS", "srv_name": "dummy-http",
+ "srv_description": "Canary HTTP tool (k8s agnhost)"},
+ {"peer_id": "12D3KooWFQrX…9Uwe1V", "srv_name": "everything",
+ "srv_description": "MCP everything test server (tools, resources, prompts)"},
+ {"peer_id": "12D3KooWAjWy…RcZcs", "srv_name": "everything",
+ "srv_description": "MCP everything test server (tools, resources, prompts)"}
+]
+```
+
+Note `everything` appearing twice under different peers, and `dummy-http` three
+times. Service names are not unique across the mesh and were never meant to be —
+the `peer_id` is the identity. Any step that remembers "the everything service"
+without remembering which peer will eventually talk to the wrong one.
+
+### Find tools, and read the failures
+
+> List the tools available on the mesh.
+
+Calls `find_remote_tools` with `{}`. The real answer mixes successes and
+failures in one array:
+
+```json
+[
+ {"peer_id": "12D3KooWQ1hk…veSLS", "tool_name": "mcp://dummy-http",
+ "error": "failed to connect: failed to connect client: calling \"initialize\": EOF"},
+ {"peer_id": "12D3KooWAjWy…RcZcs", "tool_name": "mcp://everything/get-sum",
+ "description": "Returns the sum of two numbers"},
+ {"peer_id": "12D3KooWAjWy…RcZcs", "tool_name": "mcp://everything/echo",
+ "description": "Echoes back the input string"}
+]
+```
+
+Discovery is best-effort per peer. Three peers advertising `dummy-http` were
+reachable enough to be listed but failed at `initialize`, and that is reported
+as an `error` field on the entry rather than failing the whole call. A partly
+broken mesh returns a partly populated array, so it is worth checking whether
+the tool you wanted came back with a `description` or an `error`.
+
+Narrow the search with `service_name` or `tool_name` when you already know the
+target; `tool_name` is served from gossip announcements and is the fastest path.
+
+### Call a tool on someone else's machine
+
+> Use the everything service on the mesh to add 2 and 3.
+
+`describe_remote_tool` first, with the peer and the namespaced name exactly as
+discovery returned them:
+
+```json
+{
+ "tool_name": "mcp://everything/get-sum",
+ "description": "Returns the sum of two numbers",
+ "input_schema": {
+ "type": "object",
+ "properties": {
+ "a": {"type": "number", "description": "First number"},
+ "b": {"type": "number", "description": "Second number"}
+ },
+ "required": ["a", "b"]
+ }
+}
+```
+
+Then `call_remote_tool` with `arguments` matching that schema — `{"a": 2, "b": 3}`
+— which returned:
+
+```text
+The sum of 2 and 3 is 5.
+```
+
+The describe step is not ceremony. Names are namespaced `scheme://service/tool`,
+not `service.tool`, and the arguments here are `a` and `b` rather than the
+`numbers` array a guess might have produced. Both are the provider's to change.
+
+### Use a model the mesh provides
+
+Inference is not an MCP tool and is never called with `call_remote_tool`.
+`discover_remote_services` with `{"type":"inference"}` inventories the providers
+— on this mesh, a vLLM TPU service and an OpenRouter proxy — but to actually use
+one you talk HTTP to the node's OpenAI-compatible facade at
+`http://localhost:8080/v1`.
+
+Over the tokenless local socket:
+
+```console
+$ curl -s --unix-socket ~/.config/sam-mesh/sam.sock http://localhost/v1/models
+{"object":"list","data":[
+ {"id":"openrouter/auto","object":"model","created":0,
+ "owned_by":"12D3KooWHfiw…8T5YP"}
+]}
+```
+
+`owned_by` is the peer serving the model. Note that two inference services were
+discovered but only one model is listed: discovery inventories services, while
+`/v1/models` lists models that answered the catalog walk. Ask for a model that
+is not in this list and it resolves to no provider and comes back 404 — so read
+the catalog rather than assuming a name.
+
+A completion is the ordinary OpenAI shape, and took 3.3s here:
+
+```bash
+curl -s --unix-socket ~/.config/sam-mesh/sam.sock \
+ http://localhost/v1/chat/completions \
+ -H 'Content-Type: application/json' \
+ -d '{"model":"openrouter/auto",
+ "messages":[{"role":"user","content":"Reply with exactly: mesh inference works"}]}'
+```
+
+Over TCP instead of the socket, add
+`-H "X-Sam-Authentication: Bearer $SAM_API_TOKEN"`. Any OpenAI SDK works too:
+point `base_url` at `http://localhost:8080/v1`.
+
+## Developing an agent against the mesh
+
+Everything above treats Copilot as a client of your node. The other half of the
+loop is writing an agent that runs *behind* a boundary, and VS Code is a
+comfortable place to do it: edit the harness in the editor, run it in a
+container with no network at all, and watch the boundary decide what it may
+reach.
+
+The example lives in `development/examples/agent-harness`. Build it with the
+repository root as the build context, because the image compiles `nano-init`
+from source:
+
+```bash
+docker build -t agent-harness -f development/examples/agent-harness/Dockerfile .
+```
+
+Start a boundary for it. `--sidecar-socket` is the node's local API socket, the
+same tokenless socket `get_mesh_info` reported, so a node you are already
+running is a node you can already develop against:
+
+```bash
+sam-box run \
+ --socket /tmp/sam-demo/agent.sock \
+ --sidecar-socket ~/.config/sam-mesh/sam.sock \
+ --bundle development/examples/agent-harness/bundle.yaml \
+ --insecure-unverified-bundle \
+ --metrics-addr 127.0.0.1:9600
+```
+
+It says what that insecure flag costs, and it is right to:
+
+```text
+WARN --insecure-unverified-bundle: this bundle is taken at its word, so
+ whoever can write it decides which agent this sandbox is
+INFO Serving agent researcher-1.prod.acme.example
+INFO Agents reach the mesh at http://mesh.sam.alt
+```
+
+That is fine on your laptop and not fine anywhere else. In production the
+bundle's claim is checked against a platform-issued credential.
+
+### Watch it bootstrap itself
+
+Now run the agent with no network:
+
+```bash
+docker run --rm \
+ --network none \
+ --cap-add NET_ADMIN \
+ --device /dev/net/tun \
+ -v /tmp/sam-demo/agent.sock:/run/agent.sock \
+ agent-harness "Use your mesh tools to find out how many peers this node is connected to."
+```
+
+`--network none` is the assertion, not the arrangement. The container has no
+interface, no resolver, no route and no credentials; `NET_ADMIN` and
+`/dev/net/tun` exist only so `nano-init` can build the single `tun0` that leads
+to the mounted socket. If this worked because the container could route
+somewhere, it would prove nothing.
+
+The real output:
+
+```text
+mesh offered model: openrouter/auto
+mesh granted 15 tools: call_remote_tool, check_connectivity, connect_peer,
+ describe_remote_tool, discover_remote_services, find_remote_tools,
+ get_mesh_info, get_network_info, get_recent_logs, get_token_info,
+ list_local_services, mesh_pubsub_broadcast, poll_messages, send_message,
+ subscribe_topic
+step 1: get_mesh_info({})
+This node is connected to **23 peers**.
+```
+
+Nothing was configured. The harness asked `mesh.sam.alt` for a model, asked it
+for tools, was granted fifteen, chose one, called it, and answered — from inside
+a container that cannot reach anything else. The catalog is answered per agent,
+so the list is not a property of the node but of who is asking.
+
+### Watch policy refuse something
+
+The bundle allows `api.github.com` and `*.githubusercontent.com`, and nothing
+else. Run a probe in the same sandbox:
+
+```bash
+docker run --rm --network none --cap-add NET_ADMIN --device /dev/net/tun \
+ -v /tmp/sam-demo/agent.sock:/run/agent.sock \
+ --entrypoint nano-init agent-harness \
+ run /run/agent.sock python -c '
+import urllib.request as u
+for url in ["https://api.github.com/zen", "https://example.com"]:
+ try:
+ r = u.urlopen(url, timeout=25)
+ print(url, "->", r.status, r.read(60))
+ except Exception as e:
+ print(url, "->", type(e).__name__, e)
+'
+```
+
+```text
+[TCP] dial 169.254.64.2:443: boundary refused: not allowed by policy
+https://api.github.com/zen -> 200 b'Responsive is better than fast.'
+https://example.com -> URLError: [Errno 104] Connection reset by peer
+```
+
+The agent sees a reset connection, which is all a denied agent should learn. The
+reason lives outside the sandbox, on the boundary, in metrics you can read while
+you develop:
+
+```console
+$ curl -s http://127.0.0.1:9600/metrics | grep sam_box_flows_total
+sam_box_flows_total{outcome="allowed",route="external"} 1
+sam_box_flows_total{outcome="allowed",route="mesh-entrypoint"} 19
+sam_box_flows_total{outcome="denied",route="unresolved"} 1
+```
+
+Nineteen mesh flows for one short run — model catalog, tool listing, the tool
+call — one allowed external flow, one denial. Editing `bundle.yaml` and
+restarting `sam-box` changes those numbers without touching the agent at all,
+which is the property worth developing against: policy is not in the code.
+
+### A trap worth knowing
+
+The harness asks the mesh for a model rather than hardcoding one, and takes the
+first the catalog offers. On a mesh offering `google/gemma-2-2b-it` first, that
+run fails:
+
+```text
+mesh offered model: google/gemma-2-2b-it
+openai.BadRequestError: Error code: 400 -
+ {'error': {'message': 'System role not supported', ...}}
+```
+
+Not a mesh fault and not a policy denial — Gemma has no system role, and the
+harness sends a system prompt. Pin a model with `-e SAM_MODEL=openrouter/auto`
+while developing, and remember that "whatever the mesh offers first" is a
+different model on different days.
+
+## Troubleshooting
+
+**401 from the server.** The token does not match the node's. It is the
+`SAM_API_TOKEN` the node was started with. VS Code caches what you typed, so
+clear it with **MCP: Reset Cached Tokens** and reconnect.
+
+**Server unreachable.** Check the node is listening:
+
+```bash
+curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/mcp
+```
+
+`401` is a healthy answer — it means the endpoint is there and wants the token.
+Connection refused means the node is not running.
+
+**Tools do not appear.** Confirm the server is actually running with **MCP:
+List Servers** — see [Start the server](#start-the-server). If it is running,
+start a new chat: a chat already in progress may not pick up newly registered
+tools.
+
+**A tool is discovered but will not run.** Look for an `error` field on the
+entry `find_remote_tools` returned. `failed to connect … calling "initialize":
+EOF` means the peer is advertising a service whose backend is not answering —
+that is the provider's problem, not yours, and another peer offering the same
+service name may well work.
+
+**No remote tools found at all.** Check `get_mesh_info` first. A `dht_size` of
+zero means the node has not found the mesh, and no amount of discovery will help
+until it has. An empty `connected_peers` means it has not even reached a router.
+
+**Everything works but nothing is sandboxed.** That is by design here — see the
+note at the top. Copilot is a client of your node, not an agent behind a
+boundary.