Integrating Knowledge Catalog MCP Tools into Multi-Agent AI Systems

The Knowledge Catalog MCP server exposes catalog operations as standard MCP tools that any compatible agent can invoke to read, query, or modify metadata from a local snapshot without writing custom HTTP clients.

The GoogleCloudPlatform/knowledge-catalog repository provides a production-ready Model Context Protocol (MCP) implementation that bridges Google Cloud Knowledge Catalog metadata with AI agent workflows. By exposing catalog operations through standardized MCP tools, the kcmd CLI enables seamless integration into multi-agent architectures where different agents discover, analyze, and govern data assets through a common, language-agnostic interface.

How the Knowledge Catalog MCP Server Works

The MCP server implementation resides in toolbox/mdcode/src/tool/mcp.ts, where the McpServer class registers available tools and handles request/response cycles according to the MCP specification. The server uses StdioServerTransport to communicate over stdin/stdout, allowing it to run as a subprocess that any parent process can launch and control.

When you invoke kcmd mcp (implemented in toolbox/mdcode/src/tool/main.ts), the server initializes a CatalogSnapshot instance from toolbox/mdcode/src/libts/catalog_snapshot.ts. This snapshot loads a local directory tree of YAML and Markdown files representing your catalog metadata, providing high-level operations including listEntries(), lookupEntry(), updateEntry(), pull(), and push().

Authentication flows through gcp.ApiContext in toolbox/mdcode/src/libts/gcp.ts, which automatically picks up Google Cloud credentials from gcloud auth application-default login. This ensures secure access to remote catalog services without embedding service account keys in your agent configuration.

Available MCP Tools and Input Schemas

The server exposes four primary tools that follow the MCP specification for structured inputs and outputs:

• list-entries: Returns a JSON array of all entry names in the loaded snapshot. Requires no input parameters.
• lookup-entry: Retrieves complete metadata for a specific entry. Requires input schema { "name": "string" }.
• modify-entry: Updates either the resource block or specific aspects of an entry. Requires input schema { "name": "string", "field": "string", "updates": "Record<string, any>" }.
• pull and push: Synchronize the local snapshot with the remote Knowledge Catalog service. These expose the snapshot's pull() and push() methods as callable MCP tools.

Because these tools follow the MCP spec, any agent capable of consuming MCP-formatted tool definitions—including the Gemini CLI, Claude Desktop, or custom agents built with the @modelcontextprotocol SDK—automatically gains Knowledge Catalog capabilities.

Configuring the MCP Server for Agent Integration

To integrate the server into your agent system, first create a local catalog snapshot using kcmd init or check out an existing snapshot repository. Then add the following configuration to your agent's MCP settings:

{
  "mcpServers": {
    "knowledge-catalog": {
      "command": "kcmd",
      "args": ["mcp", "--path", "/absolute/path/to/catalog-snapshot"]
    }
  }
}

The stdio transport ensures the server runs efficiently as a child process, consuming minimal resources while maintaining persistent access to the loaded snapshot. This architecture keeps agent startup times low and eliminates network configuration complexity since communication happens through standard file descriptors.

Implementing Multi-Agent Workflows

Multi-agent systems leverage different tool combinations to orchestrate complex data governance tasks. Below are implementation patterns for Python and TypeScript agents interacting with the Knowledge Catalog MCP server.

Python Agent Implementation

Using the @modelcontextprotocol Python SDK, agents can discover and modify catalog entries programmatically:

from modelcontextprotocol.sdk.client import McpClient

client = McpClient(server="knowledge-catalog")

# Discovery phase: List all available entries

entries = client.call_tool("list-entries")
print("Available datasets:", entries["content"][0]["text"])

# Analysis phase: Retrieve specific entry metadata

entry = client.call_tool("lookup-entry", {"name": "products"})
schema = entry["content"][0]["text"]

# Governance phase: Add compliance tags

