# MCP Tools in Context Hub: A Complete Guide to AI Agent Integration

> Discover MCP tools within Context Hub and learn how this AI agent integration gateway leverages JSON-RPC for seamless programmatic control over content registry operations.

- Repository: [Andrew Ng/context-hub](https://github.com/andrewyng/context-hub)
- Tags: deep-dive
- Published: 2026-03-20

---

**TL;DR:** Context Hub ships with a built-in **MCP (Model Context Protocol)** server that exposes core CLI operations—search, retrieval, listing, annotation, and feedback—as JSON-RPC tools, enabling AI agents like Claude Code and Cursor to interact programmatically with the hub's content registry.

The **andrewyng/context-hub** repository extends its command-line interface with a dedicated MCP server located in `cli/src/mcp/`. These **MCP tools** transform local Context Hub operations into standardized, agent-friendly endpoints, allowing external AI systems to query documentation and manage context without invoking shell commands directly.

## What Are MCP Tools in Context Hub?

**MCP tools** are JSON-RPC methods registered by the Context Hub MCP server that mirror the functionality of the `chub` CLI. When an AI assistant connects to the server via stdio transport, it can invoke these tools to search the registry, retrieve specific documents, list available content, add annotations, or submit feedback. Each tool is defined in [`cli/src/mcp/server.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/server.js) and implemented by handler functions in [`cli/src/mcp/tools.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/tools.js), reusing the core library logic found in `cli/src/lib/*`.

## MCP Server Architecture

### Core Server Components

The MCP server architecture centers on three primary components from the `@modelcontextprotocol/sdk`:

- **`McpServer`** (`@modelcontextprotocol/sdk/server/mcp.js`) – The core JSON-RPC server that receives tool calls over stdio or other transports.
- **`StdioServerTransport`** – Connects the server to the process's stdin/stdout, creating a simple pipe for agent communication.
- **`attachStdioShutdownHandlers`** (in [`cli/src/mcp/stdio-lifecycle.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/stdio-lifecycle.js)) – Ensures clean server termination when the host closes the stdio stream, critical for long-running agent sessions.

### Tool Registration and Validation

In [`cli/src/mcp/server.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/server.js), each tool is registered using the `server.tool()` method, which declares:
- A unique tool name (e.g., `chub_search`, `chub_get`)
- A descriptive text for AI agents
- **Zod-validated** argument schemas for type safety
- A handler function reference imported from [`cli/src/mcp/tools.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/tools.js)

### Handler Implementation

The actual business logic resides in [`cli/src/mcp/tools.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/tools.js). Five primary handlers implement the tool interfaces:
- `handleSearch` – Queries the Context Hub registry
- `handleGet` – Retrieves specific document content
- `handleList` – Lists available contexts or categories
- `handleAnnotate` – Adds user notes to documents
- `handleFeedback` – Submits usage feedback

These handlers reuse existing CLI library functions and format responses using `textResult()` or `errorResult()` helpers to ensure MCP-compliant output.

## Available MCP Tools and Handlers

Context Hub exposes five distinct MCP tools that map directly to common CLI workflows:

| Tool Name | Handler Function | Description |
|-----------|-----------------|-------------|
| `chub_search` | `handleSearch` | Searches the hub for documents matching a query string |
| `chub_get` | `handleGet` | Retrieves full or partial content for a specific document ID |
| `chub_list` | `handleList` | Lists available documents, categories, or collections |
| `chub_annotate` | `handleAnnotate` | Attaches persistent notes to specific document IDs |
| `chub_feedback` | `handleFeedback` | Submits structured feedback about document quality |

Each handler validates input parameters using Zod schemas defined during registration in [`cli/src/mcp/server.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/server.js), then delegates to the shared library modules in `cli/src/lib/*` for data retrieval and storage operations.

## How to Use MCP Tools in Practice

### Starting the MCP Server

The simplest way to launch the server is via the dedicated binary:

```bash
./cli/bin/chub-mcp

```

This executable runs [`cli/src/mcp/server.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/server.js), instantiates the `McpServer`, registers all five tools, and attaches the stdio transport. Once started, the server listens for JSON-RPC messages on stdin and writes responses to stdout.

### JSON-RPC Request Format

Agents communicate with the server by sending structured JSON-RPC payloads. To search for "openai chat" documentation:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "chub_search",
  "params": {
    "query": "openai chat",
    "limit": 5
  }
}

```

The server processes this through `handleSearch` in [`cli/src/mcp/tools.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/tools.js) and returns a formatted response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\n  \"results\": [\n    {\"id\":\"openai/chat\",\"name\":\"Chat\",\"type\":\"doc\",\"description\":\"...\"},\n    ...\n  ],\n  \"total\": 42,\n  \"showing\": 5\n}"
      }
    ]
  }
}

```

### Node.js Client Integration

You can programmatically interact with Context Hub MCP tools from Node.js using the official SDK client:

```javascript
import { McpClient } from '@modelcontextprotocol/sdk/client/mcp.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { spawn } from 'child_process';

// Spawn the server process
const proc = spawn('node', ['./cli/bin/chub-mcp']);
const transport = new StdioClientTransport(proc.stdin, proc.stdout);

const client = new McpClient({ transport });

// Search for documentation
const searchRes = await client.call('chub_search', { query: 'stripe api' });
console.log(searchRes.content[0].text);

// Retrieve full document content
const getRes = await client.call('chub_get', { id: 'stripe/api', full: true });
console.log(getRes.content[0].text);

// Add an annotation
await client.call('chub_annotate', {
  id: 'openai/chat',
  note: 'Remember to add latest rate-limit info.'
});

```

This approach uses the same method names (`chub_search`, `chub_get`, `chub_annotate`) that the server registers in [`cli/src/mcp/server.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/server.js), ensuring protocol compatibility.

## Summary

- **MCP tools** in Context Hub are JSON-RPC methods exposed through a built-in MCP server located in `cli/src/mcp/`.
- The server uses **stdio transport** (`StdioServerTransport`) to communicate with AI agents via stdin/stdout pipes.
- Five core tools—`chub_search`, `chub_get`, `chub_list`, `chub_annotate`, and `chub_feedback`—mirror the CLI functionality.
- Tool handlers are implemented in [`cli/src/mcp/tools.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/tools.js) and reuse logic from `cli/src/lib/*`.
- The `chub-mcp` binary (`cli/bin/chub-mcp`) provides a zero-configuration entry point for starting the server.

## Frequently Asked Questions

### What protocol do Context Hub MCP tools use?

Context Hub MCP tools use the **Model Context Protocol (MCP)**, a JSON-RPC-based standard designed specifically for AI agent communication. The server implementation in [`cli/src/mcp/server.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/server.js) leverages the official `@modelcontextprotocol/sdk` to handle message serialization, tool routing, and schema validation.

### How do I run the Context Hub MCP server locally?

Execute the `chub-mcp` binary located at `cli/bin/chub-mcp` from the repository root. This script initializes the `McpServer` defined in [`cli/src/mcp/server.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/server.js), registers all available tools, and connects the stdio transport. The server runs persistently until the parent process closes the stdin stream, at which point `attachStdioShutdownHandlers` triggers graceful termination.

### Can I use Context Hub MCP tools with Cursor or Claude Code?

Yes. Any MCP-compatible AI assistant—including Claude Code, Cursor, or other agents supporting the Model Context Protocol—can connect to the Context Hub server. Configure your agent to spawn the `chub-mcp` process and communicate over stdio; the agent will automatically discover available tools like `chub_search` and `chub_get` through the MCP capability exchange.

### Where are the MCP tool handlers implemented?

The handler logic for all five MCP tools resides in [`cli/src/mcp/tools.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/tools.js). This module exports `handleSearch`, `handleGet`, `handleList`, `handleAnnotate`, and `handleFeedback`, which are imported and bound to tool names in [`cli/src/mcp/server.js`](https://github.com/andrewyng/context-hub/blob/main/cli/src/mcp/server.js). Each handler calls into the shared library modules (`cli/src/lib/*`) to perform the actual registry operations and context management.