Use kagent to Call an MCP Server over HTTP - Container Service for Kubernetes

kagent provides the RemoteMCPServer custom resource definition (CRD) to connect to remote MCP servers.

HTTP-based MCP protocol

Model Context Protocol (MCP) is a protocol for communication between an AI application and its context sources. MCP supports multiple transport layer mechanisms. The HTTP-based transport provides a standardized solution for communicating with remote servers.

MCP architecture

MCP uses a client-server architecture. Key participants include:

MCP Host: An AI application, such as Claude Code or Claude Desktop, that coordinates and manages one or more MCP clients.
MCP Client: A component that maintains a connection to an MCP server and retrieves context.
MCP Server: A program that provides context to MCP clients.

HTTP transport layer

MCP supports two transport mechanisms:

Stdio transport: Used for local inter-process communication.
Streamable HTTP transport: Uses HTTP POST for client-to-server messaging, with optional Server-Sent Events (SSE) for streaming.

The streamable HTTP transport supports standard HTTP authentication methods, including Bearer tokens, API keys, and custom headers. OAuth is recommended for obtaining authentication tokens.

Core features

MCP defines three types of core primitives that a server can expose:

Tools: Executable capabilities that an AI application can invoke, such as file operations, API calls, or database queries.
Resources: Data sources that provide contextual information, such as file content, database records, or API responses.
Prompts: Reusable templates for interacting with language models.

Connect to an HTTP-based MCP service in kagent

To connect to remote MCP servers, use the RemoteMCPServer custom resource definition (CRD).

Example

apiVersion: kagent.dev/v1alpha2
kind: RemoteMCPServer
metadata:
  name: example-http-mcp-server
  namespace: default
spec:
  description: "Example HTTP-based MCP server"
  protocol: STREAMABLE_HTTP  # Use the HTTP protocol
  url: https://example-mcp-server.com  # MCP server URL
  headersFrom:
  - name: Authorization
    valueFrom:
      secret:
        name: mcp-server-credentials
        key: token
  timeout: 30s
  terminateOnClose: true

Use a RemoteMCPServer in an agent

After you define a RemoteMCPServer, you can use it as a tool source in an Agent:

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: example-agent
  namespace: default
spec:
  declarative:
    systemMessage: "You are an AI assistant that uses external tools."
    tools:
    - type: McpServer
      mcpServer:
        apiGroup: kagent.dev
        kind: RemoteMCPServer
        name: example-http-mcp-server
        toolNames: ["example-tool1", "example-tool2"]  # Specify the tool names to use

Authentication configuration

If your MCP server requires authentication, store the credentials in a Secret:

apiVersion: v1
kind: Secret
metadata:
  name: mcp-server-credentials
  namespace: default
data:
  token: <base64-encoded-api-key>

Then, reference it in the RemoteMCPServer.

Example using valueFrom.secret:

...
spec:
  headersFrom:
  - name: Authorization
    valueFrom:
      secret:
        name: mcp-server-credentials
        key: token

Example using valueFrom.configMap:

...
spec:
  headersFrom:
  - name: X-API-Key
    valueFrom:
      configMap:
        name: mcp-config
        key: api-key

This approach integrates HTTP-based MCP servers into kagent, providing your AI application with rich context and powerful tools.