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

> Set up the kcmd MCP server with Gemini CLI for efficient metadata management in agentic workflows. Easily list and modify Knowledge Catalog metadata using standardized ADK agent tools.

- Repository: [Google Cloud Platform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog)
- Tags: how-to-guide
- Published: 2026-07-14

---

**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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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:

```bash

# 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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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:

```bash

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

kcmd mcp --path .

```

In [`toolbox/mdcode/src/tool/main.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/catalog.yaml).

### Configure the Gemini ADK Agent

Create an [`mcp.json`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/mcp.json) configuration file in your tools directory to declare the MCP server:

```json
{
  "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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/tool/main.ts))

The file [`toolbox/mdcode/src/tool/main.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/tool/mcp.ts))

In [`toolbox/mdcode/src/tool/mcp.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/agent/enrich/agent.ts))

The file [`toolbox/enrichment/src/agent/enrich/agent.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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**

```typescript
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**

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

```

`CatalogSnapshot.fromPath()` reads the local [`catalog.yaml`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/catalog.yaml) representation and validates it against the Knowledge Catalog schema.

**3. Instantiate the Gemini Model**

```typescript
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**

```typescript
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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/command.ts)) parses the [`mcp.json`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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:

```typescript
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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/main.ts), while the MCP implementation resides in [`toolbox/mdcode/src/tool/mcp.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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.