Build and test Model Context Protocol servers

Overview

The Model Context Protocol (MCP) lets AI assistants call your tools and read your resources. The mcp module provides a builder pattern for creating MCP servers with Zod-validated inputs.

Building an MCP Server

import { McpServerBuilder } from '@jamaalbuilds/ai-toolkit/mcp';
import { z } from 'zod';

const server = new McpServerBuilder({
  name: 'my-company-tools',
  version: '1.0.0',
});

// Define a tool
server.defineTool({
  name: 'search-docs',
  description: 'Search internal documentation',
  schema: {
    query: z.string().describe('Search query'),
    limit: z.number().default(5).describe('Max results'),
  },
  handler: async ({ query, limit }) => {
    const results = await searchDocs(query, limit);
    return results;
  },
});

// Define a resource
server.defineResource({
  uri: 'config://settings',
  name: 'App Settings',
  description: 'Current application configuration',
  handler: async () => getSettings(),
});

Testing Without a Server

Use McpTestHarness to test tools and resources directly:

const harness = server.createTestHarness();

// Test a tool
const result = await harness.callTool('search-docs', { query: 'vacation policy' });
expect(result.content[0].text).toContain('vacation');

// Test a resource
const config = await harness.readResource('config://settings');
expect(config).toBeDefined();

Connecting to Claude Desktop

Add your MCP server to Claude Desktop's configuration:

{
  "mcpServers": {
    "my-tools": {
      "command": "node",
      "args": ["./dist/mcp-server.js"]
    }
  }
}

Best Practices

• Clear descriptions: The AI uses tool descriptions to decide when to call them
• Zod schemas: Describe every field with .describe() for better AI understanding
• Error handling: Return error text in content, don't throw
• Test first: Use McpTestHarness before deploying