Setting Up the kcmd MCP Server with Gemini CLI for Metadata Management in Agentic Workflows

The kcmd CLI in the GoogleCloudPlatform/knowledge-catalog repository exposes a Model Context Protocol (MCP) server that enables Gemini-based ADK agents to read and modify Knowledge Catalog metadata through standardized tools like list-entries and modify-entry.

Setting up the kcmd MCP server with Gemini CLI creates a seamless bridge between local metadata snapshots and autonomous agents. The GoogleCloudPlatform/knowledge-catalog repository provides a Metadata-as-Code (MDC) library that functions both as a TypeScript/Node library and as a single-binary CLI. When configured correctly, the kcmd mcp command starts an MCP server that exposes catalog operations as tools consumable by the Google ADK (Agent Development Kit) with Gemini models, enabling fully automated metadata enrichment workflows.

What Is the kcmd MCP Server?

The kcmd MCP server is a specialized sub-command of the kcmd CLI that implements the Model Context Protocol (MCP). This protocol allows autonomous agents to discover and invoke tools exposed by external services. In toolbox/mdcode/src/tool/mcp.ts (lines 11-96), the server instantiates an McpServer, registers catalog-snapshot tools, and connects via stdio transport.

The three primary tools exposed are:

• list-entries – Returns all entries in the loaded catalog snapshot
• lookup-entry – Retrieves specific entry details by identifier
• modify-entry – Updates metadata properties for a given entry

These tools operate on a local CatalogSnapshot loaded from YAML representations, allowing agents to work with Knowledge Catalog metadata offline before pushing changes back to GCP.

Prerequisites

Before configuring the integration, ensure you have:

• Node.js environment with the kcmd CLI built from the repository
• A Google Cloud project with Knowledge Catalog API enabled
• Local directory initialized with kcmd init
• The Google ADK (@google/adk) package installed for your agent

Step-by-Step Setup Guide

Initialize the Local Snapshot

First, create a local representation of your BigQuery dataset or other supported data sources:

# Initialize a local snapshot for a BigQuery dataset

kcmd init --bigquery-dataset my-project.my_dataset

# Pull the latest metadata from Knowledge Catalog

kcmd pull

This creates a catalog.yaml file and associated metadata files in your working directory.

Start the MCP Server

Launch the MCP server from the same binary that handles CLI commands:

# Start the MCP server (exposes catalog tools via stdio)

kcmd mcp --path .

In toolbox/mdcode/src/tool/main.ts (lines 9-70), the CLI entry point parses the mcp sub-command and dispatches to the library function that boots the server. The --path argument specifies the root directory containing your catalog.yaml.

Configure the Gemini ADK Agent

Create an mcp.json configuration file in your tools directory to declare the MCP server:

{
  "mcpServers": {
    "md-fileset": {
      "command": "../dist/md-fileset",
      "args": [ "--dir", "fileset" ]
    }
  }
}

As documented in the toolbox enrichment README (lines 17-24), this configuration tells the ADK agent how to launch and connect to the MCP server binary.

Core Architecture and Source Files

CLI Entry Point (tool/main.ts)

The file toolbox/mdcode/src/tool/main.ts (lines 9-70) serves as the primary entry point for the kcmd binary. It parses commands including init, pull, push, and the critical mcp sub-command. When kcmd mcp is invoked, the CLI initializes the MCP server within the same process.

MCP Server Implementation (tool/mcp.ts)

In toolbox/mdcode/src/tool/mcp.ts (lines 11-96), the server implementation:

1. Creates an McpServer instance
2. Registers the three catalog tools (list-entries, lookup-entry, modify-entry)
3. Establishes stdio transport for communication with the host process
4. Loads the CatalogSnapshot from the specified path

Gemini Agent Integration (agent/enrich/agent.ts)

The file toolbox/enrichment/src/agent/enrich/agent.ts (lines 4-101) demonstrates the consumer side of the architecture. It creates an adk.Agent that uses adk.Gemini as the underlying model and receives the MCP tools via loadMcpTools(). The agent can then invoke catalog operations transparently within its prompt execution loop.

How the Integration Works

The connection between kcmd and Gemini follows a four-step pattern implemented in the agent setup code:

1. Create GCP API Context

const apiContext = kcmd.gcp.ApiContext.default();

The kcmd.gcp.ApiContext.default() method supplies the project and region credentials needed by both the catalog client and the Gemini Vertex AI endpoint.

