Feat/expose kagent agents in mcp #1201

riturajFi · 2026-01-12T06:58:36Z

Title

Expose kagent agents as dynamic MCP tools over stdio (kagent mcp serve-agents)

Summary

This PR adds a new CLI subcommand, kagent mcp serve-agents, which runs an MCP server over stdio and dynamically exposes kagent agents as MCP tools.

Each eligible kagent agent is surfaced as a discoverable MCP tool at runtime. MCP-capable clients (IDEs, agent frameworks, assistants) can list and invoke these tools without any static tool definitions or manual schema maintenance.

All execution continues to flow through the existing A2A (agent-to-agent) API, preserving current agent semantics, permissions, and behavior.

What This Enables

MCP clients can automatically discover kagent agents via tools/list
Agents can be invoked using standard MCP tools/call
No static MCP schemas need to be authored or updated
Agent additions/removals are reflected immediately at runtime

This turns kagent into a dynamic MCP tool provider backed by real agents.

New CLI Command

kagent mcp serve-agents

Behavior

Starts an MCP server over stdin/stdout
Intended to be launched and managed by an MCP client
Dynamically registers one MCP tool per eligible kagent agent
Does not open network ports or run an HTTP server

Tool Model

Tool Naming

One tool per agent
Tool name is a deterministic, MCP-safe identifier derived from the agent ID

Tool Description

kagent agent <namespace>/<name>

Tool Inputs

Runtime Flow

Startup

On startup, serve-agents:

Loads local CLI configuration
Queries the kagent backend for agents
Filters agents that are:
- Accepted
- DeploymentReady
- Have a non-nil agent payload
Registers one MCP tool per eligible agent

If discovery fails, the MCP server still starts with an empty tool set.

Tool Invocation

When a tool is called:

Validate required inputs (task)
Construct the A2A endpoint:
```
{KAgentURL}/api/a2a/{namespace}/{name}
```
Send the task via the existing A2A protocol
Extract human-readable text from the A2A response:
- Message text (preferred)
- Task status + artifact text
- Raw JSON fallback if no text is extractable
Return the result as MCP tool output

All requests are handled synchronously over stdio.

Implementation Notes

Command Wiring

Adds a new Cobra command under kagent mcp
No changes to existing CLI behavior or defaults

MCP Server

Uses mark3labs/mcp-go
Server name: kagent-agents
Version: version.Version

Runs over stdio using:

mcpserver.NewStdioServer(s).Listen(ctx, os.Stdin, os.Stdout)

Agent Discovery

cfg.Client().Agent.ListAgents(ctx)

Filtering is applied client-side.

Error Handling

Tool-level errors are returned as MCP tool errors:
- Missing or invalid inputs
- A2A client creation failures
- A2A request failures
- JSON marshaling issues
Startup failures (config or agent discovery):
- Do not crash the MCP server
- Result in an empty tool list

The process remains long-running and usable.

Scope and Non-Goals

In Scope

MCP stdio server
Dynamic per-agent tool registration
A2A-backed execution
Text extraction and fallback handling

Out of Scope

Server-side kagent changes
New agent logic
MCP transports other than stdio
Authentication or permission changes

Files Changed

root.go
Registers serve-agents under kagent mcp
serve_agents.go
Implements the MCP stdio server, agent discovery, tool registration, and tool execution

How to Test (End-to-End)

These steps emulate a real MCP client and validate full end-to-end behavior.

1. Start kagent backend (one-time)

export KAGENT_DEFAULT_MODEL_PROVIDER=openAI export OPENAI_API_KEY=...

make create-kind-cluster make use-kind-cluster make helm-install

Port-forward the controller (keep running):

kubectl -n kagent port-forward svc/kagent-controller 8083:8083

Verify backend:

curl -s http://localhost:8083/version

curl -s -H 'X-User-ID: admin@kagent.dev' http://localhost:8083/api/agents | head

2. Build the CLI

go -C go build -o ./bin/kagent ./cli/cmd/kagent

./go/bin/kagent mcp --help

