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

> Learn how to run the Model Context Protocol MCP server with kcmd. Expose Knowledge Catalog operations as tools for AI agents using standard I/O transport. Execute the kcmd mcp command to start.

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

---

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

```bash

# 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:

```typescript
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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/mcp.ts) with CLI entry at [`toolbox/mdcode/src/tool/main.ts`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/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`](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/toolbox/mdcode/src/tool/mcp.ts) at lines 20-92. These tools expose catalog operations to AI agents following the Model Context Protocol specification.