Documentation

Adding MCP Tools to Your First Kagent Agent

MCP (Model Context Protocol) tools extend the agent's abilities by calling external services to perform tasks that require logic or access outside the cluster.

In this guide, you'll learn how to add an MCP tool to your first AI agent using the kagent resources.

Prerequisites

Before you begin make sure you have a Kubernetes cluster with kagent installed. If you haven't done this yet, check out the installation guide or the quickstart guide.

We'll be working with the kagent custom resources, so make sure you have them present on your cluster:

kubectl get crd | grep kagent.dev

Creating the agent

Similar to the first agent guide, we will first create a simple agent that can interact with the cluster. This time we will use the Agent resource to create the agent.

kubectl apply -f - <<EOF
apiVersion: kagent.dev/v1alpha1
kind: Agent
metadata:
  name: simple-k8s-agent
  namespace: kagent
spec:
  description: This agent can interact with the Kubernetes API to get information about the cluster.
  modelConfig: default-model-config
  systemMessage: |-
    You're a friendly and helpful agent that uses Kubernetes tools to answer user questions about the cluster.


    # Instructions


    - If user question is unclear, ask for clarification before running any tools
    - Always be helpful and friendly
    - If you don't know how to answer the question DO NOT make things up
      respond with "Sorry, I don't know how to answer that" and ask the user to further clarify the question


    # Response format
    - ALWAYS format your response as Markdown
    - Your response will include a summary of actions you took and an explanation of the result
  tools:
  - builtin:
      name: kagent.tools.k8s.GetAvailableAPIResources
    type: Builtin
  - builtin:
      name: kagent.tools.k8s.GetResources
    type: Builtin
EOF

Note that the way you structure your instructions is up to you. You can add more details, or simplify them as needed. It's important to make sure the instructions are clear and easy to follow.

We'll leave the default model (GPT-4o) selected and move to the next step.

Adding tools

Tools are the other building block of the agent. They are the commands that the agent can run to interact with the environment. As LLMs don't have the ability to run commands, tools are the way to bridge the gap between the agent and the environment. Kagent provides a set of built-in tools that you can use to interact with Kubernetes, Istio, Prometheus and projects. You can also build your own tools!

In our Agent resource, we added two tools:

  • GetResources, which will enable the agent to run kubectl get command and retrieve resources running in the cluster.
  • GetAvailableAPIResources, which will enable the agent to get a list of available API resources in the cluster.

Test out the agent

Let's test out the agent by asking it a question. First we need to open the kagent dashboard and select the agent we just created. We can either use the kagent CLI tool to open the dashboard or port-forward manually:

kubectl -n kagent port-forward svc/kagent 8001:80
Dashboard showing the discovered agent
Dashboard showing the discovered agent

In the chat interface, type "What pods are running in the cluster?" and press enter. The agent should respond with a list of pods running in the cluster and a call using the GetResources tool.

Dashboard showing the first agent chat
Dashboard showing the first agent chat

Configuring MCP tools

Let's create an agent that uses the MCP tools to retrieve information from a website using the Kagent resources. For this example, we will use a simple MCP example server that only has one tool - the fetch tool. The fetch tool will take a URL as input and return the contents of the page.

First let's apply a simple MCP server that will run in our cluster:

kubectl apply -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-website-fetcher
  namespace: default
  labels:
    app: mcp-website-fetcher
spec:
  replicas: 1
  selector:
    matchLabels:
      app: mcp-website-fetcher
  template:
    metadata:
      labels:
        app: mcp-website-fetcher
    spec:
      containers:
        - name: mcp-website-fetcher
          image: ghcr.io/peterj/mcp-website-fetcher:sha-d2db5b3
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 8000
          resources:
            limits:
              cpu: "500m"
              memory: "256Mi"
            requests:
              cpu: "100m"
              memory: "128Mi"
          livenessProbe:
            httpGet:
              path: /sse
              port: 8000
            initialDelaySeconds: 10
            periodSeconds: 30
---
apiVersion: v1
kind: Service
metadata:
  name: mcp-website-fetcher
spec:
  selector:
    app: mcp-website-fetcher
  ports:
    - port: 80
      targetPort: 8000
  type: ClusterIP
EOF

Now in addition to the Agent resource, we need to define a ToolServer resource:

kubectl apply -f - <<EOF
apiVersion: kagent.dev/v1alpha1
kind: Agent
metadata:
  name: simple-fetch-agent
  namespace: kagent
spec:
  description: This agent can use a single tool to retrieve the contents of a webpage.
  modelConfig: default-model-config
  systemMessage: |-
    You're a friendly and helpful agent that uses the fetch tool to retrieve webpage contents.


    # Instructions


    - If user question is unclear, ask for clarification before running any tools
    - Always be helpful and friendly
    - If you don't know how to answer the question DO NOT make things up
      respond with "Sorry, I don't know how to answer that" and ask the user to further clarify the question


    # Response format
    - ALWAYS format your response as Markdown
    - Your response will include a summary of actions you took and an explanation of the result
  tools:
  - type: McpServer
    mcpServer:
      toolServer: mcp-toolserver
      toolNames:
      - fetch
---
apiVersion: kagent.dev/v1alpha1
kind: ToolServer
metadata:
  name: mcp-toolserver
  namespace: kagent
spec:
  description: Fetches a website and returns its content
  config:
    sse:
      url: http://mcp-website-fetcher.kagent.svc.cluster.local/sse
EOF

MCP tools require a little more additional configuration before they can be used by agents.

You will notice that we're configuring the MCP server by pointing to the URL of the service we just deployed. The tool section defines the tool that the agent will use. In this case, we'll use a tool called fetch that takes a single input parameter - the URL to fetch. The input schema is discovered from the tool itself so you do not need to specify it.

Note that MCP servers can implement multiple tools and as an agent developer you can decide which tools to use.

Testing the agent with the MCP tool

Now let's try our agent out with the new integration. Open the kagent dashboard and select the agent we just created. You should see a new tool appear in the tool list.

Now let's ask our agent a question. Type "Show me the contents of the https://en.wikipedia.org/wiki/Service_mesh website?" and press enter. The agent should respond with the contents of the website.

Dashboard showing the agent chat with MCP tool call
Dashboard showing the agent chat with MCP tool call

Next Steps