2. Load the Catalog Snapshot

const snapshot = await kcmd.CatalogSnapshot.fromPath('.', apiContext);

CatalogSnapshot.fromPath() reads the local catalog.yaml representation and validates it against the Knowledge Catalog schema.

3. Instantiate the Gemini Model

const gemini = new adk.Gemini({
  model: 'gemini-2.5-flash',
  vertexai: true,
  project: apiContext.project,
  location: apiContext.location,
});

The adk.Gemini class wraps the Vertex AI Gemini API, using the same project and location context as the catalog operations.

4. Pass MCP Tools to the Agent

const mcpTools = await loadMcpTools('tools');  // reads mcp.json
const agent = new adk.Agent({
  name: 'kcagent-enrich',
  tools: mcpTools,
  model: gemini,
  // ... additional configuration
});

The loadMcpTools() utility (referenced in command.ts) parses the mcp.json configuration and establishes the stdio connection to the running kcmd mcp process. Once registered, the agent can call list-entries, lookup-entry, or modify-entry as if they were native functions.

Complete Agent Setup Example

Here is a minimal, runnable agent configuration based on the enrichment demo:

import * as adk from '@google/adk';
import * as kcmd from 'kcmd';

async function createAgent() {
  // Load GCP context and the catalog snapshot
  const apiContext = kcmd.gcp.ApiContext.default();
  const snapshot = await kcmd.CatalogSnapshot.fromPath('.', apiContext);

  // Create a Gemini model
  const gemini = new adk.Gemini({
    model: 'gemini-2.5-flash',
    vertexai: true,
    project: apiContext.project,
    location: apiContext.location,
  });

  // Register MCP tools (list-entries, lookup-entry, modify-entry)
  const mcpTools = await loadMcpTools('tools');

  // Build the agent (lines 89-107 in agent.ts)
  return new adk.Agent({
    name: 'kcagent-enrich',
    description: 'Enriches Knowledge Catalog metadata via MCP tools.',
    instruction: 'Analyze the catalog entries and suggest metadata improvements.',
    tools: mcpTools,
    model: gemini,
  });
}

When the agent executes, it receives a JSON response from the MCP tools containing catalog entry names and metadata, which it can then process to generate enrichment recommendations.

Summary

• kcmd CLI provides a unified binary for metadata operations and MCP server functionality via the kcmd mcp command.
• MCP tools (list-entries, lookup-entry, modify-entry) expose Knowledge Catalog operations as standardized JSON-RPC endpoints.
• Source locations: CLI entry point is in toolbox/mdcode/src/tool/main.ts, while the MCP implementation resides in toolbox/mdcode/src/tool/mcp.ts.
• Gemini integration uses adk.Gemini with Vertex AI configuration shared via kcmd.gcp.ApiContext.
• Agent setup requires loading the CatalogSnapshot, instantiating the model, and passing tools via loadMcpTools() as shown in toolbox/enrichment/src/agent/enrich/agent.ts.

Frequently Asked Questions

What is the Model Context Protocol (MCP) used by kcmd?

The Model Context Protocol is an open standard that allows AI agents to discover and invoke external tools through a standardized JSON-RPC interface. In the Knowledge Catalog repository, the kcmd binary implements MCP to expose catalog operations—such as listing or modifying entries—as tools that Gemini-based agents can call natively during prompt execution.

How do I configure the MCP server connection for the Gemini CLI?

Connection configuration happens through an mcp.json file placed in your tools directory. This JSON file declares which MCP server binaries to launch, including the path to the kcmd binary and any required arguments like --dir or --path. The loadMcpTools() utility function reads this configuration and manages the stdio transport connection between the agent and the kcmd process.

Can the kcmd MCP server modify BigQuery metadata directly?

No, the MCP server operates on a local CatalogSnapshot loaded from YAML files. When you run kcmd init and kcmd pull, you create a local representation of your BigQuery dataset or other data sources. The agent modifies this local snapshot via the modify-entry tool. You must explicitly run kcmd push to synchronize these changes back to the actual BigQuery metadata or Knowledge Catalog service.

Which Gemini model versions work with the kcmd MCP integration?

The implementation in toolbox/enrichment/src/agent/enrich/agent.ts supports any Gemini model available through Vertex AI by configuring the adk.Gemini class with vertexai: true. The example code uses gemini-2.5-flash, but you can substitute other model identifiers supported by your GCP project and region, provided they are compatible with the Google ADK tool-calling capabilities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}