Skip to content

Agent Mesh

feat(node): MCP services announce tools via mesh discovery

Antonio Ojea96d15f784c10
diff --git a/internal/node/discovery/discovery_test.go b/internal/node/discovery/discovery_test.go
index a2328df1..bfa2732c 100644
--- a/internal/node/discovery/discovery_test.go
+++ b/internal/node/discovery/discovery_test.go
@@ -233,6 +233,24 @@ func TestProviderTableIsBounded(t *testing.T) {
}
}
+func TestPeerLabels(t *testing.T) {
+ d := New(nil, testPeerID(t))
+ signer := testPeerID(t)
+ d.observe(rawMessage(t, signer, &api.ServiceAnnounce{
+ PeerId: signer.String(), Type: api.ServiceType_SERVICE_TYPE_MCP,
+ ServiceName: "reviewer", Keys: []string{"review_pr"},
+ Labels: map[string]string{api.LabelRegion: "eu"},
+ Timestamp: time.Now().Unix(),
+ }))
+
+ if got := d.PeerLabels(signer.String()); got[api.LabelRegion] != "eu" {
+ t.Errorf("PeerLabels: got %v, want region=eu", got)
+ }
+ if got := d.PeerLabels("unknown-peer"); got != nil {
+ t.Errorf("PeerLabels for unknown peer: got %v, want nil", got)
+ }
+}
+
func TestValidateServiceAnnounceCaps(t *testing.T) {
base := func() *api.ServiceAnnounce {
return &api.ServiceAnnounce{
diff --git a/internal/node/discovery/view.go b/internal/node/discovery/view.go
index 7e2898b9..633d5dc0 100644
--- a/internal/node/discovery/view.go
+++ b/internal/node/discovery/view.go
@@ -75,6 +75,20 @@ func (d *Discovery) Providers(t api.ServiceType, key string) []Provider {
return out
}
+// PeerLabels returns the labels last observed for a peer, if any. Labels are
+// node-level claims (e.g. region), so any fresh entry of the peer suffices.
+func (d *Discovery) PeerLabels(peerID string) map[string]string {
+ d.viewMu.Lock()
+ defer d.viewMu.Unlock()
+ cutoff := time.Now().Add(-d.staleAfter)
+ for _, p := range d.providers {
+ if p.PeerID == peerID && p.LastSeen.After(cutoff) && len(p.Labels) > 0 {
+ return p.Labels
+ }
+ }
+ return nil
+}
+
// readLoop consumes one subscription until it is cancelled or ctx ends.
func (d *Discovery) readLoop(ctx context.Context, sub *pubsub.Subscription) {
for {
diff --git a/internal/node/discovery_source.go b/internal/node/discovery_source.go
index e115338c..bdd528c0 100644
--- a/internal/node/discovery_source.go
+++ b/internal/node/discovery_source.go
@@ -30,33 +30,43 @@ type activeTracker interface {
ActiveRequests() uint32
}
-// discoverySource builds gossip announcements from the registered services.
-// Only inference services announce for now; MCP adoption follows.
+// toolLister is implemented by services that report served MCP tool names.
+type toolLister interface {
+ Tools(ctx context.Context) ([]string, error)
+}
+
+// capKeys bounds announced keys to the wire cap; keys are expected sorted so
+// truncation is deterministic across ticks.
+func capKeys(keys []string) []string {
+ if len(keys) > api.MaxAnnounceKeys {
+ return keys[:api.MaxAnnounceKeys]
+ }
+ return keys
+}
+
+// discoverySource builds gossip announcements from the registered services:
+// inference services announce model IDs, MCP services announce tool names.
func (n *SamNode) discoverySource() []discovery.Announcement {
var labels map[string]string
if n.config.Region != "" {
labels = map[string]string{api.LabelRegion: n.config.Region}
}
var out []discovery.Announcement
- for _, info := range n.services.List(api.ServiceType_SERVICE_TYPE_INFERENCE) {
+ for _, info := range n.services.List(api.ServiceType_SERVICE_TYPE_UNSPECIFIED) {
svc, ok := n.services.Get(info.GetName())
if !ok {
continue
}
- lister, ok := svc.(modelLister)
- if !ok {
- continue
- }
ctx, cancel := context.WithTimeout(context.Background(), discoverySourceProbeTimeout)
- models, err := lister.Models(ctx)
+ keys, err := serviceKeys(ctx, svc, info.GetType())
cancel()
- if err != nil || len(models) == 0 {
+ if err != nil || len(keys) == 0 {
continue
}
ann := discovery.Announcement{
- Type: api.ServiceType_SERVICE_TYPE_INFERENCE,
+ Type: info.GetType(),
Name: info.GetName(),
- Keys: models,
+ Keys: capKeys(keys),
Labels: labels,
}
if tracker, ok := svc.(activeTracker); ok {
@@ -66,3 +76,18 @@ func (n *SamNode) discoverySource() []discovery.Announcement {
}
return out
}
+
+// serviceKeys returns the routing keys a service serves, per its type.
+func serviceKeys(ctx context.Context, svc Service, t api.ServiceType) ([]string, error) {
+ switch t {
+ case api.ServiceType_SERVICE_TYPE_INFERENCE:
+ if lister, ok := svc.(modelLister); ok {
+ return lister.Models(ctx)
+ }
+ case api.ServiceType_SERVICE_TYPE_MCP:
+ if lister, ok := svc.(toolLister); ok {
+ return lister.Tools(ctx)
+ }
+ }
+ return nil, nil
+}
diff --git a/internal/node/inference_service.go b/internal/node/inference_service.go
index 38fceb39..4f4a9acf 100644
--- a/internal/node/inference_service.go
+++ b/internal/node/inference_service.go
@@ -34,9 +34,9 @@ import (
"github.com/openai/openai-go"
)
-// modelCacheTTL bounds backend /v1/models probes: the announcer ticks more
-// often than models change.
-const modelCacheTTL = 30 * time.Second
+// backendProbeTTL bounds backend capability probes (models, tools): the
+// announcer ticks more often than backends change.
+const backendProbeTTL = 30 * time.Second
// InferenceService provides intelligent LLM gateway features: traffic routing
// and token usage tracking for OpenAI-compatible endpoints.
@@ -85,7 +85,7 @@ func (s *InferenceService) Models(ctx context.Context) ([]string, error) {
return nil, err
}
s.cachedModels = models
- s.modelsExpires = time.Now().Add(modelCacheTTL)
+ s.modelsExpires = time.Now().Add(backendProbeTTL)
return models, nil
}
diff --git a/internal/node/mcp.go b/internal/node/mcp.go
index 7fd50a18..7cc461de 100644
--- a/internal/node/mcp.go
+++ b/internal/node/mcp.go
@@ -113,7 +113,7 @@ func NewMCPServer(node *SamNode) *mcp.Server {
// Add the find_remote_tools tool.
mcp.AddTool(mcpServer, &mcp.Tool{
Name: "find_remote_tools",
- Description: "Discover MCP tools available on hosted services across the mesh. Returns name + description per tool. Optionally narrow by peer_id, service_name, or intent (intent is reserved for future ranking and is accepted-but-ignored).",
+ Description: "Discover MCP tools available on hosted services across the mesh. Returns name + description per tool, plus the provider's region claim when known. Optionally narrow by peer_id, service_name, or tool_name (exact tool name; fastest — served from mesh announcements when available). intent is reserved for future ranking and is accepted-but-ignored.",
}, node.handleFindRemoteTools)
// Add the describe_remote_tool tool.
diff --git a/internal/node/mcp_discovery_test.go b/internal/node/mcp_discovery_test.go
new file mode 100644
index 00000000..e6f47299
--- /dev/null
+++ b/internal/node/mcp_discovery_test.go
@@ -0,0 +1,161 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package node
+
+import (
+ "context"
+ "fmt"
+ "net/http/httptest"
+ "reflect"
+ "sort"
+ "testing"
+
+ "github.com/google/sam/api"
+ samdiscovery "github.com/google/sam/internal/node/discovery"
+ "github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+func TestMCPService_Tools(t *testing.T) {
+ backend := httptest.NewServer(newFakeMCPHandler(t, []*mcp.Tool{
+ {Name: "zeta", Description: "z", InputSchema: map[string]any{"type": "object"}},
+ {Name: "alpha", Description: "a", InputSchema: map[string]any{"type": "object"}},
+ }))
+ defer backend.Close()
+
+ svc := &MCPService{baseService: baseService{
+ info: &api.ServiceInfo{Type: api.ServiceType_SERVICE_TYPE_MCP, Name: "tools-svc"},
+ backend: &api.RegisterServiceRequest_TargetUrl{TargetUrl: backend.URL},
+ }}
+ if err := svc.Init(context.Background()); err != nil {
+ t.Fatalf("Init: %v", err)
+ }
+
+ got, err := svc.Tools(context.Background())
+ if err != nil {
+ t.Fatalf("Tools: %v", err)
+ }
+ if want := []string{"alpha", "zeta"}; !reflect.DeepEqual(got, want) {
+ t.Errorf("Tools: got %v, want %v (sorted)", got, want)
+ }
+
+ // Cached: survives the backend going away.
+ backend.Close()
+ got, err = svc.Tools(context.Background())
+ if err != nil || len(got) != 2 {
+ t.Errorf("cached Tools: got %v, err %v", got, err)
+ }
+}
+
+// fakeToolService is a local MCP Service reporting served tool names.
+type fakeToolService struct {
+ testService
+ tools []string
+ err error
+}
+
+func (f *fakeToolService) Tools(_ context.Context) ([]string, error) {
+ return f.tools, f.err
+}
+
+func TestDiscoverySource(t *testing.T) {
+ node := &SamNode{
+ services: NewServiceRegistry(&fakeDHT{}),
+ config: Options{Region: "eu"},
+ }
+ ctx := context.Background()
+
+ llm := newFakeModelService("llm", nil, "model-b", "model-a")
+ tools := &fakeToolService{
+ testService: testService{info: &api.ServiceInfo{Type: api.ServiceType_SERVICE_TYPE_MCP, Name: "reviewer"}},
+ tools: []string{"review_pr", "lint"},
+ }
+ broken := &fakeToolService{
+ testService: testService{info: &api.ServiceInfo{Type: api.ServiceType_SERVICE_TYPE_MCP, Name: "broken"}},
+ err: fmt.Errorf("backend down"),
+ }
+ for _, svc := range []Service{llm, tools, broken} {
+ if err := node.services.Register(ctx, svc); err != nil {
+ t.Fatalf("Register: %v", err)
+ }
+ }
+
+ anns := node.discoverySource()
+ if len(anns) != 2 {
+ t.Fatalf("announcements: got %d (%+v), want 2", len(anns), anns)
+ }
+ byName := map[string]samdiscovery.Announcement{}
+ for _, a := range anns {
+ byName[a.Name] = a
+ }
+ if a := byName["llm"]; a.Type != api.ServiceType_SERVICE_TYPE_INFERENCE || len(a.Keys) != 2 {
+ t.Errorf("llm announcement: %+v", a)
+ }
+ if a := byName["reviewer"]; a.Type != api.ServiceType_SERVICE_TYPE_MCP || len(a.Keys) != 2 {
+ t.Errorf("reviewer announcement: %+v", a)
+ }
+ for name, a := range byName {
+ if a.Labels[api.LabelRegion] != "eu" {
+ t.Errorf("%s labels: got %v, want region=eu", name, a.Labels)
+ }
+ }
+}
+
+func TestCapKeys(t *testing.T) {
+ keys := make([]string, api.MaxAnnounceKeys+5)
+ for i := range keys {
+ keys[i] = fmt.Sprintf("k%03d", i)
+ }
+ sort.Strings(keys)
+ if got := capKeys(keys); len(got) != api.MaxAnnounceKeys {
+ t.Errorf("capKeys: got %d, want %d", len(got), api.MaxAnnounceKeys)
+ }
+ if got := capKeys(keys[:3]); len(got) != 3 {
+ t.Errorf("capKeys under cap: got %d, want 3", len(got))
+ }
+}
+
+func TestGossipToolRows(t *testing.T) {
+ provs := []samdiscovery.Provider{
+ {PeerID: "peerA", Service: "reviewer", Labels: map[string]string{api.LabelRegion: "eu"}},
+ {PeerID: "peerB", Service: "other"},
+ }
+ rows := gossipToolRows(provs, "review_pr", "")
+ if len(rows) != 2 {
+ t.Fatalf("rows: got %+v, want 2", rows)
+ }
+ if rows[0].ToolName != "mcp://reviewer/review_pr" || rows[0].Region != "eu" {
+ t.Errorf("row 0: %+v", rows[0])
+ }
+ if rows[1].Region != "" {
+ t.Errorf("row 1 should have no region claim: %+v", rows[1])
+ }
+
+ filtered := gossipToolRows(provs, "review_pr", "reviewer")
+ if len(filtered) != 1 || filtered[0].PeerID != "peerA" {
+ t.Errorf("service filter: got %+v", filtered)
+ }
+}
+
+func TestFilterRowsByToolName(t *testing.T) {
+ rows := []remoteToolRow{
+ {PeerID: "p1", ToolName: "mcp://svc/review_pr"},
+ {PeerID: "p2", ToolName: "mcp://svc/lint"},
+ {PeerID: "p3", Error: "unreachable"},
+ }
+ got := filterRowsByToolName(rows, "review_pr")
+ if len(got) != 1 || got[0].PeerID != "p1" {
+ t.Errorf("filter: got %+v", got)
+ }
+}
diff --git a/internal/node/mcp_handlers.go b/internal/node/mcp_handlers.go
index 9d669941..dd9ee7d4 100644
--- a/internal/node/mcp_handlers.go
+++ b/internal/node/mcp_handlers.go
@@ -9,6 +9,7 @@ import (
"time"
"github.com/google/sam/api"
+ samdiscovery "github.com/google/sam/internal/node/discovery"
"github.com/libp2p/go-libp2p/core/peer"
"github.com/modelcontextprotocol/go-sdk/mcp"
"github.com/multiformats/go-multiaddr"
@@ -285,6 +286,7 @@ type FindRemoteToolsParams struct {
Intent string `json:"intent,omitempty" jsonschema:"Natural-language description of what the caller is looking for. Reserved for future semantic ranking; currently accepted but ignored."`
PeerID string `json:"peer_id,omitempty" jsonschema:"Restrict the search to a single peer. Empty means search the whole mesh."`
ServiceName string `json:"service_name,omitempty" jsonschema:"Restrict results to tools whose name starts with this service prefix (e.g. 'code-reviewer'). Empty means no service filter."`
+ ToolName string `json:"tool_name,omitempty" jsonschema:"Exact (non-namespaced) tool name to locate across the mesh, e.g. 'review_pr'. Served from gossip announcements when fresh; falls back to a mesh-wide fetch. Empty means list all tools."`
}
// remoteToolRow is one entry in the find_remote_tools response.
@@ -292,7 +294,10 @@ type remoteToolRow struct {
PeerID string `json:"peer_id"`
ToolName string `json:"tool_name,omitempty"`
Description string `json:"description,omitempty"`
- Error string `json:"error,omitempty"`
+ // Region is the provider's operator-declared region claim, when known
+ // from gossip. A routing hint, not an enforced attribute.
+ Region string `json:"region,omitempty"`
+ Error string `json:"error,omitempty"`
}
// handleFindRemoteTools implements the find_remote_tools tool.
@@ -320,6 +325,18 @@ func (n *SamNode) handleFindRemoteTools(ctx context.Context, req *mcp.CallToolRe
var rows []remoteToolRow
+ // Exact-name lookup: gossip fast path, avoiding the catalog fan-out
+ // when interested announcements are already flowing.
+ if params.ToolName != "" && params.PeerID == "" && n.Discovery != nil {
+ n.Discovery.Ensure(api.ServiceType_SERVICE_TYPE_MCP, params.ToolName)
+ if provs := n.Discovery.Providers(api.ServiceType_SERVICE_TYPE_MCP, params.ToolName); len(provs) > 0 {
+ rows = gossipToolRows(provs, params.ToolName, params.ServiceName)
+ if len(rows) > 0 {
+ return marshalToolRows(rows)
+ }
+ }
+ }
+
if params.PeerID != "" {
pid, err := peer.Decode(params.PeerID)
if err != nil {
@@ -352,6 +369,15 @@ func (n *SamNode) handleFindRemoteTools(ctx context.Context, req *mcp.CallToolRe
rows = n.fanOutFetch(ctx, peerIDs, params.ServiceName)
}
+ if params.ToolName != "" {
+ rows = filterRowsByToolName(rows, params.ToolName)
+ }
+ n.annotateToolRegions(rows)
+ return marshalToolRows(rows)
+}
+
+// marshalToolRows renders the find_remote_tools response.
+func marshalToolRows(rows []remoteToolRow) (*mcp.CallToolResult, any, error) {
if rows == nil {
rows = []remoteToolRow{}
}
@@ -364,6 +390,57 @@ func (n *SamNode) handleFindRemoteTools(ctx context.Context, req *mcp.CallToolRe
}, nil, nil
}
+// gossipToolRows builds result rows from gossip-observed providers of a tool.
+func gossipToolRows(provs []samdiscovery.Provider, toolName, serviceNameFilter string) []remoteToolRow {
+ var rows []remoteToolRow
+ for _, p := range provs {
+ if serviceNameFilter != "" && p.Service != serviceNameFilter {
+ continue
+ }
+ name := p.Service
+ if !strings.Contains(name, "://") {
+ name = api.MCPServicePrefix + name
+ }
+ rows = append(rows, remoteToolRow{
+ PeerID: p.PeerID,
+ ToolName: name + "/" + toolName,
+ Region: p.Labels[api.LabelRegion],
+ })
+ }
+ return rows
+}
+
+// filterRowsByToolName keeps rows whose namespaced tool name ends in the
+// bare tool name; error rows (no tool listing) are dropped from targeted
+// lookups.
+func filterRowsByToolName(rows []remoteToolRow, toolName string) []remoteToolRow {
+ var out []remoteToolRow
+ for _, row := range rows {
+ if row.Error != "" {
+ continue
+ }
+ if row.ToolName[strings.LastIndex(row.ToolName, "/")+1:] == toolName {
+ out = append(out, row)
+ }
+ }
+ return out
+}
+
+// annotateToolRegions fills the region hint for peers the gossip view knows.
+func (n *SamNode) annotateToolRegions(rows []remoteToolRow) {
+ if n.Discovery == nil {
+ return
+ }
+ for i := range rows {
+ if rows[i].Region != "" {
+ continue
+ }
+ if labels := n.Discovery.PeerLabels(rows[i].PeerID); labels != nil {
+ rows[i].Region = labels[api.LabelRegion]
+ }
+ }
+}
+
// fetchRemoteToolCatalogue gets the remote node's service catalogue,
// then opens a separate libp2p stream to each MCP service to fetch its tools.
func (n *SamNode) fetchRemoteToolCatalogue(ctx context.Context, targetPeer peer.ID, serviceNameFilter string) ([]remoteToolRow, error) {
diff --git a/internal/node/mcp_service.go b/internal/node/mcp_service.go
index 98e47604..6098e67a 100644
--- a/internal/node/mcp_service.go
+++ b/internal/node/mcp_service.go
@@ -16,6 +16,10 @@ package node
import (
"context"
+ "fmt"
+ "sort"
+ "sync"
+ "time"
"github.com/google/sam/api"
"github.com/libp2p/go-libp2p/core/network"
@@ -26,6 +30,10 @@ import (
// MCPService extends baseService to handle MCP protocol proxying.
type MCPService struct {
baseService
+
+ toolsMu sync.Mutex
+ cachedTools []string
+ toolsExpires time.Time
}
// Init initializes the base service.
@@ -38,6 +46,58 @@ func (m *MCPService) Teardown() error {
return m.baseService.Teardown()
}
+// backendTransport builds a fresh MCP transport to this service's backend.
+// Command backends share the stdio bridge, which multiplexes sessions the
+// same way concurrent remote streams already do.
+func (m *MCPService) backendTransport() (mcp.Transport, error) {
+ switch x := m.backend.(type) {
+ case *api.RegisterServiceRequest_TargetUrl:
+ return &mcp.StreamableClientTransport{Endpoint: x.TargetUrl}, nil
+ case *api.RegisterServiceRequest_Command:
+ bridge, ok := m.handler.(*StdioBridge)
+ if !ok {
+ return nil, fmt.Errorf("expected *StdioBridge handler for command-backed MCP service %q, got %T", m.info.GetName(), m.handler)
+ }
+ return newBridgeTransport(bridge), nil
+ default:
+ return nil, fmt.Errorf("unsupported backend type %T for MCP service %q", m.backend, m.info.GetName())
+ }
+}
+
+// Tools lists the backend's tool names (sorted), cached briefly since the
+// discovery announcer polls it on every tick.
+func (m *MCPService) Tools(ctx context.Context) ([]string, error) {
+ m.toolsMu.Lock()
+ defer m.toolsMu.Unlock()
+ if m.cachedTools != nil && time.Now().Before(m.toolsExpires) {
+ return m.cachedTools, nil
+ }
+ transport, err := m.backendTransport()
+ if err != nil {
+ return nil, err
+ }
+ client := mcp.NewClient(&mcp.Implementation{Name: "sam-node-discovery", Version: "0.1.0"}, nil)
+ session, err := client.Connect(ctx, transport, nil)
+ if err != nil {
+ return nil, fmt.Errorf("connect to backend of %q: %w", m.info.GetName(), err)
+ }
+ defer func() { _ = session.Close() }()
+ res, err := session.ListTools(ctx, nil)
+ if err != nil {
+ return nil, fmt.Errorf("list tools of %q: %w", m.info.GetName(), err)
+ }
+ names := make([]string, 0, len(res.Tools))
+ for _, t := range res.Tools {
+ if t != nil && t.Name != "" {
+ names = append(names, t.Name)
+ }
+ }
+ sort.Strings(names)
+ m.cachedTools = names
+ m.toolsExpires = time.Now().Add(backendProbeTTL)
+ return names, nil
+}
+
// preflightMethodsUnsupportedByPassThrough lists stateless MCP capability
// probes that HandleStreamPassThrough answers locally instead of forwarding.
// It opens a fresh, sessionless backend connection per stream, so it can
@@ -63,22 +123,12 @@ func (m *MCPService) HandleStreamPassThrough(s network.Stream) {
var backendTransport mcp.Transport
var closeTransport func()
- switch x := m.backend.(type) {
- case *api.RegisterServiceRequest_TargetUrl:
- backendTransport = &mcp.StreamableClientTransport{Endpoint: x.TargetUrl}
- closeTransport = func() {} // ClientTransport Close is handled by Connect's returned Connection
- case *api.RegisterServiceRequest_Command:
- bridge, ok := m.handler.(*StdioBridge)
- if !ok {
- logger.Errorf("[MCPService] %s: expected *StdioBridge handler for command-backed MCP service, got %T", m.info.Name, m.handler)
- return
- }
- backendTransport = newBridgeTransport(bridge)
- closeTransport = func() {} // Do not close the shared bridge
- default:
- logger.Errorf("[MCPService] %s: unsupported backend type %T", m.info.Name, m.backend)
+ backendTransport, err := m.backendTransport()
+ if err != nil {
+ logger.Errorf("[MCPService] %s: %v", m.info.Name, err)
return
}
+ closeTransport = func() {} // fresh per stream for URL; shared bridge is never closed
ctx, cancel := context.WithCancel(context.Background())
defer cancel()