# Sam Mesh

> Use when local tools cannot provide a needed capability and a SAM agent mesh can: inspect mesh state, discover reachable services/tools, describe and call namespaced remote MCP tools, and reach OpenAI-compatible inference models hosted by mesh peers. Also use to set up, join, or reconnect a sam-node when its MCP tools are not callable yet.

- Skill: `google/sam-mesh` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add google/sam-mesh`
- Raw SKILL.md: https://api.skillmd.com/api/skills/google/sam-mesh/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Google (https://skillmd.com/u/google)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/google/sam-mesh

---


# SAM Agent Skill

Use this skill when local tools cannot satisfy the task and the SAM mesh can.
Prefer local tools first. Reach into the SAM mesh only for the capability needed
to complete the task.

Pick the path that matches the need:

- The `sam-node` MCP tools are not callable yet:
  [Bootstrap A Node](#bootstrap-a-node).
- The task needs a plain HTTP call to the node, such as inference or a
  `local_proxy_url`: [Talk To The Node Over HTTP](#talk-to-the-node-over-http).
- The node is up but the mesh seems broken:
  [Diagnose The Node](#diagnose-the-node).
- The task needs a remote tool or capability:
  [Inspect The Mesh](#inspect-the-mesh).
- The task needs a model completion:
  [Use Mesh Inference](#use-mesh-inference).

## Bootstrap A Node

The mesh is reached through a local `sam-node`. When its MCP tools are missing,
guide the user through these steps. Propose each shell command and let the user
approve it before running anything.

1. Check the CLI: `sam-node --help`. If it is missing, install it with
   `curl -sL https://sam-mesh.dev/install.sh | bash` or
   `go install github.com/google/sam/cmd/sam-node@latest`.
2. Start the node in the background: `sam-node run --daemonize`. It returns as
   soon as the node answers, and prints the endpoint, the API token file, the
   log file, and how to stop it. It is idempotent, so run it again whenever you
   need to confirm a node is up.
3. If step 2 reports that the node is not enrolled, run the command it prints,
   `sam-node join --headless <control-plane-url>`. In headless mode SAM now
   prefers OAuth device flow automatically when the OIDC provider supports it,
   so no pasted callback code is required: it prints a verification URL/code
   and polls until login completes. If the provider does not expose a device
   endpoint, SAM falls back to OOB code-paste flow; show the URL/code to the
   user, wait for completion, then repeat step 2. For deterministic automation,
   force the flow with `--auth-mode device` (also `oob`, `browser`, or the
   default `auto`); `--auth-mode device` fails fast if the provider has no
   device endpoint. Enrollment is a one-time step per machine.
4. Read the node API token from the file named in step 2, then register the MCP
   endpoint `http://127.0.0.1:8080/mcp` with the header
   `X-Sam-Authentication: Bearer <token>`. Claude Code:
   `claude mcp add --transport http sam-mesh http://127.0.0.1:8080/mcp --header "X-Sam-Authentication: Bearer <token>"`.
   Antigravity: add the same URL as `serverUrl` with the same header to
   `~/.gemini/config/mcp_config.json`.
5. Tell the user to restart the agent session, since MCP tools load at startup.

