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

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 and implemented by handler functions in 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) – 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, 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

Handler Implementation

The actual business logic resides in 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, 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:

./cli/bin/chub-mcp

This executable runs 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:

{
  "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 and returns a formatted response:

{
  "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:

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, 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 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 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, 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. This module exports handleSearch, handleGet, handleList, handleAnnotate, and handleFeedback, which are imported and bound to tool names in 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.

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