Skip to content

Agent Mesh

refactor: extract MCPServicePrefix to api/types and document explicitly

Antonio Ojea3ff3ea807273
diff --git a/api/types.go b/api/types.go
index fea9f99f..77d9b8e2 100644
--- a/api/types.go
+++ b/api/types.go
@@ -35,6 +35,12 @@ const DefaultServiceType = "system"
const DefaultAudience = "sam-mesh-audience"
+// MCPServicePrefix is the conventional prefix (namespace + separator) used for Model Context Protocol (MCP) services.
+// When an MCP client attempts to connect to an MCP service on a remote peer, and the target service name
+// does not contain a namespace separator (':'), this prefix is automatically prepended to the service name
+// prior to routing and policy evaluation.
+const MCPServicePrefix = "mcp:"
+
// Biscuit fact names
const (
FactExpiration = "expiration"
diff --git a/cmd/sam-node/mcp_handlers.go b/cmd/sam-node/mcp_handlers.go
index 2028877e..44ea30e9 100644
--- a/cmd/sam-node/mcp_handlers.go
+++ b/cmd/sam-node/mcp_handlers.go
@@ -338,7 +338,7 @@ func (n *SamNode) fetchRemoteToolCatalogue(ctx context.Context, targetPeer peer.
targetService := svc.Name
if !strings.Contains(targetService, ":") {
- targetService = "mcp:" + targetService
+ targetService = api.MCPServicePrefix + targetService
}
n.preparePeerAddrs(ctx, targetPeer)
diff --git a/development/kind/10-hub.yaml b/development/kind/10-hub.yaml
index ec3fcf36..2565e410 100644
--- a/development/kind/10-hub.yaml
+++ b/development/kind/10-hub.yaml
@@ -30,6 +30,7 @@ spec:
# addr (for pods) and the host-mapped addr (for a local sam-node).
- "--external-multiaddr=/dns4/sam-hub.${NAMESPACE}.svc.cluster.local/tcp/4001"
- "--external-multiaddr=/ip4/127.0.0.1/tcp/4001"
+ - "--policy-file=/etc/sam/policies/policies.yaml"
ports:
- { containerPort: 9090, name: http, protocol: TCP }
- { containerPort: 4001, name: p2p-tcp, protocol: TCP }
@@ -39,6 +40,14 @@ spec:
readinessProbe:
tcpSocket: { port: 9090 }
periodSeconds: 2
+ volumeMounts:
+ - name: policies-volume
+ mountPath: /etc/sam/policies
+ readOnly: true
+ volumes:
+ - name: policies-volume
+ configMap:
+ name: sam-hub-policies
---
apiVersion: v1
kind: Service
@@ -68,3 +77,26 @@ spec:
ports:
- { name: http, port: 9090, targetPort: 9090, nodePort: 30090, protocol: TCP }
- { name: p2p-tcp, port: 4001, targetPort: 4001, nodePort: 30401, protocol: TCP }
+
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: sam-hub-policies
+ namespace: ${NAMESPACE}
+data:
+ policies.yaml: |
+ version: "v1alpha1"
+ bindings:
+ - group: "system:serviceaccounts"
+ role: "sam-admin"
+ - group: "system:authenticated"
+ role: "sam-admin"
+ - group: "system:serviceaccounts:${NAMESPACE}"
+ role: "sam-admin"
+ roles:
+ sam-admin:
+ allowed_services:
+ - "*"
+ allowed_targets:
+ - "*"
diff --git a/site/content/docs/development/policy.md b/site/content/docs/development/policy.md
index 73ca5792..b009f961 100644
--- a/site/content/docs/development/policy.md
+++ b/site/content/docs/development/policy.md
@@ -71,6 +71,7 @@ Admins define central permissions by mapping OIDC roles to specific capabilities
* **`allowed_services`**: Defines the application-level tools or endpoints a user can access. Services use a strict `type:name` convention (e.g., `mcp:db-agent` or `inference:openrouter`).
* **Default Namespace (`system`)**: If a service string does not contain a `:` separator (e.g., `my-tool`), it automatically defaults to the `system` type (parsed as `system:my-tool`).
* **Wildcards**: Because `allowed_services` translates to the two-argument Biscuit fact `service($type, $name)`, SAM natively supports wildcards. You can grant access to an entire type via `type:*` (e.g., `mcp:*`), or grant global access to everything via `*`.
+ * **MCP Namespace Convention**: The `mcp:` prefix (`api.MCPServicePrefix`) is the explicit convention for all Model Context Protocol targets. When remote nodes query local nodes for tool catalogs, if the local service is an MCP server and is missing the `mcp:` prefix in its name, the proxy layer will automatically prepend `mcp:` prior to enforcing the authorization policy to prevent it from accidentally falling back into the `system:` namespace.
> [!NOTE]
> The `*` global wildcard is a special case. It maps exactly to type `*` and name `*`. It does *not* default to the `system` type.