3. MCP handshake + tool discovery

cat <<'EOF' | ./go/bin/kagent mcp serve-agents

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"manual","version":"0.0.0"}}}

{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

EOF

Expected: tools listed, one per eligible agent.

4. Invoke a real agent via MCP

cat <<'EOF' | ./go/bin/kagent mcp serve-agents

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"manual","version":"0.0.0"}}}

{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"kagent__NS__k8s_agent","arguments":{"task":"list all pods in all namespaces"}}}

EOF

Expected: real cluster data returned as MCP tool output.

Result

This PR makes kagent agents immediately usable as MCP tools with no static schemas, no server-side changes, and full reuse of existing A2A execution paths.

riturajFi · 2026-01-12T07:00:51Z

@eitansuez @ilackarms @yuval-k @peterj
Kindly check this PR changes solving #1160

supreme-gg-gg

Left some comments on tools below.

Perhaps we can add support for HTTP transport with --transport http --port <port> as well instead of just stdio? The existing mcp deploy command supports both.

It would also be a good idea to add e2e tests for invoking agents through MCP.

supreme-gg-gg · 2026-01-12T16:59:27Z

go/cli/internal/cli/mcp/serve_agents.go

+					}
+					toolName, agentNS, agentName := agent.ID, agent.Agent.Namespace, agent.Agent.Name
+					s.AddTool(mcp.NewTool(toolName,
+						mcp.WithDescription("kagent agent "+agentNS+"/"+agentName),


Instead of one tool per agent, I think it would be more efficient to create a list_agents tool and a separate invoke_agent tool that takes in an agent name from the list of agents alongside the prompt / task. When listing the agents perhaps you can include the description for the agent for better info on which one to choose.

This way there will be only 2 tools exposed via this MCP server, which is more token-efficient and functionally equivalent if you have 20 agents. This is similar to the Agent Skills pattern for progressive discovery.

supreme-gg-gg · 2026-01-12T17:16:00Z

go/cli/internal/cli/mcp/serve_agents.go

+					s.AddTool(mcp.NewTool(toolName,
+						mcp.WithDescription("kagent agent "+agentNS+"/"+agentName),
+						mcp.WithString("context_id", mcp.Description("A2A context ID")),
+						mcp.WithNumber("history_length", mcp.Description("Requested history length")),


We can possibly remove history_length I don't see how it can be useful since the agent calling this would just be guessing a number for input. It seems like the MCP client will have no idea what is context_id as well.

I believe the easiest solutions would be either just

remove it (so only single-turn conversations are possible) or

return this context id created on the first A2A request to the client, and it can use it to continue the conversation.

Alternatively we can manage a session internally in the MCP server based on the MCP sessions ID, so the agent calling this would not worry about context ID at all.

riturajFi · 2026-01-13T08:37:24Z

Hi @supreme-gg-gg made the changes -
Updated serve_agents.go to address the review comments:
Switched from “one tool per agent” → 2 tools: list_agents (includes agent ref, id, description) + invoke_agent (takes agent + task).
Removed history_length; context_id is now managed internally per MCP session+agent and returned in structuredContent.
Added HTTP transport: kagent mcp serve-agents --transport http --host --port (streamable-http at http://:/mcp).
Added an e2e test: mcp_serve_agents_test.go (runs kagent mcp serve-agents over stdio and invokes kebab-agent).
Commits: 6c4b1d9e (tools + HTTP transport), 333ac100 (e2e test).
How to try it

STDIO server: kagent mcp serve-agents
HTTP server: kagent mcp serve-agents --transport http --host 127.0.0.1 --port 3000 (connect to http://127.0.0.1:3000/mcp)
Run the new e2e test: cd go && go test ./test/e2e -run TestE2EInvokeAgentThroughMCPServeAgents -v

supreme-gg-gg

Good start, I tried this and it seems to work pretty well in both stdio and http with MCP clients like Cursor. I left a few more comments. I think the test can be improved as well.

^ screenshot from Cursor using agents via MCP after I set it up

Lmk once you fixed them and I'll give it another review.

supreme-gg-gg · 2026-01-13T18:16:38Z

go/cli/internal/cli/mcp/serve_mcp.go

+				return mcp.NewToolResultErrorFromErr("list agents", err), nil
+			}
+			type agentSummary struct {
+				Ref         string `json:"ref"`


Id doesn't seem to be useful, maybe just ref (name) and description?

supreme-gg-gg · 2026-01-13T18:44:07Z

go/cli/internal/cli/mcp/serve_mcp.go

+			agentRef = agentNS + "/" + agentName
+
+			sessionID := "unknown"
+			if session := mcpserver.ClientSessionFromContext(ctx); session != nil {


Instead of falling back to unknown, use a unique invocation ID per session if none is available to keep the context separate. When callers with proper session support use this they will get unknown as session and it will cause unexpected behaviour with multiple concurrent users like potentially wrong context history.

supreme-gg-gg · 2026-01-13T18:45:25Z

go/cli/internal/cli/mcp/serve_mcp.go

+			stdioServer := mcpserver.NewStdioServer(s)
+			return stdioServer.Listen(cmd.Context(), os.Stdin, os.Stdout)
+		case "http":
+			addr := fmt.Sprintf("%s:%d", serveAgentsHost, serveAgentsPort)


Perhaps some logging to indicate the server is running successfully like "MCP server listening on xxx"

supreme-gg-gg · 2026-01-13T18:46:30Z

go/cli/internal/cli/mcp/serve_mcp.go

+	serveAgentsPort      int
+)
+
+var a2aContextBySessionAndAgent sync.Map


This map never cleans up old session contexts. This might be an issue for HTTP server

I quickly looked at the docs for mcp-go and seems like this hook will help:

// Create hooks for session lifecycle hooks := &mcpserver.Hooks{} // Clean up context storage when session ends hooks.AddOnUnregisterSession(func(ctx context.Context, session mcpserver.ClientSession) { sessionID := session.SessionID() // Delete all entries for this session a2aContextBySessionAndAgent.Range(func(key, value any) bool { if keyStr, ok := key.(string); ok { // Keys are formatted as "sessionID|agentRef" if strings.HasPrefix(keyStr, sessionID+"|") { a2aContextBySessionAndAgent.Delete(key) } } return true }) }) s := mcpserver.NewMCPServer( "kagent-agents", version.Version, mcpserver.WithToolCapabilities(false), mcpserver.WithHooks(hooks), )

hope it helps

supreme-gg-gg · 2026-01-13T18:49:44Z

go/cli/internal/cli/mcp/serve_agents.go

+	Use:   "serve-agents",
+	Short: "Serve kagent agents via MCP",
+	RunE: func(cmd *cobra.Command, args []string) error {
+		cfg, cfgErr := config.Get()


You can just check for config error on server startup instead of inside tool invocation because if config has a problem you won't be able to get the client and kagent url to do anything that follows.

supreme-gg-gg · 2026-01-13T20:44:20Z

go/test/e2e/mcp_serve_agents_test.go

+	require.NotEmpty(t, callResult.Content)
+	require.Contains(t, callResult.Content[0].Text, "kebab-agent")
+
+	writeLine(`{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"invoke_agent","arguments":{"agent":"kebab-agent","task":"What can you do?"}}}`)


I think it's best to follow the pattern in invoke_api_test.go and setup the kebab agent and especially use mockLLM otherwise this might fail in CI

supreme-gg-gg · 2026-01-13T21:13:56Z

go/cli/internal/cli/mcp/serve_agents.go

+			if err != nil {
+				return mcp.NewToolResultErrorFromErr("encode agents", err), nil
+			}
+			return result, nil


This seems to bug, you need to return mcp.NewToolResultStructured like below as well

riturajFi · 2026-01-14T12:39:59Z

Hi @supreme-gg-gg
I have implemented the changes.
Could you kindly review the changes done?

EItanya

These changes make sense to me, I think we can handle fixes in follow-ups. Unfortunately you will need to sign your commits to pass DCO

EItanya · 2026-01-14T20:39:06Z

go/cli/internal/cli/mcp/serve_agents.go

+var fallbackInvocationCounter uint64
+
+var ServeAgentsCmd = &cobra.Command{
+	Use:   "serve-agents",


Can we change this to serve-mcp

EItanya · 2026-01-15T21:01:06Z

You will need to sign all of your commits for me to approve

riturajFi marked this pull request as ready for review January 12, 2026 07:01

riturajFi requested review from EItanya, ilackarms and yuval-k as code owners January 12, 2026 07:01

supreme-gg-gg reviewed Jan 12, 2026

View reviewed changes

riturajFi force-pushed the feat/expose-kagent-agents-in-mcp branch from c4e28d8 to 548088d Compare January 13, 2026 08:36

riturajFi requested a review from supreme-gg-gg January 13, 2026 08:47

supreme-gg-gg reviewed Jan 13, 2026

View reviewed changes

riturajFi added 20 commits January 14, 2026 14:00

Add serve-agents Command Stub

3f3d845

Start an Empty mcp-go Server (stdio)

44d31ff

echo tool

0569152

Milestone 5: Clean Shutdown via Cobra Context

37da44a

Milestone 6 best-effort, non-blocking /api/agents listing cal

eb5803f

Milestone 7: Register first agent tool (stub)

347222c

Milestone 8: Register all agent tools (stub)

33429a5

Milestone 9: Bridge agent tools to A2A

ff085d8

Milestone 10: Support context_id and history_length

083a212

Milestone 11: Return extracted A2A text

84d87d6

Milestone 12: Remove temporary echo tool

6559f50

MCP serve-agents: list/invoke tools + http transport

65e4ad3

e2e: invoke agent via MCP serve-agents

c2fa6d3

mcp: drop unused agent id from list_agents

344f1f0

mcp: fail fast when config is invalid

db5b4ee

mcp: avoid context collisions when session id missing

ad6ac11

mcp: log http server listen address

0c92da8

mcp: cleanup stored contexts when sessions end

123bb45

mcp: return structured list_agents result with text fallback

c3cce6d

test: make mcp serve-agents e2e deterministic

9c77d56

riturajFi force-pushed the feat/expose-kagent-agents-in-mcp branch from 548088d to 9c77d56 Compare January 14, 2026 12:27

riturajFi requested a review from supreme-gg-gg January 14, 2026 12:28

supreme-gg-gg mentioned this pull request Jan 14, 2026

feat: expose a2a agents via mcp in controller http server and migrate to mcp go-sdk #1210

Open

EItanya previously approved these changes Jan 14, 2026

View reviewed changes

minor refactor

1063814

riturajFi dismissed EItanya’s stale review via 1063814 January 15, 2026 06:32

Feat/expose kagent agents in mcp #1201

Are you sure you want to change the base?

Feat/expose kagent agents in mcp #1201

Conversation

riturajFi commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Title

Summary

What This Enables

New CLI Command

Behavior

Tool Model

Tool Naming

Tool Description

Tool Inputs

Runtime Flow

Startup

Tool Invocation

Implementation Notes

Command Wiring

MCP Server

Agent Discovery

Error Handling

Scope and Non-Goals

In Scope

Out of Scope

Files Changed

How to Test (End-to-End)

1. Start kagent backend (one-time)

2. Build the CLI

3. MCP handshake + tool discovery

4. Invoke a real agent via MCP

Result

Uh oh!

riturajFi commented Jan 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

supreme-gg-gg left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

riturajFi commented Jan 13, 2026

Uh oh!

supreme-gg-gg left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

riturajFi commented Jan 14, 2026

Uh oh!

EItanya left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

EItanya commented Jan 15, 2026

Uh oh!

riturajFi commented Jan 12, 2026 •

edited

Loading

riturajFi commented Jan 12, 2026 •

edited

Loading

supreme-gg-gg left a comment •

edited

Loading

supreme-gg-gg left a comment •

edited

Loading