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#

1. Install kagent in a Kubernetes cluster. If you haven't done this yet, check out the installation guide or the quickstart guide.

2. Make sure that you have the kagent custom resources in your cluster.

   kubectl get crd | grep kagent.dev

Creating an agent#

To create an agent, follow the Your First Agent guide.

Take a look at the Agent custom resource for your first agent, such as with the following command.

kubectl get agent my-first-k8s-agent -n kagent -o yaml

Example output: Pay attention to the following details:

• The type field is set to Declarative. This means that the agent is using a declarative model configuration and system message, as opposed to BYO where you can bring your own agent configuration separately.
• The declarative field contains the model configuration and system message.
• The systemMessage field contains the system message that the agent will use. 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.
• The tools field contains the tools that the agent can run to interact with the environment. The tools refer to a RemoteMCPServer, because these tools are built in to kagent. However, you can also create your own MCPServer or regular Kubernetes Service and designate the Service as for MCP use.
• The status shows that the agent is accepted and ready.

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  creationTimestamp: "2025-08-13T18:05:07Z"
  generation: 1
  name: my-first-k8s-agent
  namespace: kagent
spec:
  description: This agent can interact with the Kubernetes API to get information
    about the cluster.
  type: Declarative
  declarative: 
    modelConfig: default-model-config
    systemMessage: |-
      You're a friendly and helpful agent that uses Kubernetes tools to answer users 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
        If you are unable to help, or something goes wrong, refer the user to https://kagent.dev for more information or support.
  
      # 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:
    - mcpServer:
        apiGroup: kagent.dev
        kind: RemoteMCPServer
        name: kagent-tool-server
        toolNames:
        - k8s_get_available_api_resources
      type: McpServer
    - mcpServer:
        apiGroup: kagent.dev
        kind: RemoteMCPServer
        name: kagent-tool-server
        toolNames:
        - k8s_get_resources
      type: McpServer
status:
  conditions:
  - lastTransitionTime: "2025-08-13T18:05:07Z"
    message: ""
    reason: AgentReconciled
    status: "True"
    type: Accepted
  - lastTransitionTime: "2025-08-13T18:05:23Z"
    message: Deployment is ready
    reason: DeploymentReady
    status: "True"
    type: Ready
  configHash: 297ryAv8Xqp/ib2XUWNeDphuiqwA1wk7DAxt+E1vQhQ=
  observedGeneration: 1

Configuring MCP tools#

Now that you've reviewed an existing agent that uses MCP tools, let's create our own from scratch.

The following example creates an agent that can retrieve information from a website. You create a simple MCP example server that only has one tool, the fetch tool. The fetch tool takes a URL as input and returns the contents of the page.

1. Create an MCPServer resource with kmcp for the fetch tool.

   kubectl apply -f - <<EOF
   apiVersion: kagent.dev/v1alpha1
   kind: MCPServer
   metadata:
     name: mcp-website-fetcher
     namespace: kagent
   spec:
     deployment:
       args:
       - mcp-server-fetch
       cmd: uvx
       port: 3000
     stdioTransport: {}
     transportType: stdio
   EOF

2. Create an Agent resource. Note that in the tools section, you refer to the MCPServer that you just created. One tool is included, the fetch tool. Even if the MCP server has multiple tools, you can decide which tools to include for this particular agent. The tool takes a single input parameter: the URL to fetch. You do not have to include the input schema, however. Kagent automatically discovers the input schema from the tool itself.

   kubectl apply -f - <<EOF
   apiVersion: kagent.dev/v1alpha2
   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.
     type: Declarative
     declarative:
       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:
           name: mcp-website-fetcher
           kind: MCPServer
           toolNames:
           - fetch
   EOF

Testing the agent with the MCP tool#

Now let's try our agent out with the fetch tool.

1. Open the kagent dashboard.

   kagent dashboard

2. Select the simple-fetch-agent that you just created. Under Agent Details, you see the fetch tool.

3. In the chat box, enter "Show me the contents of the https://en.wikipedia.org/wiki/Service_mesh website?" and click Send. The agent responds with the contents of the website.

Next Steps#

• Learn more about Core Concepts
• Join our Community