client.call_tool(
    "modify-entry",
    {
        "name": "products",
        "field": "overview",
        "updates": {"tags": ["pii-detected", "approved-for-analysis"]},
    }
)

# Push changes to cloud catalog

client.call_tool("push")

TypeScript Direct Integration

For TypeScript agents, you can bypass the MCP abstraction and call the snapshot library directly, though the MCP approach remains preferred for consistency:

import * as kcmd from "kcmd";
import * as gcp from "kcmd/libts/gcp";

async function catalogAgent() {
  const ctx = gcp.ApiContext.default();
  const snap = await kcmd.CatalogSnapshot.fromPath("/path/to/snapshot", ctx);
  
  const names = await snap.listEntries();
  const entry = await snap.lookupEntry("products");
  
  await snap.updateEntry(
    { 
      name: "products", 
      type: entry.type, 
      aspects: { overview: { tags: ["processed"] } } 
    },
    ["overview"]
  );
  
  await snap.push();
}

Typical Multi-Agent Orchestration

In production environments, specialized agents collaborate through the same MCP server instance:

1. Discovery Agent: Calls list-entries to enumerate available datasets and filter by tags.
2. Analysis Agent: Receives entry names and calls lookup-entry to fetch schemas, then generates SQL or documentation.
3. Governance Agent: Invokes modify-entry to attach compliance metadata or deprecation notices, followed by push to propagate changes to the cloud catalog.

This decoupled architecture ensures each agent focuses on a single responsibility while the MCP server maintains consistent state management and authentication.

Summary

• The Knowledge Catalog MCP server in toolbox/mdcode/src/tool/mcp.ts exposes catalog operations as standard MCP tools over stdio transport.
• Four primary tools—list-entries, lookup-entry, modify-entry, and pull/push—enable complete read/write workflows against local snapshots.
• The CatalogSnapshot class in toolbox/mdcode/src/libts/catalog_snapshot.ts handles local metadata operations, while gcp.ApiContext manages Google Cloud authentication.
• Any MCP-compatible agent can integrate by adding a server configuration pointing to kcmd mcp --path <snapshot>, eliminating the need for custom HTTP clients or SDK dependencies.
• Multi-agent systems can distribute tasks across discovery, analysis, and governance agents, all communicating through the same MCP interface.

Frequently Asked Questions

What is the Model Context Protocol (MCP) and why does it matter for Knowledge Catalog?

The Model Context Protocol is an open standard that allows AI systems to expose tools and resources through a consistent interface. For Knowledge Catalog, MCP matters because it decouples metadata operations from specific programming languages or frameworks, allowing any MCP-compatible agent—whether built with Python, TypeScript, or Go—to discover and manage data assets without learning proprietary APIs.

How do I authenticate the MCP server with Google Cloud?

The server uses the gcp.ApiContext class from toolbox/mdcode/src/libts/gcp.ts to automatically resolve credentials via Application Default Credentials. Run gcloud auth application-default login before starting the MCP server, and the kcmd binary will automatically propagate those credentials to the underlying Knowledge Catalog API calls.

Can I use the MCP server with programming languages other than Python or TypeScript?

Yes. Because the server communicates over stdin/stdout using the standard MCP JSON protocol, you can launch it as a subprocess from any language that supports process spawning and JSON serialization, including Go, Rust, Java, or Ruby. Simply start the process with kcmd mcp --path <snapshot> and write MCP-formatted JSON-RPC messages to its stdin.

How does the MCP server handle synchronization with the remote Knowledge Catalog?

The server exposes pull and push tools that map directly to the CatalogSnapshot.pull() and CatalogSnapshot.push() methods in toolbox/mdcode/src/libts/catalog_snapshot.ts. The pull operation fetches the latest metadata from the cloud catalog into your local snapshot, while push uploads local modifications. These operations ensure agents work against consistent local state while maintaining synchronization with the central Knowledge Catalog service.

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