# How to Implement New MCP Tools in the Claude-Mem Plugin Framework

> Learn to implement new MCP tools in the Claude-Mem plugin framework. Define tool schemas and create HTTP endpoints to handle your tool's business logic.

- Repository: [Alex Newman/claude-mem](https://github.com/thedotmack/claude-mem)
- Tags: how-to-guide
- Published: 2026-02-16

---

**To implement new MCP tools in the Claude-Mem plugin framework, define a tool schema in the MCP server's tools array and implement a corresponding Worker HTTP endpoint that handles the business logic.**

The Claude-Mem plugin framework exposes its Memory-Context Protocol (MCP) through a lightweight HTTP wrapper, allowing developers to extend functionality by adding new tools. This guide walks through the exact implementation pattern used in the `thedotmack/claude-mem` repository, referencing specific source files and line numbers to ensure technical accuracy.

## Understanding the MCP Architecture in Claude-Mem

The framework separates concerns between the MCP protocol layer and business logic execution. This separation allows tools to remain portable while the heavy processing occurs in a dedicated Worker process.

### The MCP Server Wrapper

The MCP server implementation lives in [`src/servers/mcp-server.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/servers/mcp-server.ts). This file defines the **tools array** starting at line 57, where each tool is registered as an object containing `name`, `description`, `inputSchema`, and `handler` properties.

The server registers two critical request handlers:
- **`ListToolsRequestSchema`** (line 57-66): Returns the complete tool catalogue to clients
- **`CallToolRequestSchema`** (line 88-98): Receives tool invocations, looks up the requested tool in the array, and executes its `handler` function

Before accepting requests, the server verifies Worker availability through `verifyWorkerConnection()` at lines 42-50, ensuring the HTTP API is ready to receive forwarded requests.

### The Worker HTTP API

The Worker process, managed by [`src/services/worker-service.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts), exposes an independent HTTP API where actual tool logic executes. Routes are organized under `src/services/worker/*`, with each domain (search, observations, etc.) having its own subdirectory.

When an MCP tool's `handler` executes, it simply forwards arguments to the Worker via HTTP GET or POST requests, then returns the Worker's response to the MCP client.

## Step-by-Step Guide to Implement New MCP Tools

Adding a new tool requires modifications to both the MCP server definition and the Worker API implementation.

### Step 1: Define the MCP Tool Schema

Edit [`src/servers/mcp-server.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/servers/mcp-server.ts) to add a new entry to the tools array. Each tool requires:

- **name**: Unique identifier using snake_case
- **description**: Clear explanation of functionality for LLM context
- **inputSchema**: JSON Schema defining required parameters
- **handler**: Async function forwarding to Worker API

```typescript
// src/servers/mcp-server.ts (add to tools array)
{
  name: 'summarize_observation',
  description: 'Generate a concise TL;DR for a single observation ID.',
  inputSchema: {
    type: 'object',
    properties: {
      id: { 
        type: 'number', 
        description: 'Observation ID to summarize' 
      }
    },
    required: ['id'],
    additionalProperties: false
  },
  handler: async (args: any) => {
    return await callWorkerAPIPost('/api/observations/summarize', args);
  }
}

```

### Step 2: Implement the Worker Endpoint

Create or modify files in `src/services/worker/` to handle the business logic. The endpoint should parse incoming requests, execute database queries or external calls, and return properly formatted MCP content.

```typescript
// src/services/worker/observations/summarize.ts
import { Router } from 'express';
import { getDb } from '../../infrastructure/Database.js';
import { logger } from '../../utils/logger.js';

export const router = Router();

router.post('/api/observations/summarize', async (req, res) => {
  const { id } = req.body;
  const db = await getDb();
  const obs = await db.getObservation(id);
  
  if (!obs) {
    return res.status(404).json({ error: 'Observation not found' });
  }

  // Simple summarization – replace with LLM call if desired
  const summary = obs.text.slice(0, 200) + 
    (obs.text.length > 200 ? '…' : '');
  
  logger.info('WORKER', 'Summarized observation', { id });
  
  res.json({ 
    content: [{ type: 'text', text: summary }] 
  });
});

```

### Step 3: Register the Route in the Worker Server

Import and mount the new router in the main Worker server file to activate the endpoint.

```typescript
// src/services/worker/WorkerServer.ts
import { router as summarizeRouter } from './observations/summarize.js';

// Add to existing app configuration
app.use(summarizeRouter);

```

## Complete Implementation Example

The following pattern demonstrates the full flow for implementing a custom search tool that queries vector embeddings:

**MCP Tool Definition** ([`src/servers/mcp-server.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/servers/mcp-server.ts)):

