Default to 127.0.0:8080 for 'cagent api', 'cagent a2a' and 'cagent mcp'

Signed-off-by: David Gageot <david.gageot@docker.com>

Author: dgageot

cmd/root/a2a.go

@@ -13,9 +13,9 @@ import (
 )
 
 type a2aFlags struct {
-	agentName string
-	port      int
-	runConfig config.RuntimeConfig
+	agentName  string
+	listenAddr string
+	runConfig  config.RuntimeConfig
 }
 
 func newA2ACmd() *cobra.Command {
@@ -26,15 +26,14 @@ func newA2ACmd() *cobra.Command {
 		Short: "Start an agent as an A2A (Agent-to-Agent) server",
 		Long:  "Start an A2A server that exposes the agent via the Agent-to-Agent protocol",
 		Example: `  cagent a2a ./agent.yaml
-  cagent a2a ./team.yaml --port 8080
-  cagent a2a agentcatalog/pirate --port 9000`,
+  cagent a2a agentcatalog/pirate --listen 127.0.0.1:9090`,
 		Args:    cobra.ExactArgs(1),
 		GroupID: "server",
 		RunE:    flags.runA2ACommand,
 	}
 
 	cmd.PersistentFlags().StringVarP(&flags.agentName, "agent", "a", "root", "Name of the agent to run")
-	cmd.PersistentFlags().IntVar(&flags.port, "port", 0, "Port to listen on (default: random available port)")
+	cmd.PersistentFlags().StringVarP(&flags.listenAddr, "listen", "l", "127.0.0.1:8080", "Address to listen on")
 	addRuntimeConfigFlags(cmd, &flags.runConfig)
 
 	return cmd
@@ -48,9 +47,9 @@ func (f *a2aFlags) runA2ACommand(cmd *cobra.Command, args []string) error {
 	agentFilename := args[0]
 
 	// Listen as early as possible
-	ln, err := server.Listen(ctx, fmt.Sprintf(":%d", f.port))
+	ln, err := server.Listen(ctx, f.listenAddr)
 	if err != nil {
-		return fmt.Errorf("failed to bind to port %d: %w", f.port, err)
+		return fmt.Errorf("failed to listen on %s: %w", f.listenAddr, err)
 	}
 	go func() {
 		<-ctx.Done()

cmd/root/api.go

@@ -40,7 +40,7 @@ func newAPICmd() *cobra.Command {
 		RunE:    flags.runAPICommand,
 	}
 
-	cmd.PersistentFlags().StringVarP(&flags.listenAddr, "listen", "l", ":8080", "Address to listen on")
+	cmd.PersistentFlags().StringVarP(&flags.listenAddr, "listen", "l", "127.0.0.1:8080", "Address to listen on")
 	cmd.PersistentFlags().StringVarP(&flags.sessionDB, "session-db", "s", "session.db", "Path to the session database")
 	cmd.PersistentFlags().IntVar(&flags.pullIntervalMins, "pull-interval", 0, "Auto-pull OCI reference every N minutes (0 = disabled)")
 	cmd.PersistentFlags().StringVar(&flags.fakeResponses, "fake", "", "Replay AI responses from cassette file (for testing)")
@@ -132,7 +132,7 @@ func (f *apiFlags) runAPICommand(cmd *cobra.Command, args []string) error {
 		_ = ln.Close()
 	}()
 
-	out.Println("Listening on " + ln.Addr().String())
+	out.Println("Listening on", ln.Addr().String())
 
 	slog.Debug("Starting server", "agents", agentsPath, "addr", ln.Addr().String())
 

cmd/root/mcp.go

@@ -12,10 +12,10 @@ import (
 )
 
 type mcpFlags struct {
-	agentName string
-	http      bool
-	port      int
-	runConfig config.RuntimeConfig
+	agentName  string
+	http       bool
+	listenAddr string
+	runConfig  config.RuntimeConfig
 }
 
 func newMCPCmd() *cobra.Command {
@@ -28,15 +28,15 @@ func newMCPCmd() *cobra.Command {
 		Example: `  cagent mcp ./agent.yaml
   cagent mcp ./team.yaml
   cagent mcp agentcatalog/pirate
-  cagent mcp ./agent.yaml --http --port 8080`,
+  cagent mcp ./agent.yaml --http --listen 127.0.0.1:9090`,
 		Args:    cobra.ExactArgs(1),
 		GroupID: "server",
 		RunE:    flags.runMCPCommand,
 	}
 
 	cmd.PersistentFlags().StringVarP(&flags.agentName, "agent", "a", "", "Name of the agent to run (all agents if not specified)")
 	cmd.PersistentFlags().BoolVar(&flags.http, "http", false, "Use streaming HTTP transport instead of stdio")
-	cmd.PersistentFlags().IntVar(&flags.port, "port", 0, "Port to listen on when using HTTP transport (default: random available port)")
+	cmd.PersistentFlags().StringVarP(&flags.listenAddr, "listen", "l", "127.0.0.1:8080", "Address to listen on")
 	addRuntimeConfigFlags(cmd, &flags.runConfig)
 
 	return cmd
@@ -48,18 +48,19 @@ func (f *mcpFlags) runMCPCommand(cmd *cobra.Command, args []string) error {
 	ctx := cmd.Context()
 	agentFilename := args[0]
 
-	if f.http || f.port != 0 {
-		ln, err := server.Listen(ctx, fmt.Sprintf(":%d", f.port))
-		if err != nil {
-			return fmt.Errorf("failed to bind to port %d: %w", f.port, err)
-		}
-		go func() {
-			<-ctx.Done()
-			_ = ln.Close()
-		}()
+	if !f.http {
+		return mcp.StartMCPServer(ctx, agentFilename, f.agentName, &f.runConfig)
+	}
 
-		return mcp.StartHTTPServer(ctx, agentFilename, f.agentName, &f.runConfig, ln)
+	// Listen as early as possible
+	ln, err := server.Listen(ctx, f.listenAddr)
+	if err != nil {
+		return fmt.Errorf("failed to listen on %s: %w", f.listenAddr, err)
 	}
+	go func() {
+		<-ctx.Done()
+		_ = ln.Close()
+	}()
 
-	return mcp.StartMCPServer(ctx, agentFilename, f.agentName, &f.runConfig)
+	return mcp.StartHTTPServer(ctx, agentFilename, f.agentName, &f.runConfig, ln)
 }

docs/a2a.md

@@ -16,10 +16,10 @@ This document describes how to expose Docker `cagent` agents via Google's A2A (A
 cagent a2a ./agent.yaml
 
 # Specify a custom port
-cagent a2a ./agent.yaml --port 8080
+cagent a2a ./agent.yaml --listen 127.0.0.1:9000
 
 # Use an agent from the catalog
-cagent a2a agentcatalog/pirate --port 9000
+cagent a2a agentcatalog/pirate
 ```
 
 ## Limitations and Future Work

examples/tic-tac-toe-mcp.yaml

@@ -10,8 +10,8 @@ metadata:
     The Game master talks to both players over MCP.
 
     To run the demo:
-    cagent mcp --http --port 8080 ./examples/tic-tac-toe-mcp.yaml --agent player_blue
-    cagent mcp --http --port 8081 ./examples/tic-tac-toe-mcp.yaml --agent player_red
+    cagent mcp --http --listen 127.0.0.1:8080 ./examples/tic-tac-toe-mcp.yaml --agent player_blue
+    cagent mcp --http --listen 127.0.0.1:8081 ./examples/tic-tac-toe-mcp.yaml --agent player_red
     cagent run --yolo ./examples/tic-tac-toe-mcp.yaml 'Go!'
 
 agents:
@@ -43,16 +43,16 @@ agents:
       </preparation>
     add_environment_info: true
     toolsets:
-      - type: shell
-      - type: filesystem
-      - type: mcp
-        remote:
-          url: http://localhost:8080/
-          transport_type: streamable
-      - type: mcp
-        remote:
-          url: http://localhost:8081/
-          transport_type: streamable
+    - type: shell
+    - type: filesystem
+    - type: mcp
+      remote:
+        url: http://localhost:8080/
+        transport_type: streamable
+    - type: mcp
+      remote:
+        url: http://localhost:8081/
+        transport_type: streamable
 
   # BLUE Player
   player_blue:

examples/tic-tac-toe.yaml

@@ -10,8 +10,8 @@ metadata:
     The Game master talks to both players over A2A.
 
     To run the demo:
-    cagent a2a --port 8080 ./examples/tic-tac-toe.yaml --agent player_blue
-    cagent a2a --port 8081 ./examples/tic-tac-toe.yaml --agent player_red
+    cagent a2a --listen 127.0.0.1:8080 ./examples/tic-tac-toe.yaml --agent player_blue
+    cagent a2a --listen 127.0.0.1:8081 ./examples/tic-tac-toe.yaml --agent player_red
     cagent run --yolo ./examples/tic-tac-toe.yaml 'Go!'
 
 agents:
@@ -43,12 +43,12 @@ agents:
       </preparation>
     add_environment_info: true
     toolsets:
-      - type: shell
-      - type: filesystem
-      - type: a2a
-        url: http://localhost:8080/
-      - type: a2a
-        url: http://localhost:8081/
+    - type: shell
+    - type: filesystem
+    - type: a2a
+      url: http://localhost:8080/
+    - type: a2a
+      url: http://localhost:8081/
 
   # BLUE Player
   player_blue:

pkg/telemetry/telemetry_test.go

@@ -539,7 +539,7 @@ func TestTrackServerStart(t *testing.T) {
 	cmdInfo := CommandInfo{
 		Action: "mcp",
 		Args:   []string{},
-		Flags:  []string{"--port", "8080"},
+		Flags:  []string{},
 	}
 	err := client.TrackServerStart(t.Context(), cmdInfo, func(ctx context.Context) error {
 		executed = true