MCP clients need that HTTP endpoint. For everything else — shell commands and
direct HTTP calls to the node — see
[Talk To The Node Over HTTP](#talk-to-the-node-over-http): the Unix socket gets
you in without a token.

If setup is stuck in a half-configured state, ask the user before starting over:
stop the node, run `sam-node reset --all --yes` for a clean slate, then go back
to step 2. That deletes the node's identity and its PeerID, and enrolling again
needs another login, so never do it to work around an unexplained error.

Put the node API token only in the agent's MCP configuration. Do not echo it
into the transcript, and do not commit it.

## Talk To The Node Over HTTP

The MCP tools need none of this. It applies when a task needs a plain HTTP
request to the node: the OpenAI-compatible `/v1` endpoints, or a
`local_proxy_url` returned by `discover_remote_services`.

There are two ways in. Try them in this order.

**1. The Unix socket, whenever there is one.** `get_mesh_info` reports it as
`local_api_socket`, by default `~/.config/sam-mesh/sam.sock`. It serves the same
API and takes no token at all: only the user who owns the socket can connect to
it, so the filesystem has already done the authenticating. Prefer it, because no
secret reaches a command line, the shell history, or the transcript.

```bash
curl --unix-socket ~/.config/sam-mesh/sam.sock http://localhost/v1/models
```

The host in the URL is a placeholder that curl ignores once it dials a socket.

**2. The TCP endpoint, with the node API token.** Use this when `get_mesh_info`
reports no `local_api_socket`, or when that path is not reachable from where you
run, for example a node inside a container. Do not read your MCP client
configuration to recover it: those files hold the headers of every other server
you are connected to, and reading them puts all of those secrets into the
transcript. A daemonized node writes its token to
`~/.config/sam-mesh/api-token`; let curl read that file itself so the value
never appears in an argument, the shell history, or your output:

```bash
curl http://127.0.0.1:8080/v1/models -H @<(printf 'X-Sam-Authentication: Bearer %s' "$(cat ~/.config/sam-mesh/api-token)")
```

`<(...)` needs bash or zsh; in a plain `sh`, write the header line to a file
with mode 0600 and pass `-H @that-file` instead.

If the node was started with `--api-token-path` or `SAM_API_TOKEN`, ask the
user where the token lives rather than searching for it.

Never print the token or echo it into the transcript. `Authorization` is not the
node's credential: send it only when the destination service needs its own, and
it passes through to that service untouched.

## Diagnose The Node

Operator diagnostics are not MCP tools, so they never appear in the tool list.
A running node serves them under `/debug`, and the `sam-node` CLI wraps each
endpoint over the node's Unix socket — no token involved:

```bash
sam-node debug mesh-info                 # connected peers, DHT size, router peer ID
sam-node debug connectivity [peer-id]    # ping the SAM router, or a specific peer
sam-node debug network-info              # listen and observed addresses
sam-node debug token-info                # local auth token expiration and status
sam-node debug logs                      # recent log lines
sam-node debug connect-peer <multiaddr>  # manually dial a peer
```

Each command prints the endpoint's raw JSON, so it composes with `jq`. The same
data is one `curl` away when the CLI is not at hand:

```bash
curl --unix-socket ~/.config/sam-mesh/sam.sock http://localhost/debug/mesh-info
```

These endpoints answer even while the mesh is unreachable — that is the state
they exist to diagnose. When the node runs but mesh tools fail, check
`debug connectivity` for `router_error_msg` and `debug token-info` for an
expired token before restarting or re-enrolling anything.

## Inspect The Mesh

Start by understanding the local node and mesh state:

- Use `get_mesh_info` with `{}` to inspect `connected_peers`, `dht_size`, and
  `router_peer_id`.
- Use `list_local_services` with `{}` to see services registered on the local
  node.

## Discover Remote Capabilities

Use service discovery when you need to inventory reachable service providers:

- Use `discover_remote_services` with `{"type":"mcp"}`,
  `{"type":"inference"}`, or `{"type":"a2a"}`. Add `name` only when narrowing
  by service name.
- Treat `discover_remote_services` as service inventory. Non-MCP service types
  are not callable with `call_remote_tool`. For `inference://` services see
  [Use Mesh Inference](#use-mesh-inference).

Use tool discovery when you need remote MCP tools:

- Use `find_remote_tools` to discover reachable aggregated MCP tools advertised
  by remote SAM services.
- Narrow `find_remote_tools` with `service_name` or `peer_id` when you already
  know the target.
- Mesh-wide searches fetch each peer's catalog on a best-effort basis and may
  return an empty array when no reachable aggregated tools are found. Discovery
  failures or explicit `peer_id` lookup failures are returned as errors.

## Describe Before Calling

All tools returned by `find_remote_tools` are namespaced. Always call
`describe_remote_tool` before calling them with `call_remote_tool`.

Remote MCP tools returned by `find_remote_tools` are namespaced as:

```text
<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.

After `describe_remote_tool`, inspect the tool name, description, and schema
for side effects and required data. Only call read-only, low-risk tools
autonomously. Ask the user before calls that may mutate state, execute code,
access files, contact external services, spend money, or transmit sensitive or
private data. Pass only task-required data, and never include secrets unless
explicitly authorized.

## Call Remote Tools

Use `call_remote_tool` with:

- `peer_id`: the peer hosting the tool
- `tool_name`: the discovered namespaced tool name, such as
  `mcp://everything/get-sum`
- `arguments`: a JSON object whose keys match the described input schema

`arguments` must be a JSON object, not a string containing JSON.

## Use Mesh Inference

The mesh also carries `inference://` services: OpenAI-compatible model
endpoints. They are plain HTTP and are never invoked with `call_remote_tool`.

The node exposes them through an OpenAI-compatible facade on its own address:

- Base URL `http://localhost:8080/v1`, usable as `base_url` for any OpenAI SDK
  or a direct `curl`.
- `GET /v1/models` lists the models reachable across the mesh.
- `POST /v1/chat/completions` routes to a provider of the requested `model`,
  preferring a local one, and fails over between providers.
- Add `X-Sam-Required-Labels: key=value` (comma-separated, any-of) to accept
  only providers whose labels the control plane attested, for example
  `region=eu`. Enforcement is fail-closed: unattested providers are rejected
  before any request data leaves the node.

To pin one specific provider instead of letting the facade choose, call
`discover_remote_services` with `{"type":"inference"}` and send the request to
the returned `local_proxy_url` (append `/v1/chat/completions`).

Authenticate as described in
[Talk To The Node Over HTTP](#talk-to-the-node-over-http): over the socket when
there is one, otherwise with the token from your own MCP configuration. The
`/v1` endpoints also accept that token as `Authorization`, so an OpenAI SDK can
pass it as its `api_key`.

```bash
curl --unix-socket ~/.config/sam-mesh/sam.sock \
  http://localhost/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model": "<model>", "messages": [{"role": "user", "content": "..."}]}'
```

Ask the user before sending private or sensitive content to a mesh model, and
say which provider will receive it.

## Minimal Workflow

1. Confirm no local tool can satisfy the task.
2. If the `sam-node` MCP tools are unavailable, follow
   [Bootstrap A Node](#bootstrap-a-node) and stop until the user restarts the
   agent session.
3. Call `get_mesh_info` with `{}`.
4. If a local SAM service may be
   relevant, call `list_local_services` with `{}`.
5. Call `find_remote_tools` with `service_name` or `peer_id` when known. Use
   `{}` only when the user asked to inventory the mesh or no narrower target
   exists.
6. Call `describe_remote_tool` with
   `{"peer_id":"...","tool_name":"service.tool"}`.
7. Call `call_remote_tool` only when the described tool is read-only and
   low-risk, or after the user approves the exact `peer_id`, `tool_name`, side
   effects, and task-required data being sent:
   `{"peer_id":"...","tool_name":"service.tool","arguments":{...}}`.

For a model completion rather than a tool, skip steps 5-7 and follow
[Use Mesh Inference](#use-mesh-inference) instead.

## Safety And Reliability

- Do not call mesh tools when a local tool is sufficient.
- Do not guess remote tool names or arguments.
- Ask before side-effecting or sensitive remote calls.
- Do not send secrets or private data through SAM unless the user explicitly
  approves the data and destination.
- Treat remote capabilities as networked and potentially unavailable.
- Surface peer, service, discovery, schema, and tool-call errors clearly.