How to Run the Model Context Protocol (MCP) Server with kcmd

Execute kcmd mcp to launch a Model Context Protocol server that exposes Knowledge Catalog operations as tools for AI agents via standard I/O transport.

The kcmd CLI in the GoogleCloudPlatform/knowledge-catalog repository bundles an embedded MCP server that transforms local catalog snapshots into agent-accessible tools. Running the Model Context Protocol (MCP) server with kcmd enables external AI systems to query, modify, and manage catalog entries through a standardized protocol interface.

Understanding the MCP Server Architecture

CLI Entry Point and Command Parsing

The MCP server lifecycle begins in toolbox/mdcode/src/tool/main.ts, where the mcp sub-command is registered and parsed. When you invoke kcmd mcp, the CLI extracts the optional --path argument (defaulting to the current directory .) and passes it to the server starter function at lines 57-63. This design keeps the command-line interface minimal while providing flexibility for targeting different catalog snapshots.

Server Initialization and Transport Setup

The startServer function in toolbox/mdcode/src/tool/mcp.ts orchestrates the server creation. At lines 11-19, it instantiates an McpServer from the official @modelcontextprotocol/sdk and loads a CatalogSnapshot from the supplied path using the internal kcmd library. Between lines 20-92, the server registers specific tools—including list-entries, lookup-entry, and modify-entry—that downstream agents can invoke via the MCP protocol. Finally, at lines 94-96, the server binds to StdioServerTransport, enabling communication over standard input and output streams for easy integration with other processes.

How to Run the MCP Server with kcmd

Command-Line Execution

Run the server from any directory containing a catalog snapshot, or specify a custom path using the --path flag:

# Start the MCP server using the current directory as the catalog root

kcmd mcp

# Specify a different snapshot directory

kcmd mcp --path /path/to/your/catalog-snapshot

Programmatic Integration

You can also launch the server programmatically from TypeScript applications by importing the startServer function:

import { startServer } from 'kcmd/tool/mcp';

// Run the MCP server on the default path ('.')
await startServer();

// Or on a custom path
await startServer('/my/custom/snapshot');

This approach is useful when embedding the Knowledge Catalog MCP server into larger automation workflows or testing environments.

Available Tools and Capabilities

Once running, the MCP server exposes operations defined in toolbox/mdcode/src/tool/mcp.ts (lines 20-92) as protocol-compliant tools. These include entry listing, metadata lookup, and content modification capabilities that AI agents can discover and invoke through the Model Context Protocol. The server relies on types from toolbox/mdcode/src/libts (including CatalogSnapshot and Entry) to ensure type-safe operations against the loaded catalog.

Summary

• Run kcmd mcp to start the Model Context Protocol server instantly from the command line.
• Use --path to target catalog snapshots outside the current working directory.
• Leverages stdio transport via StdioServerTransport for seamless piping and client integration.
• Implements standard MCP according to the official SDK, ensuring compatibility with AI agent frameworks.
• Source located in toolbox/mdcode/src/tool/mcp.ts with CLI entry at toolbox/mdcode/src/tool/main.ts.

Frequently Asked Questions

What is the default catalog path when running kcmd mcp?

The default path is the current directory (.). If you execute kcmd mcp without arguments, the server attempts to load the catalog snapshot from your present working directory. Use --path to specify an alternative location.

Can I run the MCP server programmatically instead of via CLI?

Yes. Import startServer from kcmd/tool/mcp and await the function with an optional path string. This launches the same server instance without requiring shell invocation, making it suitable for automated testing or embedded applications.

What transport protocol does the kcmd MCP server use?

The server uses standard I/O (stdio) transport via StdioServerTransport from the MCP SDK. This allows the server to communicate over stdin/stdout, enabling easy connection to client processes, pipes, and containerized environments without network configuration.

Which tools are available on the MCP server?

The server registers tools including list-entries, lookup-entry, and modify-entry as implemented in toolbox/mdcode/src/tool/mcp.ts at lines 20-92. These tools expose catalog operations to AI agents following the Model Context Protocol specification.

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