Skip to content

Agent Mesh

docs: update docs for HTTP SSE and add agent integration guide

google-labs-jules[bot]26a6586826fa
diff --git a/README.md b/README.md
index d20adf2e..e533aed8 100644
--- a/README.md
+++ b/README.md
@@ -55,14 +55,14 @@ Or pass a token directly:
## Local MCP Server
-Each `sam-node` exposes a Model Context Protocol (MCP) server over a Unix domain socket to allow local processes to discover the capabilities of the local agent and get information from the mesh.
+Each `sam-node` exposes a Model Context Protocol (MCP) server over HTTP Server-Sent Events (SSE) to allow local processes to discover the capabilities of the local agent and get information from the mesh.
-By default, the socket listens at `<datadir>/mcp.sock`. You can change this with the `--mcp-socket` flag.
+By default, the server listens at `127.0.0.1:8080`. You can change this with the `--bind-addr` flag.
To query the mesh info via the MCP server, you can use the `mcp-client` tool provided in the repository:
```bash
-./bin/mcp-client -socket /path/to/mcp.sock
+./bin/mcp-client -url http://127.0.0.1:8080/mcp/events
```
## Testing
diff --git a/docs/README.md b/docs/README.md
index be4b96e3..f2324ba8 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,7 +14,7 @@ The documentation here is intentionally small and aligned with what is implement
3. Persist identity in local node store
4. Run long-lived hub and node processes
5. Run local and containerized BATS tests
-6. Expose local tools and mesh info via MCP server on a Unix socket
+6. Expose local tools and mesh info via MCP server over HTTP SSE
7. Automated peer discovery via DHT and GossipSub events
## Start Here
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index 857d0fb2..e4fcd036 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -1,5 +1,6 @@
- [Overview](#/README.md)
- [Quick Start](#/quickstart.md)
+- [Agent Integration](#/agent_integration.md)
- [CLI Reference](#/cli/reference.md)
- [Testing](#/testing.md)
- [License](https://github.com/aojea/sam/blob/main/LICENSE)
diff --git a/docs/agent_integration.md b/docs/agent_integration.md
new file mode 100644
index 00000000..b3ffab5a
--- /dev/null
+++ b/docs/agent_integration.md
@@ -0,0 +1,78 @@
+# Agent Integration Guide
+
+SAM is designed to be the networking layer for autonomous AI agents. The easiest way for your agent to interact with the mesh is through the **Model Context Protocol (MCP)** exposed locally by your node.
+
+Every `sam-node` runs a local MCP server that allows agents to:
+- Discover tools available on the mesh.
+- Connect to remote peers securely.
+- Query mesh information (e.g. `get_mesh_info`).
+- Call tools remotely (via `call_remote_tool`).
+
+## Connecting via MCP
+
+The `sam-node` exposes the MCP server over HTTP Server-Sent Events (SSE). By default, it listens at `127.0.0.1:8080`.
+
+The repository provides a Python SDK (`sam-mcp-python`) which implements the MCP client.
+
+### Prerequisites
+
+You need the `sam_mcp` package installed. From the repo root, run:
+
+```bash
+pip install ./sam-mcp-python
+```
+
+### Python SDK Demo
+
+The following snippet demonstrates how to connect to the local node's MCP server, list the available tools, and call the `get_mesh_info` tool.
+
+```python
+import asyncio
+import os
+import sys
+from sam_mcp.client import SamClient
+
+async def main():
+ # Connect to the local SAM node's MCP SSE endpoint
+ # By default, sam-node listens at 127.0.0.1:8080
+ url = os.environ.get("SAM_MCP_URL", "http://127.0.0.1:8080/mcp/events")
+ print(f"Connecting to SAM Node at {url}")
+
+ try:
+ async with SamClient(server_url=url) as client:
+ # Discover available tools provided by the SAM node
+ tools = await client.get_tools()
+ print(f"Discovered {len(tools)} tools:")
+ for tool in tools:
+ print(f" - {tool.name}: {tool.description}")
+
+ # Call the get_mesh_info tool to get information about the mesh
+ print("\nCalling get_mesh_info tool...")
+ result = await client.call_tool("get_mesh_info", {})
+ print("Result:")
+ print(result)
+
+ except Exception as e:
+ print(f"Error connecting to SAM Node: {e}")
+ sys.exit(1)
+
+if __name__ == "__main__":
+ asyncio.run(main())
+```
+
+*(You can find this snippet at `docs/snippets/agent_demo.py`)*
+
+### Example Output
+
+When you run the demo while a `sam-node` is running locally, you'll see output similar to this:
+
+```
+Connecting to SAM Node at http://127.0.0.1:8080/mcp/events
+Discovered tools:
+ - get_mesh_info: Retrieve information about the mesh...
+ - call_remote_tool: Call an MCP tool on a remote agent...
+
+Calling get_mesh_info tool...
+Result:
+{'mesh_name': 'e2e-mesh', 'connected_peers': ...}
+```
diff --git a/docs/snippets/agent_demo.py b/docs/snippets/agent_demo.py
new file mode 100644
index 00000000..62c508f4
--- /dev/null
+++ b/docs/snippets/agent_demo.py
@@ -0,0 +1,31 @@
+import asyncio
+import os
+import sys
+from sam_mcp.client import SamClient
+
+async def main():
+ # Connect to the local SAM node's MCP SSE endpoint
+ # By default, sam-node listens at 127.0.0.1:8080
+ url = os.environ.get("SAM_MCP_URL", "http://127.0.0.1:8080/mcp/events")
+ print(f"Connecting to SAM Node at {url}")
+
+ try:
+ async with SamClient(server_url=url) as client:
+ # Discover available tools provided by the SAM node
+ tools = await client.get_tools()
+ print(f"Discovered {len(tools)} tools:")
+ for tool in tools:
+ print(f" - {tool.name}: {tool.description}")
+
+ # Call the get_mesh_info tool to get information about the mesh
+ print("\nCalling get_mesh_info tool...")
+ result = await client.call_tool("get_mesh_info", {})
+ print("Result:")
+ print(result)
+
+ except Exception as e:
+ print(f"Error connecting to SAM Node: {e}")
+ sys.exit(1)
+
+if __name__ == "__main__":
+ asyncio.run(main())
diff --git a/tests/e2e/docs_snippets.bats b/tests/e2e/docs_snippets.bats
new file mode 100644
index 00000000..9936857f
--- /dev/null
+++ b/tests/e2e/docs_snippets.bats
@@ -0,0 +1,61 @@
+#!/usr/bin/env bats
+
+load "lib/container_mesh.bash"
+
+setup() {
+ if ! mesh_require_docker; then
+ skip "docker not available or daemon not running"
+ fi
+
+ if [[ ! -x "./bin/sam-node" || ! -x "./bin/sam-hub" ]]; then
+ skip "missing binaries; run: make build"
+ fi
+
+ mesh_setup_env
+}
+
+teardown() {
+ if [[ "${BATS_TEST_COMPLETED:-0}" -ne 1 ]]; then
+ echo "Node 1 logs on failure (filtered):"
+ docker logs "${MESH_PREFIX}-node-1" 2>&1 | grep -i -E 'mcp|request|error|fatal|panic' || true
+ fi
+ mesh_cleanup_env
+}
+
+@test "Docs Snippets: agent_demo.py runs successfully" {
+ run mesh_start_mock_oidc
+ [[ "$status" -eq 0 ]]
+
+ run mesh_start_hub
+ [[ "$status" -eq 0 ]]
+
+ run mesh_start_node 1 "--discovery-interval 100ms --log-level debug"
+ [[ "$status" -eq 0 ]]
+
+ local node1_name="${MESH_PREFIX}-node-1"
+ mesh_wait_for_log "${node1_name}" "SAM Node Online" 20
+ mesh_wait_for_mcp_ready 1 20
+
+ # Run the agent_demo.py snippet inside a container
+ run docker run --rm \
+ --network "${MESH_NETWORK}" \
+ -v "$(pwd)/sam-mcp-python:/sam-mcp-python" \
+ -v "$(pwd)/docs/snippets:/snippets" \
+ -e PYTHONPATH=/sam-mcp-python/src \
+ -e SAM_MCP_URL="http://sam-node-1:8080/mcp/events" \
+ python:3.12 \
+ bash -c 'pip install mcp httpx && python3 /snippets/agent_demo.py'
+
+ echo "agent_demo.py output: $output"
+
+ if [[ "$status" -ne 0 ]]; then
+ echo "Node 1 logs:"
+ docker logs "${node1_name}"
+ fi
+
+ [[ "$status" -eq 0 ]]
+ [[ "$output" == *"Connecting to SAM Node at"* ]]
+ [[ "$output" == *"Discovered"* ]]
+ [[ "$output" == *"Calling get_mesh_info tool..."* ]]
+ [[ "$output" == *"Result:"* ]]
+}