```typescript
{
  name: 'semantic_search',
  description: 'Search observations using vector similarity against a query string.',
  inputSchema: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'Search query text' },
      limit: { type: 'number', description: 'Max results to return', default: 5 }
    },
    required: ['query']
  },
  handler: async (args) => {
    return await callWorkerAPIGet('/api/search/semantic', args);
  }
}

```

**Worker Implementation** ([`src/services/worker/search/semantic.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker/search/semantic.ts)):

```typescript
import { Router } from 'express';
import { getVectorStore } from '../../infrastructure/VectorStore.js';

export const router = Router();

router.get('/api/search/semantic', async (req, res) => {
  const { query, limit = 5 } = req.query;
  const store = await getVectorStore();
  const results = await store.similaritySearch(query as string, Number(limit));
  
  res.json({
    content: results.map(r => ({
      type: 'text',
      text: `[Score: ${r.score}] ${r.text}`
    }))
  });
});

```

## Key Files and Their Roles

Understanding the codebase structure ensures you modify the correct files when extending functionality:

- **[`src/servers/mcp-server.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/servers/mcp-server.ts)** – Core MCP protocol wrapper; defines the `tools` array (lines 57-66) and RPC handlers (lines 88-98). Contains `verifyWorkerConnection()` (lines 42-50) for health checks.
- **[`src/services/worker-service.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts)** – Manages the Worker process lifecycle and exposes the HTTP API that MCP tools consume.
- **`src/services/worker/*`** – Domain-specific business logic implementations (e.g., `search/`, `observations/`). New tool logic belongs here.
- **[`src/utils/logger.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/utils/logger.ts)** – Centralized logging utility used across MCP server and Worker processes to trace tool execution.

## Summary

- **Claude-Mem** exposes MCP tools through a thin HTTP wrapper in [`src/servers/mcp-server.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/servers/mcp-server.ts) that forwards requests to a Worker API.
- To implement new MCP tools, define the tool schema in the MCP server's `tools` array with a `handler` that calls the Worker, then implement the corresponding endpoint in `src/services/worker/`.
- The MCP server handles `ListToolsRequestSchema` (lines 57-66) and `CallToolRequestSchema` (lines 88-98), while the Worker contains all business logic, database queries, and vector search operations.
- This separation keeps the MCP layer portable and stateless while allowing complex operations to run in the dedicated Worker process.

## Frequently Asked Questions

### What is the Memory-Context Protocol (MCP) in Claude-Mem?

The Memory-Context Protocol (MCP) is the interface that allows Claude Code instances to discover and invoke tools provided by the Claude-Mem plugin. According to the `thedotmack/claude-mem` source code, the MCP server implementation in [`src/servers/mcp-server.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/servers/mcp-server.ts) exposes a JSON-RPC interface over HTTP, registering handlers for `ListToolsRequestSchema` and `CallToolRequestSchema` to catalogue and execute tools respectively.

### Do I need to modify the MCP server to add new functionality?

Yes, but only minimally. You must add a new tool definition to the `tools` array in [`src/servers/mcp-server.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/servers/mcp-server.ts) (lines 57-66), specifying the `name`, `description`, `inputSchema`, and a `handler` function. However, the actual business logic should not reside in the MCP server; instead, the handler should forward requests to the Worker HTTP API, keeping the MCP layer thin and protocol-focused.

### How does the MCP server communicate with the Worker process?

The MCP server communicates with the Worker via HTTP requests using helper functions like `callWorkerAPIPost()` and `callWorkerAPIGet()`. Before accepting tool calls, the server verifies the Worker is healthy through `verifyWorkerConnection()` (lines 42-50 in [`src/servers/mcp-server.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/servers/mcp-server.ts)). The Worker process, managed by [`src/services/worker-service.ts`](https://github.com/thedotmack/claude-mem/blob/main/src/services/worker-service.ts), exposes domain-specific endpoints under `src/services/worker/*` that handle database queries, vector searches, and other operations requested by MCP tools.